メインコンテンツまでスキップ

Cordova SDK+ 統合ガイド

Platform
Target
For Rokt Ecommerce partners. This complete guide is for ecommerce businesses integrating Rokt into transaction experiences they own. It is not an advertiser implementation guide. Advertisers should use the Rokt Ads integration guides.

このページでは、Rokt Ecommerce Cordova SDK+の実装方法について説明します。SDK+は、設定された画面でユーザーとトランザクションデータをRoktに渡し、Roktが確認画面などで関連するエクスペリエンスを表示できるようにします。

上記のTargetおよびLanguageセレクターを使用して、デプロイメントプラットフォームと従うべきネイティブコード例を選択してください。

1. Add the Rokt SDK+ to Your Cordova App#

SDK+とRoktキットプラグインをインストールします：

Install Cordova plugins
cordova plugin add @mparticle/cordova-sdk
cordova plugin add @mparticle/cordova-rokt-kit

2. Initialize the Rokt SDK+#

各プラットフォームの関連するネイティブエントリーポイントに次の初期化スニペットを挿入します。SDK+は、他のSDK+ API呼び出しの前に初期化する必要があります。your-keyとyour-secretを、Roktチームから提供されたキーとシークレットに置き換えてください。

例アプリで完全な例を見つけることができます。

初期化スニペットを挿入すると、次のカスタマイズ可能なフィールドが表示されます：

1Entering your Rokt key and secret#

your-keyとyour-secretを、Roktアカウントマネージャーから提供された値に設定します。（iOSはoptionsWithKey:secret:を使用します。Androidは.credentials(...)を使用します。）

2Setting your data environment#

テスト中はSDK+環境を開発に設定してデータを開発環境にルーティングし、本番環境に設定してライブ顧客活動を本番に送信します。（iOS: MPEnvironmentDevelopment / MPEnvironmentProduction。Android: MParticle.Environment.Development / MParticle.Environment.Production。）

3Identifying your user and setting attributes#

identifyRequestに、ユーザーの生のハッシュされていないメールを渡します。ハッシュされたメールやその他の識別子については、サポートされているユーザー識別子を参照してください。識別された後、成功コールバックを介して追加のユーザー属性を設定します（iOS: onIdentifyComplete。Android: リクエストをオプションビルダーに接続し、.identify(identifyRequest)を使用して成功リスナーを使用します — パターンについてはステップ3: ユーザーの識別を参照してください）。

注記

初期化スニペットには常にidentifyRequestを含めてください。初期化時にユーザーのメールがない場合は、メールの割り当て（iOS）または.email(...)呼び出し（Android）を省略してください — SDK+はそれでも初期化され、後で3. ユーザーの識別を介してユーザーを識別できます。エラーハンドリングを参照して、識別失敗をどのように処理するかを確認してください — エラーハンドリングがない場合、大規模なデータの一貫性の問題が発生する可能性があります。

AppDelegate initialization (iOS)
#import "AppDelegate.h"
#import "MainViewController.h"
#import "mParticle.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
  MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"your-key"
                                                                 secret:@"your-secret"];
  // Specify the data environment:
  // Set it to MPEnvironmentDevelopment if you are still testing your integration.
  // Set it to MPEnvironmentProduction if your integration is ready for production data.
  // The default is MPEnvironmentAutoDetect which attempts to detect the environment automatically.
  mParticleOptions.environment = MPEnvironmentDevelopment;

  // Identify the current user:
  // If you do not have the user's email address, you can pass in a null value
  MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];

  // Preferred: pass the customer's raw, unhashed email address in 'email'.
  // If you can only provide a SHA-256-hashed email, set it in 'other' instead of email — do not pass both.
  request.email = @"j.smith@example.com";
  // [request setIdentity:@"sha256 hashed email goes here" identityType:MPIdentityOther]; // only if raw email unavailable

  mParticleOptions.identifyRequest = request;
  mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
      if (apiResult) {
          // If the user is identified, set additional user attributes
          [apiResult.user setUserAttribute:@"example attribute key" value:@"example attribute value"];
      }
  };

  [[MParticle sharedInstance] startWithOptions:mParticleOptions];

  self.viewController = [[MainViewController alloc] init];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

3. Identify the User#

SDK+初期化スクリプトは、スクリプトのidentifyRequestオブジェクトに提供された識別子を使用して現在のユーザーを識別します。SDKの初期化後、ユーザーがログイン、ログアウト、または他の識別子を提供するたびに（例：チェックアウト時）、以下に説明する適切な方法を使用してユーザーの識別を同期させる必要があります。

サポートされているユーザー識別子サポートされているユーザー識別子 への直接リンク

サポートされているユーザー識別子を表示
フィールドタイプ説明
emailstring顧客の生のハッシュ化されていないメールアドレスを渡します。
mobilestring顧客の電話番号をE.164形式で渡します。
customeridstring内部の顧客/アカウント識別子を渡します。ログインしているユーザーにはすべての画面で送信します。
otherstringSHA-256ハッシュ化されたメールを渡します。生のメールを提供できない場合のみ使用してください — email と other の両方を渡さないでください。（Androidパスのみ。）
other2stringSHA-256ハッシュ化された携帯番号を渡します。生の携帯番号を提供できない場合のみ使用してください — mobile と other2 の両方を渡さないでください。（Androidパスのみ。）
emailSha256stringSHA-256ハッシュ化されたメールを渡します。生のメールを提供できない場合のみ使用してください — email と emailSha256 の両方を渡さないでください。（iOSパスのみ。）
mobileSha256stringSHA-256ハッシュ化された携帯番号を渡します。生の携帯番号を提供できない場合のみ使用してください — mobile と mobileSha256 の両方を渡さないでください。（iOSパスのみ。）

ユーザーを識別するには:

1Create an identifyRequest object#

ユーザーの識別子を含む identifyRequest オブジェクトを作成します。ユーザーの生のハッシュ化されていないメールアドレスを email フィールドに統合する必要があります。

2Create an identityCallback#

追加のユーザー属性を設定するには、identityCallback を作成します。identifyRequest が成功した場合、コールバック内で設定したユーザー属性は識別されたユーザーに割り当てられます。

3Send the request using the method that matches the user's action#

ユーザーのアクションに一致するメソッドに identifyRequest（およびオプションの identityCallback）を渡します:

  • identity.login: ユーザーがログインまたはアカウントを作成したときに呼び出します。
  • identity.identify: ログイン遷移なしでセッション中にユーザーのメールを取得したときに呼び出します（例：ゲストがチェックアウト時にメールを入力する場合）。
  • identity.logout: ユーザーがログアウトしたときに呼び出します。

これらのメソッドを呼び出すと、SDKの現在のユーザーの状態の記録が遷移します。login と logout メソッドは、Roktのアトリビューションを改善するために対応するイベントも自動的にログに記録します。

例えば、Jane Smithという名前のユーザーを、メールアドレス j.smith@example.com、携帯番号 +13125551515、顧客ID cust_10482 で識別するには:

Identify Jane Smith
// 1. Create the identifyRequest object
var identifyRequest = new mparticle.IdentityRequest();
// Preferred: pass the customer's raw, unhashed email address.
// If you can only provide a SHA-256-hashed email, use setUserIdentity with 'other' instead — do not pass both.
identifyRequest.setEmail('j.smith@example.com');
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other, 'SHA-256 hashed email'); // only if raw email unavailable
// If you can only provide a SHA-256-hashed mobile number, use 'Other2' instead of 'MobileNumber' — do not pass both.
// (Called 'other2' on Android and 'mobileSha256' on iOS; both use this same field.)
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other2, 'SHA-256 hashed mobile number'); // only if raw mobile unavailable
identifyRequest.setUserIdentity(mparticle.UserIdentityType.MobileNumber, '+13125551515');
identifyRequest.setCustomerId('cust_10482');

// 2. Optionally set user attributes once the request succeeds.
var identityCallback = {
  onSuccess: function(userID) {
      var user = new mparticle.User(userID);
      user.setUserAttribute('firstname', 'Jane');
      user.setUserAttribute('lastname', 'Smith');
  },
  onError: function(errorResponse) {
      console.error('Identify error: ' + JSON.stringify(errorResponse));
  }
};

// 3. Call one of the following methods that best matches the user's action:
var identity = new mparticle.Identity();
identity.login(identifyRequest, identityCallback.onSuccess); // Call when the user logs in or creates an account
identity.identify(identifyRequest, identityCallback.onSuccess); // Call when you obtain the user's email mid-session, but not during a login
identity.logout({}); // Call when the user logs out

4. Set User Attributes#

ユーザーがアプリをナビゲートする際に、段階的にユーザー属性を設定します。チェックアウト時だけでなく、設定する属性が多いほど、Roktは顧客を解決し、関連するオファーを提供することができます。

Set user attributes
var identity = new mparticle.Identity();

identity.getCurrentUser(function(userID) {
  var currentUser = new mparticle.User(userID);

  // Once you have successfully set the current user, you can set user attributes with:
  currentUser.setUserAttribute('custom-attribute-name', 'custom-attribute-value');
  // Note: all user attributes (including list attributes and tags) must have distinct names.

  // Rokt recommends setting as many of the following user attributes as possible:
  currentUser.setUserAttribute('firstname', 'John');
  currentUser.setUserAttribute('lastname', 'Doe');
  // Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
  currentUser.setUserAttribute('mobile', '3125551515');
  currentUser.setUserAttribute('age', '33');
  currentUser.setUserAttribute('gender', 'M');
  currentUser.setUserAttribute('billingcity', 'Brooklyn');
  currentUser.setUserAttribute('billingstate', 'NY');
  currentUser.setUserAttribute('billingzipcode', '123456');
  currentUser.setUserAttribute('dob', 'yyyymmdd');
  currentUser.setUserAttribute('title', 'Mr');
  currentUser.setUserAttribute('language', 'en');
  currentUser.setUserAttribute('predictedltv', '136.23');

  // You can create a user attribute to contain a list of values
  currentUser.setUserAttributeArray('favorite-genres', ['documentary', 'comedy', 'romance', 'drama']);

  // To remove a user attribute, call removeUserAttribute and pass in the attribute name.
  // All user attributes share the same key space.
  currentUser.removeUserAttribute('attribute-to-remove');
});

ユーザー属性ユーザー属性 への直接リンク

収集可能な限り、次の項目を設定してください:

すべてのユーザー属性を表示
フィールドタイプ説明
firstnamestring顧客の名。パーソナライズに使用されます。
lastnamestring顧客の姓。パーソナライズに使用されます。
mobilestring電話番号は 1112345678 または +1 (222) 345-6789 の形式で。アイデンティティ解決と関連性に使用されます。
ageinteger顧客の年齢。dob の代替。適格性と関連性に使用されます。
dobstring生年月日、yyyymmdd。age の代替。適格性と関連性に使用されます。
genderstring顧客の性別。例: M、F、Male、Female。関連性に使用されます。
titlestring敬称。例: Mr、Mrs、Ms。パーソナライズに使用されます。
languagestring購入に関連するISO 639-1言語コード。関連性に使用されます。
billingcitystring請求先の市。関連性に使用されます。
billingstatestring請求先の州/省/地域。関連性と適格性に使用されます。
billingzipcodestring完全なZIPまたは郵便番号（米国の優先はZIP+4）。アイデンティティ解決と関連性に使用されます。
billingaddress1string請求先の住所1行目。アイデンティティ解決と関連性に使用されます。
billingaddress2string請求先の住所2行目。アイデンティティ解決に使用されます。
countrystringISO 3166-1 alpha-2国コード（例: US、GB、AU）。適格性と関連性に使用されます。
birthyearinteger顧客の出生年（例: 1990）。適格性と関連性に使用されます。
newcustomerboolean初回購入者かどうか。関連性に使用されます。
customertypestringユーザーが認証されているかどうか（guest / logged_in）。関連性に使用されます。
loyaltytierstringパートナーのロイヤルティプログラムのティア。関連性と適格性に使用されます。
loyaltyidstringロイヤルティプログラムのメンバーID。アイデンティティ解決に使用されます。
predictedltvdecimal予測される生涯価値の合計で、通常はパートナーの機械学習モデルから提供されます。関連性に使用されます。
subscriptionstatusstring該当する場合のサブスクリプション状態 (active, trial, churned, paused, none)。関連性と適格性に使用されます。
customersegmentstringパートナーの内部セグメンテーション（例: vip, at_risk, new, reactivated）。関連性に使用されます。
acquisitionchannelstring顧客が取得されたチャネル。関連性に使用されます。

すべてのユーザー属性（リスト属性を含む）は、異なる名前を持たなければなりません。

5. Track Funnel Events#

画面ビュー、コマースイベント、およびカスタムイベントを追跡して、Roktが各顧客がどこにいるかを理解できるようにします。

Event category

画面の名前（例: 'homepage', 'product_detail_page'）を使用して mparticle.logScreenEvent を呼び出します。追加のカスタム属性をinfoオブジェクトに含めます。

Log a screen view
mparticle.logScreenEvent('homepage', { 'custom-attribute': 'custom-value' });

6. Show a Placement#

すべての支払いおよび確認画面でmparticle.Rokt.selectPlacementsを呼び出し、Roktがコンテンツを表示するようにします。画面の種類とテストまたは本番用であるかを指定するために、以下のページ識別子のいずれかを含めます。

  • stg.rokt.conf: A confirmation screen in a staging (or testing) environment.
  • prod.rokt.conf: A confirmation screen in a production environment.
  • stg.rokt.payments: A payments screen in a staging (or testing) environment.
  • prod.rokt.payments: A payments screen in a production environment.

配置属性配置属性 への直接リンク

これらの属性は、attributes マップ内で selectPlacements に渡します。常に最新の値を提供してください — ここで渡された属性は、以前の setUserAttribute 呼び出しを上書きします。

すべての配置属性を表示
フィールドタイプ説明
emailstring顧客のメールアドレス（ハッシュ化されていない）。アイデンティティ解決に使用されます。
firstnamestring顧客の名前。パーソナライズに使用されます。
lastnamestring顧客の姓。パーソナライズに使用されます。
mobilestringE.164形式の顧客の携帯電話番号。アイデンティティ解決に使用されます。
confirmationrefstring注文/確認参照番号。関連性と重複排除に使用されます。
currencystring取引通貨（ISO 4217、例: USD, GBP, AUD）。関連性に使用されます。
countrystringISO 3166-1 alpha-2 国コード。適格性と関連性に使用されます。
languagestring顧客の希望言語（ISO 639-1）。関連性に使用されます。
totalpricedecimal税金と送料を含むカートの合計値。関連性に使用されます。
amountstring税金と送料を含まないカート小計。totalprice とは異なります。関連性に使用されます。
couponCodestring注文に適用されたプロモーションコード（ある場合）。関連性に使用されます。
newcustomerboolean初回購入者かどうか。関連性に使用されます。
customertypestringguest または logged_in。関連性に使用されます。
valuedecimal顧客の累積購入価値（例: "2340.00"）。関連性に使用されます。
subscriptionstatusstring該当する場合のサブスクリプション状態（active, trial, churned, paused, none）。関連性と適格性に使用されます。
customersegmentstringパートナー内部のセグメンテーション（例: vip, at_risk, new, reactivated）。関連性に使用されます。
paymenttypestring選択された支払い方法（credit_card, paypal, apple_pay など）。Pay+ の適格性に使用されます。
paymentServiceProviderstringページで受け入れられる支払い方法のカンマ区切りリスト（例：applepay,paypal,cardpayment）。値は小文字でスペースを含まない必要があります。受け入れられる値の完全なリストについては、Payment Service Providerを参照してください。Pay+の適格性に使用されます。
ccbinstringクレジットカードのBIN（6-8桁）。関連性に使用されます。
billingnamestring請求先名。アイデンティティ解決に使用されます。
billingaddress1string請求先の住所。アイデンティティ解決と関連性に使用されます。
billingaddress2string請求先のアパート/ユニット。アイデンティティ解決に使用されます。
billingcitystring請求先の市区町村。関連性に使用されます。
billingstatestring請求先の州または県。関連性に使用されます。
billingzipcodestring請求先の郵便番号。アイデンティティ解決と関連性に使用されます。
shippingmethodstring選択された配送方法（standard、express、next_day）。関連性に使用されます。
shippingnamestring配送先名。関連性に使用されます。
shippingaddress1string配送先の住所。関連性に使用されます。
shippingcitystring配送先の市区町村。関連性に使用されます。
shippingstatestring配送先の州または県。関連性に使用されます。
shippingzipcodestring配送先の郵便番号。関連性に使用されます。
shippingcountrystring配送先の国（ISO 3166-1 alpha-2）。関連性に使用されます。
cartItemsstringカートアイテムのJSONシリアライズされた配列。関連性に使用されます。
adsexperiencestringShoppable Adsのエクスペリエンスを意図的にターゲットにする場合は"shoppable"を渡します。
Placement position

オーバーレイプレースメントは、Roktが管理するコンテナ内で確認画面の上にレンダリングされ、アプリの既存のレイアウトに変更を加える必要はありません。

オーバーレイプレースメントを挿入するには、確認画面がロードされたらselectPlacementsを呼び出します：

Overlay placement
var attributes = {
  // Identity
  'email': 'j.smith@example.com',
  'firstname': 'Jenny',
  'lastname': 'Smith',
  'mobile': '+13125551515',

  // Transaction
  'confirmationref': '54321',
  'currency': 'USD',
  'country': 'US',
  'language': 'en',
  'totalprice': '149.99',
  'couponCode': 'SUMMER20',

  // Customer context
  'newcustomer': 'false',
  'customertype': 'logged_in',
  'value': '2340.00',
  'subscriptionstatus': 'active',
  'customersegment': 'vip',

  // Payment (include paymenttype and paymentServiceProvider for Pay+)
  'paymenttype': 'credit_card',
  'paymentServiceProvider': 'cardpayment',
  'ccbin': '411112',

  // Billing address
  'billingaddress1': '123 Main St',
  'billingcity': 'Brooklyn',
  'billingstate': 'NY',
  'billingzipcode': '11201',

  // Shipping
  'shippingmethod': 'express',
  'shippingaddress1': '175 Varick St',
  'shippingcity': 'New York',
  'shippingstate': 'NY',
  'shippingzipcode': '10014',
  'shippingcountry': 'US'
};

var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);

オプション機能オプション機能 への直接リンク

機能目的
mparticle.Rokt.close()オーバーレイ配置を自動的に閉じます。

追加設定追加設定 への直接リンク

配置UIをカスタマイズするために、configオブジェクトなどのオプションパラメータを渡します（例：ダーク/ライトモード、キャッシング）。

selectPlacements with config
var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT,
  cacheConfig: {
      cacheDurationInSeconds: 1200,
      cacheAttributes: {
          'email': 'j.smith@example.com',
          'orderNumber': '123'
      }
  }
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);
注記

識別子RoktExperienceまたは埋め込み識別子RoktEmbedded1を異なる値で更新したい場合は、Roktアカウントマネージャーに連絡して、Rokt配置が一貫して構成されていることを確認してください。

Events APIEvents API への直接リンク

SDK+は、サブスクライブ可能なプレースメントライフサイクルイベントを提供します。onEvent コールバックを selectPlacements 呼び出しで使用して、ロード状態、エンゲージメント、失敗に応答します。

Subscribe to placement events
mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config,
  null,
  function(event) {
      // Handle placement events
      if (event && event.eventType) {
          console.log('Rokt event: ' + event.eventType);
      }
  }
);

標準イベント標準イベント への直接リンク

すべての標準イベントを表示
イベント説明パラメータ
ShowLoadingIndicatorSDK+がRoktバックエンドを呼び出す前にトリガーされます。
HideLoadingIndicatorSDK+がRoktバックエンドからの成功または失敗を受け取ったときにトリガーされます。
PlacementInteractiveプレースメントがレンダリングされ、操作可能になったときにトリガーされます。placementId: String
PlacementReadyプレースメントが表示準備ができているが、まだコンテンツがレンダリングされていないときにトリガーされます。placementId: String
OfferEngagementユーザーがオファーにエンゲージしたときにトリガーされます。placementId: String
PositiveEngagementユーザーがオファーに対して肯定的にエンゲージしたときにトリガーされます。placementId: String
FirstPositiveEngagementユーザーが初めてオファーに対して肯定的にエンゲージしたときにトリガーされます。placementId: String, fulfillmentAttributes: Object
OpenUrlユーザーがパートナーアプリに送信するように設定されたURLを押したときにトリガーされます。placementId: String, url: String
PlacementClosedユーザーによってプレースメントが閉じられたときにトリガーされます。placementId: String
PlacementCompletedオファーの進行が終了し、表示するオファーがもうない場合にトリガーされます。また、キャッシュがヒットしたが、以前に却下されたために取得されたプレースメントが表示されない場合にもトリガーされます。placementId: String
PlacementFailure何らかの失敗によりプレースメントを表示できない場合、または表示するプレースメントがない場合にトリガーされます。placementId: String (optional)
CartItemInstantPurchaseユーザーによってカタログアイテムの購入が開始されたときにトリガーされます（iOSのみ）。placementId: String, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String, totalPrice: Number, quantity: Number, unitPrice: Number

7. Appendix#

Appendix A: アプリケーション設定Appendix A: アプリケーション設定 への直接リンク

アプリケーションは、config オブジェクトを通じて設定を渡すことができ、SDK+はシステムのデフォルトではなく、アプリのカスタム設定を使用します。

ColorMode オブジェクトColorMode オブジェクト への直接リンク

値説明
LIGHTアプリケーションはライトモードです
DARKアプリケーションはダークモードです
SYSTEMアプリケーションはシステムカラーモードをデフォルトとします
selectPlacements with ColorMode
var config = {
    colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);

CacheConfig オブジェクトCacheConfig オブジェクト への直接リンク

パラメータ説明
cacheDurationInSecondsRokt SDK+がエクスペリエンスをキャッシュするためのオプションの秒数です。最大許容値は90分で、指定されていないか無効な場合のデフォルトは90分です。
cacheAttributesキャッシュキーとして使用するオプションの属性です。nullの場合、selectPlacementsで送信されたすべての属性がキャッシュキーとして使用されます。
Cache for 1200 seconds
// Cache the experience for 1200 seconds, using email and orderNumber as the cache key.
var config = {
    cacheConfig: {
        cacheDurationInSeconds: 1200,
        cacheAttributes: {
            'email': 'j.smith@example.com',
            'orderNumber': '123'
        }
    }
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);

EdgeToEdgeDisplay (Androidのみ)EdgeToEdgeDisplay (Androidのみ) への直接リンク

RoktオーバーレイがAndroidのエッジ・ツー・エッジディスプレイモードを尊重するかどうかを制御します。この設定はAndroidパスにのみ適用され、iOSではこのフラグを使用しません。

値説明
true (default)アプリケーションはエッジ・ツー・エッジディスプレイモードをサポートします
falseアプリケーションはエッジ・ツー・エッジディスプレイモードをサポートしません

Cordova SDK+は現在、EdgeToEdgeDisplayをJavaScriptの設定オプションとして公開していません。Androidアプリがエッジ・ツー・エッジディスプレイをオプトアウトし、オーバーレイが正しくレンダリングされない場合、ネイティブAndroidコードで設定してください：

EdgeToEdgeDisplay (native Android — RoktConfig)
import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(false) // set to false if your app does not use edge-to-edge
    .build()

ネイティブAndroidレイヤーでroktConfigをselectPlacementsに渡すか、Cordovaレベルのサポートが必要な場合はRoktアカウントマネージャーに相談してください。

Appendix B: ネイティブUIコンポーネントAppendix B: ネイティブUIコンポーネント への直接リンク

Cordova SDK+は、基盤となるiOSおよびAndroid SDK+によってレンダリングされるネイティブRokt UIコンポーネントを使用します。Jetpack ComposeやSwiftUIに相当するCordova固有の宣言的UIコンポーネントはありません。プレースメントUIは完全にネイティブレイヤーによって管理され、selectPlacements APIを通じて表示されます。

Appendix C: エラーハンドリングAppendix C: エラーハンドリング への直接リンク

IDSync APIは、アプリの状態の中心となることを意図しており、高速かつ高可用性を備えています。アプリがインターネット接続なしでユーザーのログイン、ログアウト、または状態の変更を防ぐのと同様に、これらのAPIをゲーティング操作として扱い、一貫したユーザー状態を維持してください。SDK+はAPI呼び出しを自動的に再試行しませんが、ビジネスロジックに従って再試行できるようにコールバックAPIを提供します。

エラーハンドリングを実装しない場合、大規模なデータの一貫性の問題が発生する可能性があります。

Cordova SDK+のmparticle.Identity.identify()コールバックパターンは、onErrorハンドラーを通じてエラーを表面化します。適切なアクションを決定するためにerrorResponseオブジェクトを調査してください。

IDSync error handling
var identifyTask = {
    onSuccess: function(userID) {
        // IDSync succeeded — proceed with the identified user
        console.log('Identify success, userID: ' + userID);
    },
    onError: function(errorResponse) {
        if (errorResponse && errorResponse.httpCode !== undefined) {
            if (errorResponse.httpCode === -1) {
                // Device is likely offline (maps to UNKNOWN_ERROR on Android,
                // MPIdentityErrorResponseCodeClientNoConnection on iOS) — retry the request
            } else if (errorResponse.httpCode === 429) {
                // Throttled — retry with exponential backoff
            } else if (errorResponse.httpCode >= 500) {
                // Server-side error — contact your account representative
            } else {
                // Inspect errorResponse for implementation issues (e.g. 400 invalid request, 401 auth error)
                console.error('Identity error: ' + JSON.stringify(errorResponse));
            }
        }
    }
};

var identity = new mparticle.Identity();
identity.identify(identifyRequest, identifyTask.onSuccess);

iOSエラーコードiOSエラーコード への直接リンク

iOSでは、ネイティブSDK+が失敗をMPIdentityErrorResponseCode値にマッピングします。CordovaブリッジはこれをJavaScriptエラーレスポンスのhttpCodeとして表面化します。処理すべき主要なコードは次の通りです：

コード意味アクション
MPIdentityErrorResponseCodeClientNoConnectionデバイスがオフラインまたはネットワークなしリクエストを再試行
MPIdentityErrorResponseCodeClientSideTimeoutTCP接続がタイムアウトリクエストを再試行
MPIdentityErrorResponseCodeRequestInProgress別のIDSyncリクエストが進行中実装を確認し、頻繁でなければ再試行
MPIdentityErrorResponseCodeRetrySDK+レベルの再試行信号リクエストを再試行
429 (HTTP)Roktサーバーによるレート制限指数バックオフで再試行
400 (HTTP)無効なリクエストボディerrorResponseを調査 — 通常は実装の問題
401 (HTTP)認証エラーAPIキーを確認

AndroidエラーコードAndroidエラーコード への直接リンク

Androidでは、ネイティブSDK+がクライアント側の失敗（デバイスオフライン、クライアント側タイムアウト、無効なリクエスト）に対してIdentityApi.UNKNOWN_ERRORを返します。429レスポンスはIdentityApi.THROTTLE_ERRORにマッピングされます。どちらも適切な再試行戦略を示します：

  • UNKNOWN_ERROR（デバイスオフラインまたはクライアント側の問題）：接続が回復したらリクエストを再試行します。
  • THROTTLE_ERROR / 429：指数バックオフで再試行します。これはユーザーの「ホットキー」や予想以上のIDSyncボリュームを示すことがあります — 頻繁に発生する場合は実装を確認してください。

Appendix D: WebからネイティブへのセッションIDの受け渡しAppendix D: WebからネイティブへのセッションIDの受け渡し への直接リンク

ユーザーの操作がWebとネイティブプラットフォームの両方にまたがる場合、Web SDK+からCordova SDK+にセッションIDを渡すことで、一貫したRoktセッションを維持できます。これは、ユーザーがWebViewでアクションを完了し（例えば、支払いページ）、ネイティブアプリに戻って確認するようなハイブリッドフローに役立ちます。

Web SDK+からのセッションIDの取得Web SDK+からのセッションIDの取得 への直接リンク

selectPlacementsを呼び出した後、セッションIDは選択コンテキストで利用可能です：

Retrieve sessionId from the selection context
const selection = await launcher.selectPlacements({
    identifier: "checkout",
    attributes: {
        email: "user@example.com",
        // ... other attributes
    }
});

const sessionId = await selection.context.sessionId;
注記

The session ID is a unique GUID assigned to the current user journey. It is useful for debugging and for correlating a user's activity across your web and native surfaces.

セッションIDをディープリンクを使用してネイティブアプリに渡します：

Deep-link to native app
const deepLink = `myapp://confirmation?sessionId=${encodeURIComponent(sessionId)}`;
window.location.href = deepLink;

セッションIDの設定セッションIDの設定 への直接リンク

ディープリンクからセッションIDを抽出し、selectPlacementsを呼び出す前にSDK+に渡します。

Set sessionId in Cordova
// Extract the sessionId from your deep link handler and set it before selectPlacements
var sessionId = getSessionIdFromDeepLink(); // Your deep link parsing logic

if (sessionId) {
    mparticle.Rokt.setSessionId(sessionId);
}

// Then proceed with selectPlacements
mparticle.Rokt.selectPlacements('RoktExperience', attributes, config);

注意事項注意事項 への直接リンク

  • セッションが使用されるようにするため、setSessionIdをselectPlacementsの前に呼び出してください。
  • 空の文字列は無視され、セッションは更新されません。
  • クエリパラメータとして渡す際には、常にセッションIDをURLエンコードしてください。

8. Test Your Integration#

SDK+が正しく初期化され、イベントが正しくログに記録されることを確認するには：

1Enable verbose SDK+ logging#

初期化前に詳細なSDK+ログを有効にして、送信されている内容を確認できるようにします。

Enable verbose SDK+ logging (iOS)
[MParticle sharedInstance].logLevel = MPILogLevelVerbose;

2Build and run your app#

開発キーを使用してアプリをビルドおよび実行し、両方のプラットフォームで環境をDevelopmentに設定します。

3Trigger selectPlacements#

配置がレンダリングされるべき画面でselectPlacementsをトリガーし、配置がロードされることを確認します。

4Verify events#

イベントがログに記録され、identifyRequestの呼び出しが成功することを確認します。

トラブルシューティングトラブルシューティング への直接リンク

プレースメントが表示されない、またはイベントが表示されない場合は、Rokt SDK+ のエラーについてネイティブデバイスのログ（iOS の場合は Xcode コンソール、Android の場合は Android Logcat）を確認してください。一般的な問題:

初期化エラー初期化エラー への直接リンク

  • iOS (your-key / your-secret in optionsWithKey:secret:) および Android (.credentials("your-key", "your-secret")) の両方で、キーとシークレットが Rokt アカウントマネージャーからの値と一致していることを確認してください。
  • MParticle.start (Android) および [[MParticle sharedInstance] startWithOptions:options] (iOS) が、selectPlacements または logEvent の呼び出しの前に実行されることを確認してください。

アイデンティティエラーアイデンティティエラー への直接リンク

アイデンティティコールバックがエラーで発生した場合、エラーコードと再試行のガイダンスについては エラーハンドリング を参照してください。エラーハンドリングがないと、大規模なデータ整合性の問題が発生する可能性があります。

プレースメントが表示されないプレースメントが表示されない への直接リンク

  • プレースメント identifier (例: RoktExperience) が、Rokt アカウントマネージャーが設定したものと一致していることを確認してください。
  • 埋め込みプレースメントの場合、埋め込みビューの識別子 (例: RoktEmbedded1) がレイアウト設定と一致していることを確認してください。
  • 属性マップに少なくとも email、firstname、lastname、billingzipcode、および confirmationref が含まれていることを確認してください。
この記事は役に立ちましたか？