Flutter SDK+ 統合ガイド

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

Target

Language

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

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

注記

SDK+を初期化する際に、ステップ2でネイティブコード（iOSではSwiftまたはObjective-C、AndroidではKotlinまたはJava）を数行書きます。その他のステップはすべて、mparticle_flutter_sdkパッケージを通じてDartを使用します。

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

Flutter SDK+はネイティブSDK+の上で動作します。Dart側のインストール手順はすべてのターゲットで同じですが、ネイティブのインストールはターゲットプラットフォームごとに異なります。上のTargetピルを使用して、iOS、Android、Webの間を切り替えてください。

1Add the mparticle_flutter_sdk package#

Flutterプロジェクトにmparticle_flutter_sdkパッケージを追加します。

Add the Flutter package

flutter pub add mparticle_flutter_sdk

2Pin mparticle_flutter_sdk to 2.0 or later#

pub addを実行した後、pubspec.yamlはパッケージを2.0以上に固定する必要があります（Shoppable Adsに必要）。

pubspec.yaml

dependencies:
  mparticle_flutter_sdk: ^2.0.0

3Add the Rokt SDK+ to your iOS app#

Rokt SDK+は、最低でもiOS 15.0のデプロイメントターゲットを必要とします。CocoaPodsまたはSwift Package Managerのどちらかを使用してください—プロジェクトで既に使用している方を選んでください。

Install method

ios/PodfileにRokt SDK+ポッドを追加します。

ios/Podfile

pod 'RoktSDKPlus', '~> 9.2'

4Get the SDK handle#

Dartコードにパッケージをインポートし、SDKのインスタンスを取得します。このmpInstanceは、このガイドの残りの部分で使用されるSDKハンドルです。後のステップでのすべてのDart API呼び出し（識別、ユーザー属性の設定、イベントのログ、プレースメントの表示）はこれを通じて行われます。

Get the SDK handle

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

MparticleFlutterSdk? mpInstance = await MparticleFlutterSdk.getInstance();

2. Initialize the Rokt SDK+#

Flutter SDK+は、ターゲットプラットフォームのネイティブSDK+を通じて初期化されます。ネイティブ側に適切な初期化スニペットを挿入し、その後Dartのmparticle_flutter_sdkパッケージがそれをプロキシします。

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

1Entering your Rokt key and secret#

Roktのキーとシークレットを、Roktアカウントマネージャーから提供された値に設定します。

2Setting your data environment#

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

3Entering a custom first-party domain#

First-Party Domain Configurationの指示に従い、ネットワークオプションオブジェクトのカスタムベースURLをカスタムサブドメインに設定します。Rokt SDK+を自分のドメインを通じてルーティングすることで、広告ブロッカーやブラウザによる広告やデータのブロックのリスクを軽減します。ネットワークオプションを完全に省略すると、Roktのデフォルトエンドポイントにトラフィックが送信されます。

4Identifying your user and setting attributes#

identifyRequestにユーザーの生のハッシュ化されていないメールを渡します。識別後、成功コールバック（iOS: onIdentifyComplete. Android: addSuccessListener）を使用して追加のユーザー属性を設定します。

注記

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

次の初期化スニペットをAppDelegateファイルに挿入します。your-keyとyour-secretをRoktチームから提供された値に置き換えてください。

AppDelegate initialization (Swift)

import mParticle_Apple_SDK
import RoktPaymentExtension

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  // Initialize the SDK
  let options = MParticleOptions(key: "your-key",
  secret: "your-secret")
  // Specify the data environment with environment:
  // Set it to .development if you are still testing your integration.
  // Set it to .production if your integration is ready for production data.
  // The default is .autoDetect which attempts to detect the environment automatically
  options.environment = .development

  // Enter your custom subdomain if you are using a first-party domain configuration (optional)
  let networkOptions = MPNetworkOptions()
  networkOptions.customBaseURL = URL(string: "https://rkt.example.com")
  options.networkOptions = networkOptions

  // Identify the current user:
  let identifyRequest = MPIdentityApiRequest.withEmptyUser()

  // If you're using an un-hashed email address, set it in 'email'.
  identifyRequest.email = "j.smith@example.com"

  // If you're using a hashed email address, set it in 'other' instead of email
  identifyRequest.setIdentity("sha256 hashed email goes here", identityType: .other)

  // If the user is identified with their email address, set additional user attributes.
  options.identifyRequest = identifyRequest
  options.onIdentifyComplete = {(result: MPIdentityApiResult?, error: Error?) in
      if let user = result?.user {
          user.setUserAttribute("example attribute key", value: "example attribute value")
      }
  }
  MParticle.sharedInstance().start(with: options)

  // Register after MParticle.sharedInstance().start(), before selectShoppableAds
  if let paymentExt = RoktPaymentExtension(
      applePayMerchantId: "merchant.com.yourapp.rokt", // omit if not offering Apple Pay
      urlScheme: "myapp" // omit if not offering Afterpay / Clearpay
  ) {
      MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
  }
  return true
}

注記

mParticle Rokt kit設定（mParticleダッシュボード）でstripePublishableKeyを設定します。キットは登録時にこれをstripeKeyとしてRoktに転送します—コード内で渡す必要はありません。applePayMerchantIdまたはurlSchemeのいずれかを必ず提供してください。

5Registering the payment extension#

RoktPaymentExtensionをMParticle.sharedInstance().start()の後、selectShoppableAdsの前に登録して、Shoppable Adsの支払いを有効にします。iOSのすべてのShoppable Ads配置に登録が必要です—Apple PayにはapplePayMerchantIdを、Afterpay / ClearpayにはurlSchemeを、またはその両方を渡します。Appendix F: Configure Shoppable Ads paymentsを参照してください。

3. Identify the User#

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

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

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

識別子	タイプ	説明
email	string	顧客の生のハッシュされていないメールアドレスを渡します。
mobile_number	string	顧客の電話番号をE.164形式で渡します。
customerId	string	内部の顧客/アカウント識別子を渡します。ログインしているユーザーには、すべての画面で送信します。
other	string	SHA-256でハッシュされたメールを渡します。生のメールが提供できない場合のみ使用します — email と other の両方を渡さないでください。
other2	string	SHA-256でハッシュされた携帯番号を渡します。生の携帯番号が提供できない場合のみ使用します — mobile_number と other2 の両方を渡さないでください。

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

1Create an identityRequest object#

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

2Use the success handler for additional attributes#

追加のユーザー属性を設定するには、識別呼び出し（ウェブ: identityCallback）で then 成功ハンドラを使用します。identityRequest が成功した場合、ハンドラ内で設定したユーザー属性は識別されたユーザーに割り当てられます。

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

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

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

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

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

Identify Jane Smith (Dart)

import 'package:mparticle_flutter_sdk/identity/identity_type.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_result.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_error_response.dart';

// 1. Create the identityRequest object
var identityRequest = MparticleFlutterSdk.identityRequest;
// Preferred: pass the customer's raw, unhashed email.
// If you can only provide a SHA-256-hashed email, remove the Email line and use IdentityType.Other instead — do not pass both.
identityRequest.setIdentity(identityType: IdentityType.Email, value: 'j.smith@example.com');
identityRequest.setIdentity(identityType: IdentityType.Other, value: 'SHA-256 hashed email');  // only if raw email unavailable
// If you can only provide a SHA-256-hashed mobile number, use IdentityType.Other2 instead of MobileNumber — do not pass both.
identityRequest.setIdentity(identityType: IdentityType.Other2, value: 'SHA-256 hashed mobile number');  // only if raw mobile unavailable
identityRequest.setIdentity(identityType: IdentityType.MobileNumber, value: '+13125551515');
identityRequest.setIdentity(identityType: IdentityType.CustomerId, value: 'cust_10482');

// 2. Optionally set user attributes in the success handler.
void Function(IdentityApiResult) identityCallback = (IdentityApiResult successResponse) {
  successResponse.user.setUserAttribute('firstname', 'Jane');
  successResponse.user.setUserAttribute('lastname', 'Smith');
};

// 3. Call one of the following methods that best matches the user's action:
mpInstance?.identity.login(identityRequest: identityRequest).then(identityCallback); // Call when the user logs in or creates an account
mpInstance?.identity.identify(identityRequest: identityRequest).then(identityCallback); // Call when you obtain the user's email mid-session, but not during a login
mpInstance?.identity.logout(); // Call when the user logs out

4. Set User Attributes#

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

Set user attributes (Dart)

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

// Retrieve the current user. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
var currentUser = await mpInstance?.getCurrentUser();

// Once you have successfully set the current user to `currentUser`, you can set user attributes with:
currentUser?.setUserAttribute(key: 'custom-attribute-name', value: '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(key: 'firstname', value: 'John');
currentUser?.setUserAttribute(key: 'lastname', value: 'Doe');
// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser?.setUserAttribute(key: 'mobile', value: '3125551515');
currentUser?.setUserAttribute(key: 'age', value: '33');
currentUser?.setUserAttribute(key: 'gender', value: 'M');
currentUser?.setUserAttribute(key: 'city', value: 'Brooklyn');
currentUser?.setUserAttribute(key: 'state', value: 'NY');
currentUser?.setUserAttribute(key: 'zip', value: '123456');
currentUser?.setUserAttribute(key: 'dob', value: 'yyyymmdd');
currentUser?.setUserAttribute(key: 'title', value: 'Mr');
currentUser?.setUserAttribute(key: 'language', value: 'en');
currentUser?.setUserAttribute(key: 'lifetime_value', value: '52.25');
currentUser?.setUserAttribute(key: 'predictedltv', value: '136.23');

// You can create a user attribute to contain a list of values
var attributeList = <String>[];
attributeList.add('documentary');
attributeList.add('comedy');
attributeList.add('romance');
attributeList.add('drama');
currentUser?.setUserAttributeArray(key: 'favorite-genres', value: attributeList);

// To remove a user attribute, call removeUserAttribute and pass in the attribute name. All user attributes share the same key space.
currentUser?.removeUserAttribute(key: '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言語コード。関連性に使用されます。
city	string	請求先の都市。関連性に使用されます。
state	string	請求先の州/県/地域。関連性と適格性に使用されます。
zip	string	完全なZIPまたは郵便番号（米国の優先はZIP+4）。アイデンティティ解決と関連性に使用されます。
country	string	ISO 3166-1 alpha-2国コード（例: US, GB, AU）。適格性と関連性に使用されます。
newcustomer	boolean	初回購入者かどうか。関連性に使用されます。
customertype	string	ユーザーが認証済みかどうか（guest / logged_in）。関連性に使用されます。
loyaltytier	string	パートナーのロイヤルティプログラムの階層。関連性と適格性に使用されます。
loyaltyid	string	ロイヤルティプログラムのメンバーID。アイデンティティ解決に使用されます。
lifetime_value	decimal	顧客の累積購入価値。文字列として（例: "52.25"）。関連性に使用されます。
predictedltv	decimal	通常はパートナーのMLモデルからの予測された総生涯価値。lifetime_value とは異なります。関連性に使用されます。
subscriptionstatus	string	該当する場合のサブスクリプション状態 (active、trial、churned、paused、none)。関連性と適格性のために使用されます。
customersegment	string	パートナー内部のセグメンテーション（例: vip、at_risk、new、reactivated）。関連性のために使用されます。
utmsource	string	マーケティング帰属ソース。関連性のために使用されます。
utmmedium	string	マーケティング帰属メディア。関連性のために使用されます。
utmcampaign	string	マーケティング帰属キャンペーン。関連性のために使用されます。

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

5. Log Events#

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

Event category

mpInstance?.logScreenEvent()を画面の名前（例: 'homepage'、'product_detail_page'）と共に呼び出します。イベントのcustomAttributesマップに追加のカスタム属性を含めます。

Log a screen view (Dart)

import 'package:mparticle_flutter_sdk/events/screen_event.dart';

ScreenEvent screenEvent = ScreenEvent(eventName: 'homepage')
..customAttributes = {'custom-attribute': 'custom-value'};
mpInstance?.logScreenEvent(screenEvent);

6. Show a Placement#

支払いおよび確認画面ごとに selectPlacements を呼び出し、Roktがコンテンツをレンダリングするようにします。画面タイプとテストまたは本番用かを指定するために、次のページ識別子のいずれかを含めます:

• stg.rokt.conf: A confirmation page in a staging (or testing) environment.
• prod.rokt.conf: A confirmation page in a production environment.
• stg.rokt.payments: A payments page in a staging (or testing) environment.
• prod.rokt.payments: A payments page 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 とは異なります。関連性とShoppable Adsに使用されます。
cartitemcount	integer	カート内のアイテム数。関連性に使用されます。
cartItems	array	カートラインオブジェクトの構造化された配列（Flutter Webのみ）。Commerce Eventsのカートアイテムを参照してください。関連性に使用されます。
couponcode	string	注文に適用されたプロモーションコード（ある場合）。関連性に使用されます。
newcustomer	boolean	初回購入者かどうか。関連性に使用されます。
customertype	string	guest または logged_in。関連性に使用されます。
lifetime_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+ の適格性と Shoppable Ads の支払い方法の優先順位付けに使用されます。
paymentServiceProvider	string	ページ上で提供される支払いサービス（apple_pay, paypal, card）。Pay+ の適格性に使用されます。
ccbin	string	クレジットカードのBIN（6-8桁）。関連性のために使用されます。
billingaddress1	string	請求先の住所。アイデンティティ解決と関連性のために使用されます。
billingaddress2	string	請求先のアパート/ユニット。アイデンティティ解決のために使用されます。
billingcity	string	請求先の市区町村。関連性のために使用されます。
billingstate	string	請求先の州または省。関連性のために使用されます。
billingzipcode	string	請求先の郵便番号。アイデンティティ解決と関連性のために使用されます。
shippingmethod	string	選択された配送方法（standard, express, next_day）。関連性のために使用されます。
shippingaddress1	string	配送先の住所。関連性と Shoppable Ads の注文履行のために使用されます。
shippingcity	string	配送先の市区町村。関連性と Shoppable Ads の注文履行のために使用されます。
shippingstate	string	配送先の州または省。関連性と Shoppable Ads の注文履行のために使用されます。
shippingzipcode	string	配送先の郵便番号。関連性と Shoppable Ads の注文履行のために使用されます。
shippingcountry	string	配送先の国（ISO 3166-1 alpha-2）。関連性と Shoppable Ads の注文履行のために使用されます。
adsexperience	string	Shoppable Ads のエクスペリエンスを意図的に選択する場合は "shoppable" を渡します。

Placement position

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

オーバーレイ配置を挿入するには、確認画面が読み込まれたら selectPlacements を呼び出します:

Overlay placement (Dart)

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

final 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',
  'cartitemcount': '2',
  'couponcode': 'SUMMER20',

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

  // Payment (include paymenttype and paymentServiceProvider for Pay+)
  'paymenttype': 'credit_card',
  'paymentServiceProvider': 'card',
  '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',
};

final roktConfig = RoktConfig(
  colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
  identifier: 'RoktExperience',
  attributes: attributes,
  roktConfig: roktConfig,
);

オプションの関数

関数	目的
Rokt.close()	オーバーレイ配置を自動的に閉じる。

追加の設定

配置 UI をカスタマイズするために、RoktConfig などのオプションパラメータを渡します（例：ダーク/ライトモード、キャッシング）。フォントファイルパスも PostScript 名とアセットパスのマップとして提供できます。

selectPlacements with RoktConfig and font typefaces (Dart)

// If you want to use custom fonts for your placement, create a fontTypefaces map
final fontTypefaces = {'Arial-Bold': 'fonts/Arial-Bold.ttf'};

final roktConfig = RoktConfig(
  colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
  identifier: 'RoktExperience',
  attributes: attributes,
  fontFilePathMap: fontTypefaces,
  roktConfig: roktConfig,
);

注記

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

Events API

iOSおよびAndroidでは、SDK+はMPRoktEvents EventChannelを通じて配置ライフサイクルイベントをストリームとして提供します。Webでは、selectPlacementsによって返される選択オブジェクトで直接イベントを購読します。

Subscribe to placement events (Dart)

final EventChannel roktEventChannel = EventChannel('MPRoktEvents');
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
  debugPrint('rokt_event: $event');
});

標準イベント

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

イベント	説明	パラメータ
ShowLoadingIndicator	SDK+がRoktバックエンドを呼び出す前にトリガーされます。
HideLoadingIndicator	SDK+がRoktバックエンドからの成功または失敗を受け取ったときにトリガーされます。
PlacementInteractive	配置がレンダリングされ、インタラクティブになったときにトリガーされます。	identifier: String
PlacementReady	配置が表示する準備ができているが、まだコンテンツがレンダリングされていないときにトリガーされます。	identifier: String
OfferEngagement	ユーザーがオファーとエンゲージしたときにトリガーされます。	identifier: String
PositiveEngagement	ユーザーがオファーと積極的にエンゲージしたときにトリガーされます。	identifier: String
FirstPositiveEngagement	ユーザーが初めてオファーと積極的にエンゲージしたときにトリガーされます。	identifier: String, fulfillmentAttributes: FulfillmentAttributes
OpenUrl	ユーザーがパートナーアプリに送信するように設定されたURLを押したときにトリガーされます。	identifier: String, url: String
PlacementClosed	ユーザーによって配置が閉じられたときにトリガーされます。	identifier: String
PlacementCompleted	オファーの進行が終了し、表示するオファーがもうない場合にトリガーされます。また、キャッシュがヒットしたが、以前に却下されたために取得されたプレースメントが表示されない場合にもトリガーされます。	identifier: String
PlacementFailure	プレースメントが何らかの失敗により表示できない場合、または表示するプレースメントがない場合にトリガーされます。	identifier: String (optional)
EmbeddedSizeChanged	埋め込みプレースメントの高さが変わったときにトリガーされます。	identifier: String, selectedHeight: Double
CartItemInstantPurchase	ユーザーがカタログアイテムの購入を開始したときにトリガーされます。	identifier: String, catalogItemId: String, cartItemId: String, totalPrice: String, currency: String
CartItemInstantPurchaseInitiated	購入フローが開始されました—ユーザーが「購入」をタップしました（Shoppable Ads、iOSのみ）。	identifier: String, catalogItemId: String, cartItemId: String
CartItemInstantPurchaseFailure	購入に失敗しました（Shoppable Ads、iOSのみ）。	identifier: String, catalogItemId: String, cartItemId: String, error: String
CartItemDevicePay	Apple Pay / デバイス支払いがトリガーされました（Shoppable Ads、iOSのみ）。	identifier: String, catalogItemId: String, cartItemId: String, paymentProvider: String
InstantPurchaseDismissal	ユーザーが購入オーバーレイを却下しました（Shoppable Ads、iOSのみ）。	identifier: String

7. Appendix#

Appendix A: アプリケーション設定

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

ColorMode オブジェクト

値	説明
light	アプリケーションがライトモードであること
dark	アプリケーションがダークモードであること
system	アプリケーションがシステムのカラーモードにデフォルト設定されていること

RoktConfig with ColorMode

final roktConfig = RoktConfig(
    colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
    identifier: 'RoktExperience',
    attributes: attributes,
    roktConfig: roktConfig,
);

EdgeToEdgeDisplay (Android のみ)

値	説明
true (デフォルト)	アプリケーションがエッジ・トゥ・エッジディスプレイモードをサポートすること
false	アプリケーションがエッジ・トゥ・エッジディスプレイモードをサポートしないこと

Android でネイティブの RoktConfig を構築する際、edgeToEdgeDisplay(true) を RoktConfig.Builder で呼び出してエッジ・トゥ・エッジモードを有効にします:

RoktConfig with EdgeToEdgeDisplay (Android native)

import com.mparticle.MParticle
import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(true)
    .build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
    identifier = "RoktExperience",
    attributes = attributes,
    config = roktConfig
)

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.
final roktConfig = RoktConfig(
    cacheConfig: CacheConfig(
        cacheDurationInSeconds: 1200,
        cacheAttributes: {'email': 'j.smith@example.com', 'orderNumber': '123'},
    ),
);

mpInstance?.rokt.selectPlacements(
    identifier: 'RoktExperience',
    attributes: attributes,
    roktConfig: roktConfig,
);

Appendix B: SwiftUI サポートと MPRoktLayout (iOS のみ)

アプリが主に SwiftUI で書かれている場合、MPRoktLayout コンポーネントは、iOS アプリに Rokt プレースメントを統合するためのよりモダンで宣言的なアプローチを提供します。

MPRoktLayout クラスは、selectPlacements を手動で呼び出すことなく、Rokt プレースメントを表示するための SwiftUI 互換の方法を提供し、オーバーレイと埋め込みの両方のプレースメントタイプをサポートします。

SwiftUI placement with MPRoktLayout

import SwiftUI
import mParticle_Apple_SDK
import mParticle_Rokt_Swift

struct OrderConfirmationView: View {
    let attributes = [
        "email": "test@gmail.com",
        "firstname": "Jenny",
        "lastname": "Smith",
        "billingzipcode": "07762",
        "confirmationref": "54321"
    ]

    @State private var sdkTriggered = true

    var body: some View {
        VStack(alignment: .leading) {
            // Other UI components
            Text("Order Confirmation")
                .font(.title)

            // Rokt placement using SwiftUI
            MPRoktLayout(
                sdkTriggered: $sdkTriggered,
                identifier: "RoktExperience",
                locationName: "RoktEmbedded1", // For embedded placements
                attributes: attributes,
                config: roktConfig, // Optional RoktConfig
                onEvent: { roktEvent in
                    // Optional: Handle different event types see above
                }
            ).roktLayout
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
    }
}

パラメータ	型	説明
sdkTriggered	Bool	プレースメントをトリガーするタイミングを制御します。
identifier	String	Rokt プレースメント識別子 (例: "RoktExperience")。
locationName	String?	埋め込みプレースメントのためのオプションのロケーション名 (例: "RoktEmbedded1")。
attributes	[String: String]	プレースメントに渡す属性の辞書。
config	RoktConfig?	カラーモード、キャッシングなどのオプションの設定オブジェクト。
onEvent	((RoktEvent) -> Void)?	すべてのプレースメントイベントを処理するためのオプションのコールバック。

Appendix C: Jetpack ComposeでのRoktLayoutサポート（Androidのみ）

Jetpack Composeを使用して実装された画面に対して、SDK+はRokt配置のモダンで宣言的な統合を可能にするRoktLayoutコンポーザブルを提供します。RoktLayoutは、selectPlacementsを手動で呼び出すことなく、Overlay、BottomSheet、およびEmbedded配置タイプをサポートします。

Jetpack Compose placement with RoktLayout

import com.mparticle.kits.RoktLayout
import com.mparticle.MpRoktEventCallback
import com.mparticle.UnloadReasons

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        val attributes = mapOf(
            "email" to "j.smith@example.com",
            "firstname" to "Jenny",
            "lastname" to "Smith",
            "mobile" to "(323) 867-5309",
            "postcode" to "90210",
            "country" to "US"
        )
        val callbacks = object : MpRoktEventCallback {
            override fun onLoad() = println("View loaded")
            override fun onUnload(reason: UnloadReasons) = println("View unloaded due to: $reason")
            override fun onShouldShowLoadingIndicator() = println("Show loading indicator")
            override fun onShouldHideLoadingIndicator() = println("Hide loading indicator")
        }
        val roktConfig = RoktConfig.Builder()
            .colorMode(RoktConfig.ColorMode.DARK)
            .cacheConfig(CacheConfig(
                cacheDurationInSeconds = 1200,
                cacheAttributes = mapOf("email" to "j.smith@example.com")
            ))
            .build()

        RoktLayout(
            sdkTriggered = true,
            identifier = "RoktExperience",
            attributes = attributes,
            location = "Location1",
            modifier = Modifier
                .fillMaxWidth()
                .background(Color.Black),
            mpRoktEventCallback = callbacks,
            config = roktConfig
        )
    }
}

パラメータ

パラメータ	型	説明
sdkTriggered	Boolean	配置がトリガーされるタイミングを制御します。
identifier	String	Roktエクスペリエンスの識別子（例: "RoktExperience"）。
location	String?	埋め込み配置のためのオプションのロケーション名（例: "Location1"）。
attributes	Map<String, String>	配置に渡す属性のマップ。
modifier	Modifier	レイアウト、スタイリング、UIの動作をカスタマイズするためのCompose Modifier。
mpRoktEventCallback	MpRoktEventCallback	配置イベント（ロード、アンロード、ロード状態）を処理するためのオプションのコールバック。
config	RoktConfig?	カラーモード、キャッシングなどのためのオプションの設定。

Appendix D: エラーハンドリング

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

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

IDSync error handling

import 'package:mparticle_flutter_sdk/identity/identity_api_result.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_error_response.dart';

mpInstance?.identity
    .identify(identityRequest: identityRequest)
    .then(
        (IdentityApiResult successResponse) {
            // Proceed with the identified user
        },
        onError: (error) {
            var failureResponse = error as IdentityAPIErrorResponse;
            // Inspect failureResponse.statusCode to determine the error type:
            // - Check for network errors (device offline) and retry the request
            // - Check for throttle errors (429) and retry with backoff
            print('Identity error: $failureResponse');
        }
    );

クライアント側エラーコード (iOS)

MPIdentityErrorResponseCode enumは以下のクライアント側コードを定義しています：

MPIdentityErrorResponseCode	説明
MPIdentityErrorResponseCodeRequestInProgress	IDSync HTTPリクエストが既に進行中のため、実行されませんでした。
MPIdentityErrorResponseCodeClientSideTimeout	TCP接続のタイムアウトによりIDSync HTTPリクエストが失敗しました。
MPIdentityErrorResponseCodeClientNoConnection	ネットワークカバレッジがないためIDSync HTTPリクエストが失敗しました。
MPIdentityErrorResponseCodeSSLError	SSL設定の問題によりIDSync HTTPリクエストが失敗しました。
MPIdentityErrorResponseCodeOptOut	オプトアウトによりSDK+が無効化されているためIDSync HTTPリクエストが実行されませんでした。
MPIdentityErrorResponseCodeUnknown	不明なエラーによりIDSync HTTPリクエストが失敗しました。

Androidエラーコード

Android SDK+は、デバイスのカバレッジ外、クライアント側のタイムアウト、または無効なIDリクエストを含むクライアント側の問題に対してIdentityApi.UNKNOWN_ERRORを返します。THROTTLE_ERROR (HTTP 429) を確認し、遭遇した場合はバックオフを使用して再試行してください。

HTTPステータスコード

値	説明
400	無効なリクエストボディによりIDSync HTTP呼び出しが失敗しました。
401	認証エラーによりIDSync HTTP呼び出しが失敗しました。APIキーが正しいことを確認してください。
429	IDSync HTTP呼び出しがスロットルされ、再試行する必要があります。
5xx	Roktサーバー側の問題によりIDSync HTTP呼び出しが失敗しました。追加情報についてはアカウント担当者にお問い合わせください。

Appendix E: セッションIDをWebからネイティブに渡す

ユーザージャーニーがWebとネイティブプラットフォームの両方にまたがる場合、Web SDK+からFlutter 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;

iOSでのセッションIDの設定

ディープリンクからセッションIDを抽出し、selectPlacementsを呼び出す前にSDK+に渡します。これをAppDelegate.swiftに追加します：

Handle deep link and set sessionId (iOS)

func handleDeepLink(url: URL) {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
    if let sessionId = components?.queryItems?.first(where: { $0.name == "sessionId" })?.value {
        MParticle.sharedInstance().rokt.setSessionId(sessionId: sessionId)
    }
    // Proceed with your confirmation flow
}

AndroidでのセッションIDの設定

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

Handle deep link and set sessionId (Android)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    intent.data?.getQueryParameter("sessionId")?.let { sessionId ->
        MParticle.getInstance()?.Rokt()?.setSessionId(sessionId)
    }

    // Proceed with your confirmation flow
}

注意事項

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

付録 F: Shoppable Adsの支払いを設定する（iOSのみ）

Shoppable Adsを使用しない場合、このステップはスキップしてください。

iOS上のShoppable Adsは、登録されたRoktPaymentExtension（ネイティブiOS）が必要で、複数の支払い方法をサポートします。拡張機能の登録は、リダイレクトベースの方法のみを提供する場合でも、すべてのShoppable Adsの配置において必須です。登録およびリダイレクト転送のスニペットは、Show a PlacementステップのShoppable Ads（インタースティシャル）ターゲットにあります。

方法	iOS設定
Apple Pay	Apple Pay商人IDはapplePayMerchantIdとしてRoktPaymentExtensionに渡されます。オプションです。
PayPal	Rokt SDK+に組み込まれており、追加の拡張構成は不要です。リダイレクトURLの転送が必要です。
Afterpay / Clearpay	Info.plistにカスタムURLスキームを設定し、urlSchemeをRoktPaymentExtensionに設定し、リダイレクトURLの転送を行います。
Card Forwarding	パートナー支払い共有API + partnerpaymentreference / last4digits属性をselectShoppableAdsに設定します。

注記

Apple Payはオプションです — Shoppable AdsはApple Pay商人IDなしでも組み込みのPayPalとカード転送をサポートします。拡張機能を作成する際には、少なくともapplePayMerchantIdまたはurlSchemeのいずれかを提供する必要があります。mParticle Roktキット設定でstripePublishableKeyを設定してください。このキットはRoktに自動的に転送します。

Apple Payを提供するには、Apple Pay商人IDを作成し、Xcodeプロジェクトを設定し、Apple Pay — iOS設定に従って支払い処理証明書を生成し、商人IDをapplePayMerchantIdとして渡します。

8. Test Your Integration#

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

1Enable verbose SDK+ logging#

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

Enable verbose SDK+ logging

// Enable mParticle debug logging at the Dart level
MparticleFlutterSdk.setLogLevel(LogLevel.verbose);

2Build and run against a development environment#

ネイティブ側で開発環境を設定してアプリをビルドおよび実行します:

• iOS: environment = .development (Swift) または MPEnvironmentDevelopment (Objective-C)
• Android: MParticle.Environment.Development
• Web: isDevelopmentMode: true

3Trigger selectPlacements#

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

4Verify events#

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

• iOS: XcodeコンソールでRokt SDK+のログ出力を確認します。
• Android: Android StudioのLogcatでRokt SDK+のログ出力を確認します。
• Web: 開発者ツールを開き、Networkタブに移動し、experiencesでフィルタリングし、ステータス200の/experiencesリクエストが発生することを確認します。

トラブルシューティング

プレースメントが表示されない、またはイベントが表示されない場合は、プラットフォームのデバッグコンソールでRokt SDK+のエラーを確認してください。一般的な問題:

初期化エラー

• keyとsecret（iOS/Android）またはAPI_KEY（Web）が、Roktアカウントマネージャーから提供された値と一致していることを確認してください。
• ネイティブSDK+の初期化が、DartコードからのselectPlacementsやlogEventの呼び出しの前に実行されていることを確認してください。
• Androidでは、ルートActivityがFlutterFragmentActivityを継承していることを確認してください。
• iOSでのShoppable Adsの場合、SDK+の初期化後、RoktPaymentExtensionが登録され、selectShoppableAdsの前であることを確認してください。

アイデンティティエラー

identify呼び出しのonErrorハンドラーが発火した場合、IdentityAPIErrorResponseを調査し、ステータスコードを確認し、ビジネスロジックに従ってリクエストを再試行してください。エラーハンドリングがない場合、スケールでデータの一貫性の問題が発生する可能性があります。

プレースメントが表示されない

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