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

Flutter SDK+ 統合ガイド

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

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

サポートされているユーザー識別子を表示
識別子タイプ説明
emailstring顧客の生のハッシュされていないメールアドレスを渡します。
mobile_numberstring顧客の電話番号をE.164形式で渡します。
customerIdstring内部の顧客/アカウント識別子を渡します。ログインしているユーザーには、すべての画面で送信します。
otherstringSHA-256でハッシュされたメールを渡します。生のメールが提供できない場合のみ使用します — email と other の両方を渡さないでください。
other2stringSHA-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');

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

収集可能な限り、以下の属性を設定してください:

すべてのユーザー属性を表示
属性型説明
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言語コード。関連性に使用されます。
citystring請求先の都市。関連性に使用されます。
statestring請求先の州/県/地域。関連性と適格性に使用されます。
zipstring完全なZIPまたは郵便番号（米国の優先はZIP+4）。アイデンティティ解決と関連性に使用されます。
countrystringISO 3166-1 alpha-2国コード（例: US, GB, AU）。適格性と関連性に使用されます。
newcustomerboolean初回購入者かどうか。関連性に使用されます。
customertypestringユーザーが認証済みかどうか（guest / logged_in）。関連性に使用されます。
loyaltytierstringパートナーのロイヤルティプログラムの階層。関連性と適格性に使用されます。
loyaltyidstringロイヤルティプログラムのメンバーID。アイデンティティ解決に使用されます。
lifetime_valuedecimal顧客の累積購入価値。文字列として（例: "52.25"）。関連性に使用されます。
predictedltvdecimal通常はパートナーのMLモデルからの予測された総生涯価値。lifetime_value とは異なります。関連性に使用されます。
subscriptionstatusstring該当する場合のサブスクリプション状態 (active、trial、churned、paused、none)。関連性と適格性のために使用されます。
customersegmentstringパートナー内部のセグメンテーション（例: vip、at_risk、new、reactivated）。関連性のために使用されます。
utmsourcestringマーケティング帰属ソース。関連性のために使用されます。
utmmediumstringマーケティング帰属メディア。関連性のために使用されます。
utmcampaignstringマーケティング帰属キャンペーン。関連性のために使用されます。

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

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 呼び出しを上書きするため、常に最新の値を提供してください。

すべての配置属性を表示する
属性型説明
emailstring顧客のメールアドレス（ハッシュ化されていない）。アイデンティティ解決に使用されます。
firstnamestring顧客の名。パーソナライゼーションに使用されます。
lastnamestring顧客の姓。パーソナライゼーションに使用されます。
mobilestringE.164形式の顧客の携帯電話番号。アイデンティティ解決に使用されます。
confirmationrefstring注文/確認参照番号。関連性と重複排除に使用されます。
currencystring取引通貨（ISO 4217、例: USD, GBP, AUD）。関連性に使用されます。
countrystringISO 3166-1 alpha-2 国コード。適格性と関連性に使用されます。
languagestring顧客の希望言語（ISO 639-1）。関連性に使用されます。
totalpricedecimal税金と送料を含むカートの合計金額。関連性に使用されます。
amountstring税金と送料を除くカートの小計。totalprice とは異なります。関連性とShoppable Adsに使用されます。
cartitemcountintegerカート内のアイテム数。関連性に使用されます。
cartItemsarrayカートラインオブジェクトの構造化された配列（Flutter Webのみ）。Commerce Eventsのカートアイテムを参照してください。関連性に使用されます。
couponcodestring注文に適用されたプロモーションコード（ある場合）。関連性に使用されます。
newcustomerboolean初回購入者かどうか。関連性に使用されます。
customertypestringguest または logged_in。関連性に使用されます。
lifetime_valuedecimal顧客の累積購入価値（例: "2340.00"）。関連性に使用されます。
subscriptionstatusstring該当する場合のサブスクリプション状態（active, trial, churned, paused, none）。関連性と適格性に使用されます。
customersegmentstringパートナー内部のセグメンテーション（例: vip, at_risk, new, reactivated）。関連性のために使用されます。
paymenttypestring選択された支払い方法（credit_card, paypal, apple_pay など）。Pay+ の適格性と Shoppable Ads の支払い方法の優先順位付けに使用されます。
paymentServiceProviderstringページ上で提供される支払いサービス（apple_pay, paypal, card）。Pay+ の適格性に使用されます。
ccbinstringクレジットカードのBIN（6-8桁）。関連性のために使用されます。
billingaddress1string請求先の住所。アイデンティティ解決と関連性のために使用されます。
billingaddress2string請求先のアパート/ユニット。アイデンティティ解決のために使用されます。
billingcitystring請求先の市区町村。関連性のために使用されます。
billingstatestring請求先の州または省。関連性のために使用されます。
billingzipcodestring請求先の郵便番号。アイデンティティ解決と関連性のために使用されます。
shippingmethodstring選択された配送方法（standard, express, next_day）。関連性のために使用されます。
shippingaddress1string配送先の住所。関連性と Shoppable Ads の注文履行のために使用されます。
shippingcitystring配送先の市区町村。関連性と Shoppable Ads の注文履行のために使用されます。
shippingstatestring配送先の州または省。関連性と Shoppable Ads の注文履行のために使用されます。
shippingzipcodestring配送先の郵便番号。関連性と Shoppable Ads の注文履行のために使用されます。
shippingcountrystring配送先の国（ISO 3166-1 alpha-2）。関連性と Shoppable Ads の注文履行のために使用されます。
adsexperiencestringShoppable 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 APIEvents 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');
});

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

すべての標準イベントを表示
イベント説明パラメータ
ShowLoadingIndicatorSDK+がRoktバックエンドを呼び出す前にトリガーされます。
HideLoadingIndicatorSDK+が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
CartItemDevicePayApple Pay / デバイス支払いがトリガーされました（Shoppable Ads、iOSのみ）。identifier: String, catalogItemId: String, cartItemId: String, paymentProvider: String
InstantPurchaseDismissalユーザーが購入オーバーレイを却下しました（Shoppable Ads、iOSのみ）。identifier: String

7. Appendix#

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

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

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

値説明
lightアプリケーションがライトモードであること
darkアプリケーションがダークモードであること
systemアプリケーションがシステムのカラーモードにデフォルト設定されていること
RoktConfig with ColorMode
final roktConfig = RoktConfig(
    colorMode: ColorMode.light,
);

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

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

Appendix C: Jetpack ComposeでのRoktLayoutサポート（Androidのみ）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
        )
    }
}

パラメータパラメータ への直接リンク

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

Appendix D: エラーハンドリング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)クライアント側エラーコード (iOS) への直接リンク

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

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

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

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

HTTPステータスコードHTTPステータスコード への直接リンク

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

Appendix E: セッションIDをWebからネイティブに渡すAppendix E: セッションIDをWebからネイティブに渡す への直接リンク

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

iOSでのセッションIDの設定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の設定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のみ）付録 F: Shoppable Adsの支払いを設定する（iOSのみ） への直接リンク

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

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

方法iOS設定
Apple PayApple Pay商人IDはapplePayMerchantIdとしてRoktPaymentExtensionに渡されます。オプションです。
PayPalRokt SDK+に組み込まれており、追加の拡張構成は不要です。リダイレクトURLの転送が必要です。
Afterpay / ClearpayInfo.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が含まれていることを確認してください。
この記事は役に立ちましたか？