iOS SDK インテグレーションガイド
このページでは、Rokt Ecommerce の iOS SDK を実装して、チェックアウト時により関連性の高い顧客体験を提供する方法を説明します。SDK を使用すると、設定されたページで発火し、ユーザーおよびトランザクションデータを Rokt に返すことで、これらの体験(確認ページでのオファー表示など)をトリガーおよび追跡し、パーソナライズおよび測定を行うことができます。
専任のアカウント担当者が、iOS SDK のアカウント設定をサポートします 。彼らは、SDK を初期化するために必要な key と secret、および顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。
これらの指示を完了するには、開発リソースが必要です。追加のサポートが必要な場合は、Rokt のアカウントマネージャーにお問い合わせください。Shopify ストアは、Rokt Ecommerce アプリ を使用して数秒で Rokt プレースメントを設定できます — コーディングは不要です!
1. iOS アプリに Rokt SDK を追加する1. iOS アプリに Rokt SDK を追加する への直接リンク
SPM または CocoaPods のいずれかを使用して 、アプリケーションに Rokt SDK を含めます:
CocoaPodsCocoaPods への直接リンク
CocoaPods を使用して SDK を統合するには、Podfile に次のように指定します:
pod 'mParticle-Apple-SDK', '~> 8.0'
pod 'mParticle-Rokt','~> 8.0'
SPMSPM への直接リンク
Swift Package Manager を使用して SDK を統合するには:
- Xcode でプロジェクトを開き、「Package Dependencies」タブに移動します。
- パッケージリストの下にある + ボタンをクリックします。
- 検索ボックスの右上にリポジトリ URL
https://github.com/mParticle/mparticle-apple-sdkを入力し、パッケージのリストからmparticle-apple-sdkを選択し、「Dependency Rule」を「Up to Next Major Version」に変更します。 - 右下の「Add Package」ボタンをクリックし、「Package Product」として
mParticle-Apple-SDKを選択します。位置情報追跡サポートを含まない SDK バージョンを使用したい場合は、mParticle-Apple-SDK-NoLocationを選択します。 - Rokt Kit リポジトリ URL
https://github.com/mparticle-integrations/mparticle-apple-integration-rokt.gitに対してステップ 3 と 4 を繰り返します。mParticle-Apple-SDK-NoLocationパッケージプロダクトを選択した場合、import mParticle_Apple_SDKの代わりにimport mParticle_Apple_SDK_NoLocationを使用して SDK をインポートする必要があります。
2. Rokt SDK を初期化する2. Rokt SDK を初期化する への直接リンク
SDK を初期化するには、AppDelegate ファイルに次の初期化スニペットを挿入します:
:::注意
your-keyとyour-secretを、専任のRoktチームから提供されたキーとシークレットに置き換えてください。 :::
- Swift
- Objective-C
import mParticle_Apple_SDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
// SDKを初期化する
let options = MParticleOptions(key: "your-key",
secret: "your-secret")
// データ環境をenvironmentで指定する:
// 統合をテスト中の場合は.developmentに設定してください。
// 統合が本番データに対応している場合は.productionに設定してください。
// デフォルトは.autoDetectで、環境を自動的に検出しようとします
options.environment = .development
// 現在のユーザーを識別する:
let identifyRequest = MPIdentityApiRequest.withEmptyUser()
// ハッシュされていないメールアドレスを使用している場合は、'email'に設定してください。
identifyRequest.email = "j.smith@example.com"
// ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定します。
options.identifyRequest = identifyRequest
options.onIdentifyComplete = {(result: MPIdentityApiResult?, error: Error?) in
if let user = result?.user {
user.setUserAttribute("example attribute key", value: "example attribute value")
} else {
//失敗を処理する - 以下の「エラーハンドリング」セクションを参照
}
}
MParticle.sharedInstance().start(with: options)
return true
}
#import <mParticle_Apple_SDK/mParticle.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// SDKを初期化する
MParticleOptions *options = [MParticleOptions optionsWithKey:@"your-key"
secret:@"your-secret"];
// データ環境をenvironmentで指定する:
// 統合をテスト中の場合はMPEnvironmentDevelopmentに設定してください。
// 統合が本番データに対応している場合はMPEnvironmentProductionに設定してください。
// デフォルトはMPEnvironmentAutoDetectで、環境を自動的に検出しようとします
options.environment = MPEnvironmentDevelopment;
// 現在のユーザーを識別する:
// ユーザーのメールアドレスがない場合は、null値を渡すことができます
MPIdentityApiRequest *identifyRequest = [MPIdentityApiRequest requestWithEmptyUser];
// ハッシュされていないメールアドレスを使用している場合は、'email'に設定してください。
identifyRequest.email = @"j.smith@example.com";
options.identifyRequest = identifyRequest;
// ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定します。
options.onIdentifyComplete = ^(MPIdentityApiResult *_Nullable apiResult, NSError *_Nullable error) {
if (apiResult) {
[apiResult.user setUserAttribute:@"example attribute key"
value:@"example attribute value"];
} else {
//失敗を処理する - https://docs.mparticle.com/developers/sdk/ios/idsync/#error-handling を参照
}
};
[[MParticle sharedInstance] startWithOptions:options];
return YES;
}
2.1 初期化時にユーザーを識別する2.1 初期化時にユーザーを識別する への直接リンク
SDKが初期化されると、収集されたデータが正しくユーザーに帰属されるように、またユーザーの行動に基づいて最も関連性の高い広告が表示されるように、現在のユーザーを識別することができます。
SDKの初期化スクリプトには、identifyRequestというオブジェクトが含まれています:
- Swift
- Objective-C
let identifyRequest = MPIdentityApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"
options.identifyRequest = identifyRequest
MPIdentityApiRequest *identifyRequest = [MPIdentityApiRequest requestWithEmptyUser];
identifyRequest.email = @"j.smith@example.com";
options.identifyRequest = identifyRequest;
2.2 追加のユーザー属性を設定する2.2 追加のユーザー属性を設定する への直接リンク
初期化スクリプトには、ユーザーがメールアドレスで正常に識別された場合に、追加のユーザー属性を設定できるコールバック関数が含まれています:
- Swift
- Objective-C
options.onIdentifyComplete = {(result: MPIdentityApiResult?, error: Error?) in
if let user = result?.user {
user.setUserAttribute("example attribute key", value: "example attribute value")
} else {
//失敗を処理する - 下記の「エラーハンドリング」セクションを参照
}
}
options.onIdentifyComplete = ^(MPIdentityApiResult *_Nullable apiResult, NSError *_Nullable error) {
if (apiResult) {
[apiResult.user setUserAttribute:@"example attribute key"
value:@"example attribute value"];
} else {
//失敗を処理する - https://docs.mparticle.com/developers/sdk/ios/idsync/#error-handling を参照
}
};
3. データが利用可能になるとユーザーを識別する3. データが利用可能になるとユーザーを識別する への直接リンク
SDKが初期化された後にユーザーがメールアドレスを提供するたびに(例えば、ログインや購入時)、identifyメソッドを呼び出してメールをRoktに渡すべきです。これにより、データが現在のユーザーに正しく帰属されます。
3.1 identifyRequestを作成する31-identifyrequestを作成する への直接リンク
ユーザーを識別するには、まずユーザーのメールアドレスを含むidentifyRequestオブジェクトを作成します。
ハッシュ化されていないメールアドレスを提供する場合は、以下を使用します:
- Swift
- Objective-C
let identifyRequest = MPIdentityApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"
MPIdentityApiRequest *identifyRequest = [MPIdentityApiRequest requestWithEmptyUser];
identifyRequest.email = @"j.smith@example.com";
3.2 追加のユーザー属性を設定する3.2 追加のユーザー属性を設定する への直接リンク
次に、ユーザーを識別する際にコールバック関数を作成して追加のユーザー属性を設定するオプションがあります。identifyRequestが成功した場合、setUserAttributeで設定したユーザー属性がユーザーに割り当てられます。
- Swift
- Objective-C
let identifyCallback = {(result: MPIdentifyApiResult?) in
if let user = result?.user {
user.setUserAttribute("example attribute key", value: "example attribute value")
}
}
id identityCallback = ^(MPIdentifyApiResult *_Nullable apiResult) {
if (apiResult) {
[apiResult.user setUserAttribute:@"example attribute key"
value:@"example attribute key"];
}
}
3.3 identifyメソッドを呼び出す3.3 identifyメソッドを呼び出す への直接リンク
最後に、identifyRequestとidentityCallbackを作成した後、追加の属性を設定するために、作成したidentifyRequestとidentityCallbackオブジェクトを渡してidentifyメソッドを呼び出します:
- Swift
- Objective-C
MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)
[[[MParticle sharedInstance] identity] identify:identifyRequest completion:identityCallback];
例えば、Jane Smithという名前のユーザーをメールアドレスj.smith@example.comで識別する場合(メールアドレスをハッシュ化する必要はありません)、次 のように使用します。
- Swift
- Objective-C
let identifyRequest = MPIdentityApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"
let identifyCallback = {(result: MPIdentifyApiResult?) in
if let user = result?.user {
user.setUserAttribute("example attribute key", value: "example attribute value")
}
}
MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)
MPIdentityApiRequest *identifyRequest = [MPIdentityApiRequest requestWithEmptyUser];
identifyRequest.email = @"j.smith@example.com";
id identityCallback = ^(MPIdentifyApiResult *_Nullable apiResult) {
if (apiResult) {
[apiResult.user setUserAttribute:@"example attribute key"
value:@"example attribute key"];
}
}
[[[MParticle sharedInstance] identity] identify:identifyRequest completion:identityCallback];
4. ユーザー属性の追跡4. ユーザー属性の追跡 への直接リンク
Rokt SDKを使用して、イベントとは別にユーザー属性を収集することができます。ユーザー属性は、イベントを追跡する際のカスタム属性とは別です。SDKは、特定のセッションで収集されたユーザー属性を、同じセッションでトリガーされたイベントと関連付けます。
ユーザー属性を収集するには、Rokt SDKを初期化した直後、イベントをログに記録する前に、次のコードをアプリで実行する必要があります。
- Swift
- Objective-C
import mParticle_Apple_SDK
// 現在のユーザーを取得します。これは、SDKの初期化時またはidentifyメソッドを呼び出すことによってユーザーを識別した場合にのみ成功します。
let currentUser = MParticle.sharedInstance().identity.currentUser
// 現在のユーザーを`currentUser`に設定した後、次のようにユーザー属性を設定できます。
currentUser?.setUserAttribute("custom-attribute-name", value: "custom-attribute-value")
// 注意: すべてのユーザー属性(リスト属性やタグを含む)は、異なる名前を持たなければなりません。
// Roktは、次のユーザー属性をできるだけ多く設定することを推奨します。
currentUser?.setUserAttribute("firstname", value: "John")
currentUser?.setUserAttribute("lastname", value: "Doe")
// 電話番号は '1234567890' または '+1 (234) 567-8901' の形式でフォーマットできます
currentUser?.setUserAttribute("mobile", value: "3125551515")
currentUser?.setUserAttribute("age", value: "33")
currentUser?.setUserAttribute("gender", value: "M")
currentUser?.setUserAttribute("city", value: "Brooklyn")
currentUser?.setUserAttribute("state", value: "NY")
currentUser?.setUserAttribute("zip", value: "123456")
currentUser?.setUserAttribute("dob", value: "yyyymmdd")
currentUser?.setUserAttribute("title", value: "Mr")
currentUser?.setUserAttribute("language", value: "en")
currentUser?.setUserAttribute("value", value: "52.25")
currentUser?.setUserAttribute("predictedltv", value: "136.23")
// 値のリストを含むユーザー属性を作成することができます
currentUser?.setUserAttributeList("favorite-genres", values: ["documentary", "comedy", "romance", "drama"])
// ユーザー属性を削除するには、removeUserAttributeを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
currentUser?.removeAttribute("attribute-to-remove")
#import <mParticle_Apple_SDK/mParticle.h>
// 現在のユーザーを取得します。これは、SDKの初期化時またはidentifyメソッドを呼び出すことによってユーザーを識別した場合にのみ成功します。
MParticleUser *currentUser = [[[MParticle sharedInstance] identity] currentUser];
// 現在のユーザーを`currentUser`に設定した後、次のようにユーザー属性を設定できます。
[currentUser setUserAttribute:@"custom-attribute-name" value:@"custom-attribute-name"];
// 注意: すべてのユーザー属性(リスト属性やタグを含む)は、異なる名前を持たなければなりません。
// Roktは、次のユーザー属性をできるだけ多く設定することを推奨します。
[currentUser setUserAttribute:@"firstname" value:@"John"];
[currentUser setUserAttribute:@"lastname" value:@"Doe"];
// 電話番号は '1234567890' または '+1 (234) 567-8901' の形式でフォーマットできます
[currentUser setUserAttribute:@"mobile" value:@"3125551515"];
[currentUser setUserAttribute:@"age" value:@"33"];
[currentUser setUserAttribute:@"gender" value:@"M"];
[currentUser setUserAttribute:@"city" value:@"Brooklyn"];
[currentUser setUserAttribute:@"state" value:@"NY"];
[currentUser setUserAttribute:@"zip" value:@"123456"];
[currentUser setUserAttribute:@"dob" value:@"yyyymmdd"];
[currentUser setUserAttribute:@"title" value:@"Mr"];
[currentUser setUserAttribute:@"language" value:@"en"];
[currentUser setUserAttribute:@"value" value:@"52.25"];
[currentUser setUserAttribute:@"predictedltv" value:@"136.23"];
// 値のリストを含むユーザー属性を作成することができます
[currentUser setUserAttribute:@"favorite-genres" values:@[@"documentary", @"comedy", @"romance", @"drama"]];
// ユーザー属性を削除するには、removeUserAttributeを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
[currentUser removeUserAttribute:@"attribute-to-remove"];
5. ファネルイベントのキャプチャ5. ファネルイベントのキャプチャ への直接リンク
Rokt SDKを使用すると、ユーザーがアプリ内でどのように移動するかを記述するデータを収集するためのイベントトラッキングを実装できます。このデータを使用して、ユーザーの体験を最適化することができます。
SDKで記録できる主なイベントタイプは3つあります:
- スクリーンビューイベント: これらはアプリのページが読み込まれたときにトリガーできるイベントです。
- カスタムイベント: アプリに特化した情報を追跡するために作成する自由形式のイベントです。
- コマースイベント: これらはeコマースに特化したイベントで、カートに商品を追加することや最終購入を行うことなど、ショッピング体験のさまざまな段階を説明できます。
Rokt SDKと初めて統合する際は、スクリーンビューのトラッキングを実装することから始めます。カスタムイベントとコマースイベントのトラッキングについては、付録を参照してください。
スクリーンビューのトラッキングスクリーンビューのトラッキン グ への直接リンク
最も基本的なイベントタイプの1つはスクリーンビューです。スクリーンビューを記録するには、.logScreen メソッドを呼び出し、画面の名前を文字列として渡します。
渡す名前は、'homepage' や 'product detail page' などの限られたページセットの1つである必要があります。また、eventInfo 配列に追加のカスタム属性を含めることもできます。
- Swift
- Objective-C
MParticle.sharedInstance().logScreen(
"homepage",
eventInfo: ["custom-attribute": custom-value]
)
[[MParticle sharedInstance] logScreen:@"homepage"
eventInfo:@{@"custom-attribute": customValue}];
6. プレースメントの表示6. プレースメントの表示 への直接リンク
Rokt SDKの主な価値は、selectPlacements メソッドを通じて解放されます。このメソッドは、提供する属性に基づいて顧客に対して非常に関連性の高いプレースメント(またはレイアウト)を提供します。
Roktの統合が初期化されたら、レイアウトがレンダリングされるページから selectPlacements メソッドを呼び出すことができます。ユーザーに最適な体験を提供するために、可能な限り早く、必要な属性がすべて利用可能になった時点で呼び出すべきです。
selectPlacementsを呼び出す際には、少なくとも email、firstname、lastname、billingzipcode、confirmationref の属性を提供して、ユーザーに最も関連性の高いプレースメントを提供する必要があります。
オーバーレイプレースメントオーバーレイプレースメント への直接リンク
- Swift
- Objective-C
import mParticle_Apple_SDK
let attributes = [
"email": "test@gmail.com",
"firstname": "Jenny",
"lastname": "Smith",
"billingzipcode": "07762",
"confirmationref": "54321"
]
MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes)
#import <mParticle_Apple_SDK/mParticle.h>
NSDictionary *attributes = @{
@"email": @"test@gmail.com",
@"firstname": @"Jenny",
@"lastname": @"Smith",
@"billingzipcode": @"07762",
@"confirmationref": @"54321"
};
[[[MParticle sharedInstance] rokt] selectPlacements:@"RoktExperience" attributes:attributes];
また、MPRoktConfig などのオプションパラメータを渡すこともできます。これにより、アプリがダークモードかライトモードかに応じてプレースメントUIをカスタマイズすることができます。埋め込みビューやコールバックなどの追加のオプションパラメータは、以下に示されています。
- Swift
- Objective-C
let roktConfig = MPRoktConfig()
roktConfig.colorMode = .light
MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: nil, callbacks: nil, config: roktConfig)
MPRoktConfig *roktConfig = [[MPRoktConfig alloc] init];
roktConfig.colorMode = MPColorModeLight;
[[MParticle sharedInstance].rokt selectPlacements:@"RoktExperience" attributes:attributes embeddedViews:nil config:roktConfig callbacks:callbacks];
識別子 RoktExperience または埋め込み識別子 RoktEmbedded1 を別の値に更新したい場合は、Roktのアカウントマネージャーに連絡して、Roktのプレースメントが一貫して設定されていることを確認してください。
オプション機能オプション機能 への直接リンク
| 関数 | 目的 |
|---|---|
Rokt.close() | オーバーレイプレースメントを自動で閉じるために使用されます。 |
埋め込みプレースメント埋め込みプレースメント への直接リンク
埋め込みプレースメントは、上記のオーバーレイプレースメントと同じ推奨事項と要件を共有しますが、UIにプレースメントビューを埋め込むことができます。このセクションでは、Roktを通じて許可されるさまざまな高度な機能の例も提供します。
callbacks パラメータを通じてRoktに渡される MPRoktEventCallback クラスは、プレースメントの生成および表示時に発生するさまざまなイベントに応答することを可能にします。
- Swift
- Objective-C
import mParticle_Apple_SDK
let attributes = [
"email": "test@gmail.com",
"firstname": "Jenny",
"lastname": "Smith",
"billingzipcode": "07762",
"confirmationref": "54321"
]
let roktFrame = CGRect(x: 0, y: 0, width: 320, height: 50)
let roktView = MPRoktEmbeddedView(frame: roktFrame)
let embeddedViews = ["RoktEmbedded1": roktView]
let roktConfig = MPRoktConfig()
roktConfig.colorMode = .light
let callbacks = MPRoktEventCallback()
callbacks.onLoad = {
// Roktプレースメントがロードされたときのオプションのコールバック
}
callbacks.onUnLoad = {
// Roktプレースメントがアンロードされたときのオプションのコールバック
}
callbacks.onShouldShowLoadingIndicator = {
// ローディングインジケーターを表示するためのオプションのコールバック
}
callbacks.onShouldHideLoadingIndicator = {
// ローディングインジケーターを非表示にするためのオプションのコールバック
}
callbacks.onEmbeddedSizeChange = { (placement: String, size: CGFloat) in
// プレースメントの高さが変わるたびに、選択されたプレースメントと必要な高さを取得するためのオプションのコールバック
}
MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: embeddedViews, config: roktConfig, callbacks: callbacks)
#import <mParticle_Apple_SDK/mParticle.h>
NSDictionary *attributes = @{
@"email": @"test@gmail.com",
@"firstname": @"Jenny",
@"lastname": @"Smith",
@"billingzipcode": @"07762",
@"confirmationref": @"54321"
};
CGRect roktFrame = CGRectMake(0, 0, 320, 50);
MPRoktEmbeddedView *roktView = [[MPRoktEmbeddedView alloc] initWithFrame:roktFrame];
NSDictionary *embeddedViews = @{@"RoktEmbedded1": roktView};
MPRoktConfig *roktConfig = [[MPRoktConfig alloc] init];
roktConfig.colorMode = MPColorModeLight;
MPRoktEventCallback *callbacks = [[MPRoktEventCallback alloc] init];
callbacks.onLoad = ^{
// Roktプレースメントがロードされたときのオプションのコールバック
};
callbacks.onUnLoad = ^{
// Roktプレースメントがアンロードされたときのオプションのコールバック
};
callbacks.onShouldShowLoadingIndicator = ^{
// ローディングインジケーターを表示するためのオプションのコールバック
};
callbacks.onShouldHideLoadingIndicator = ^{
// ローディングインジケーターを非表示にするためのオプションのコールバック
};
callbacks.onEmbeddedSizeChange = ^(NSString *placement, CGFloat size) {
// プレースメントの高さが変わるたびに、選択されたプレースメントと必要な高さを取得するためのオプションのコールバック
};
[[MParticle sharedInstance].rokt selectPlacements:@"RoktExperience" attributes:attributes embeddedViews:embeddedViews config:roktConfig callbacks:callbacks];
サポートされている属性の完全なリストについては、データ属性を参照してください。
専任のRoktチームが、あなたのブランドとUXスタイルガイドに合わせて配置レイアウトを設定します。