Cordova SDK+ 統合ガイド

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

Target

このページでは、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の初期化後、ユーザーがログイン、ログアウト、または他の識別子を提供するたびに（例：チェックアウト時）、以下に説明する適切な方法を使用してユーザーの識別を同期させる必要があります。

サポートされているユーザー識別子

サポートされているユーザー識別子を表示

フィールド	タイプ	説明
email	string	顧客の生のハッシュ化されていないメールアドレスを渡します。
mobile	string	顧客の電話番号をE.164形式で渡します。
customerid	string	内部の顧客/アカウント識別子を渡します。ログインしているユーザーにはすべての画面で送信します。
other	string	SHA-256ハッシュ化されたメールを渡します。生のメールを提供できない場合のみ使用してください — email と other の両方を渡さないでください。（Androidパスのみ。）
other2	string	SHA-256ハッシュ化された携帯番号を渡します。生の携帯番号を提供できない場合のみ使用してください — mobile と other2 の両方を渡さないでください。（Androidパスのみ。）
emailSha256	string	SHA-256ハッシュ化されたメールを渡します。生のメールを提供できない場合のみ使用してください — email と emailSha256 の両方を渡さないでください。（iOSパスのみ。）
mobileSha256	string	SHA-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');
});

ユーザー属性

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

すべてのユーザー属性を表示

フィールド	タイプ	説明
firstname	string	顧客の名。パーソナライズに使用されます。
lastname	string	顧客の姓。パーソナライズに使用されます。
mobile	string	電話番号は 1112345678 または +1 (222) 345-6789 の形式で。アイデンティティ解決と関連性に使用されます。
age	integer	顧客の年齢。dob の代替。適格性と関連性に使用されます。
dob	string	生年月日、yyyymmdd。age の代替。適格性と関連性に使用されます。
gender	string	顧客の性別。例: M、F、Male、Female。関連性に使用されます。
title	string	敬称。例: Mr、Mrs、Ms。パーソナライズに使用されます。
language	string	購入に関連するISO 639-1言語コード。関連性に使用されます。
billingcity	string	請求先の市。関連性に使用されます。
billingstate	string	請求先の州/省/地域。関連性と適格性に使用されます。
billingzipcode	string	完全なZIPまたは郵便番号（米国の優先はZIP+4）。アイデンティティ解決と関連性に使用されます。
billingaddress1	string	請求先の住所1行目。アイデンティティ解決と関連性に使用されます。
billingaddress2	string	請求先の住所2行目。アイデンティティ解決に使用されます。
country	string	ISO 3166-1 alpha-2国コード（例: US、GB、AU）。適格性と関連性に使用されます。
birthyear	integer	顧客の出生年（例: 1990）。適格性と関連性に使用されます。
newcustomer	boolean	初回購入者かどうか。関連性に使用されます。
customertype	string	ユーザーが認証されているかどうか（guest / logged_in）。関連性に使用されます。
loyaltytier	string	パートナーのロイヤルティプログラムのティア。関連性と適格性に使用されます。
loyaltyid	string	ロイヤルティプログラムのメンバーID。アイデンティティ解決に使用されます。
predictedltv	decimal	予測される生涯価値の合計で、通常はパートナーの機械学習モデルから提供されます。関連性に使用されます。
subscriptionstatus	string	該当する場合のサブスクリプション状態 (active, trial, churned, paused, none)。関連性と適格性に使用されます。
customersegment	string	パートナーの内部セグメンテーション（例: vip, at_risk, new, reactivated）。関連性に使用されます。
acquisitionchannel	string	顧客が取得されたチャネル。関連性に使用されます。

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

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 呼び出しを上書きします。

すべての配置属性を表示

フィールド	タイプ	説明
email	string	顧客のメールアドレス（ハッシュ化されていない）。アイデンティティ解決に使用されます。
firstname	string	顧客の名前。パーソナライズに使用されます。
lastname	string	顧客の姓。パーソナライズに使用されます。
mobile	string	E.164形式の顧客の携帯電話番号。アイデンティティ解決に使用されます。
confirmationref	string	注文/確認参照番号。関連性と重複排除に使用されます。
currency	string	取引通貨（ISO 4217、例: USD, GBP, AUD）。関連性に使用されます。
country	string	ISO 3166-1 alpha-2 国コード。適格性と関連性に使用されます。
language	string	顧客の希望言語（ISO 639-1）。関連性に使用されます。
totalprice	decimal	税金と送料を含むカートの合計値。関連性に使用されます。
amount	string	税金と送料を含まないカート小計。totalprice とは異なります。関連性に使用されます。
couponCode	string	注文に適用されたプロモーションコード（ある場合）。関連性に使用されます。
newcustomer	boolean	初回購入者かどうか。関連性に使用されます。
customertype	string	guest または logged_in。関連性に使用されます。
value	decimal	顧客の累積購入価値（例: "2340.00"）。関連性に使用されます。
subscriptionstatus	string	該当する場合のサブスクリプション状態（active, trial, churned, paused, none）。関連性と適格性に使用されます。
customersegment	string	パートナー内部のセグメンテーション（例: vip, at_risk, new, reactivated）。関連性に使用されます。
paymenttype	string	選択された支払い方法（credit_card, paypal, apple_pay など）。Pay+ の適格性に使用されます。
paymentServiceProvider	string	ページで受け入れられる支払い方法のカンマ区切りリスト（例：applepay,paypal,cardpayment）。値は小文字でスペースを含まない必要があります。受け入れられる値の完全なリストについては、Payment Service Providerを参照してください。Pay+の適格性に使用されます。
ccbin	string	クレジットカードのBIN（6-8桁）。関連性に使用されます。
billingname	string	請求先名。アイデンティティ解決に使用されます。
billingaddress1	string	請求先の住所。アイデンティティ解決と関連性に使用されます。
billingaddress2	string	請求先のアパート/ユニット。アイデンティティ解決に使用されます。
billingcity	string	請求先の市区町村。関連性に使用されます。
billingstate	string	請求先の州または県。関連性に使用されます。
billingzipcode	string	請求先の郵便番号。アイデンティティ解決と関連性に使用されます。
shippingmethod	string	選択された配送方法（standard、express、next_day）。関連性に使用されます。
shippingname	string	配送先名。関連性に使用されます。
shippingaddress1	string	配送先の住所。関連性に使用されます。
shippingcity	string	配送先の市区町村。関連性に使用されます。
shippingstate	string	配送先の州または県。関連性に使用されます。
shippingzipcode	string	配送先の郵便番号。関連性に使用されます。
shippingcountry	string	配送先の国（ISO 3166-1 alpha-2）。関連性に使用されます。
cartItems	string	カートアイテムのJSONシリアライズされた配列。関連性に使用されます。
adsexperience	string	Shoppable Adsのエクスペリエンスを意図的にターゲットにする場合は"shoppable"を渡します。iOSでのみ使用されます。

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 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);
      }
  }
);

標準イベント

すべての標準イベントを表示

イベント	説明	パラメータ
ShowLoadingIndicator	SDK+がRoktバックエンドを呼び出す前にトリガーされます。
HideLoadingIndicator	SDK+が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: アプリケーション設定

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

ColorMode オブジェクト

値	説明
LIGHT	アプリケーションはライトモードです
DARK	アプリケーションはダークモードです
SYSTEM	アプリケーションはシステムカラーモードをデフォルトとします

selectPlacements with ColorMode

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

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

CacheConfig オブジェクト

パラメータ	説明
cacheDurationInSeconds	Rokt 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のみ)

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コンポーネント

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

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

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

Androidエラーコード

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

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

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

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

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を抽出し、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 が含まれていることを確認してください。