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

MAUI SDK+ 統合ガイド

Platform
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 MAUI SDK+の実装方法について説明します。SDK+は、設定された画面でユーザーとトランザクションデータをRoktに渡し、Roktが確認画面でのオファーなどの関連するエクスペリエンスを表示できるようにします。

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

プロジェクトにSDK+パッケージを追加します:

Add SDK+ packages
dotnet add package mParticle.MAUI
dotnet add package mParticle.MAUI.Kits.Rokt
dotnet add package mParticle.MAUI.Kits.Rokt.Payments

mParticle.MAUI.Kits.Rokt.Paymentsには、コアRoktキットがトランジティブに含まれています。

注記

Androidの場合、アクティビティがMauiAppCompatActivityを拡張していることを確認する必要があります。

2. Initialize the Rokt SDK+#

アプリケーションのスタートアップに次の初期化スニペットを挿入します。SDK+は他のSDK+ API呼び出しの前に初期化される必要があります。your-keyとyour-secretをRoktチームから提供されたキーとシークレットに置き換えてください。

SDK+ initialization
using mParticle.MAUI;

string key = "";
string secret = "";
#if __ANDROID__
  key = "your-key";
  secret = "your-secret";
#elif __IOS__
  key = "your-key";
  secret = "your-secret";
#endif

// Initialize the SDK+
var options = new MParticleOptions()
{
  ApiKey = key,
  ApiSecret = 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 = mParticle.MAUI.Environment.Development;

// Enter your custom subdomain if you are using a first-party domain configuration (optional)
options.NetworkOptions = new NetworkOptions()
{
  CustomBaseUrl = "https://rkt.example.com"
};

// Identify the current user:
var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
#if __ANDROID__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.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.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.MobileNumber, "+13125551515" },
  { UserIdentity.CustomerId, "cust_10482" }
#elif __IOS__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.Other, "SHA-256 hashed email" },  // only if raw email unavailable
  // Customer phone number in E.164 format.
  { UserIdentity.MobileNumber, "+13125551515" },
  // If you can only provide a SHA-256-hashed mobile number, use Other2 instead of MobileNumber — do not pass both.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.CustomerId, "cust_10482" }
#endif
};

// If the user is identified with their email address, set additional user attributes.
options.IdentifyRequest = identifyRequest;

OnUserIdentified onIdentifyComplete = newUser =>
{
  if (newUser != null)
  {
      newUser.SetUserAttribute("example attribute key", "example attribute value");
  }
};
options.IdentityStateListener = onIdentifyComplete;

// Register the Rokt kit with mParticle before initialization
RoktKit.Register();

MParticle.Instance.Initialize(options);

アプリケーションのスタートアップに初期化スニペットを挿入すると、次のカスタマイズ可能なフィールドが表示されます:

1Entering your Rokt key and secret#

プラットフォーム固有のブロック内にyour-keyとyour-secretを設定し、Roktアカウントマネージャーから提供されたキーとシークレットの値に置き換えます。

2Setting your data environment#

options.EnvironmentをmParticle.MAUI.Environment.Developmentに設定してテスト中にデータを開発環境にルーティングし、mParticle.MAUI.Environment.Productionに設定して本番環境にライブ顧客活動を送信します。

3Entering a custom first-party domain#

First-Party Domain Configurationの指示に従い、options.NetworkOptions.CustomBaseUrlをカスタムサブドメインに設定してから、MParticle.Instance.Initialize(options)を呼び出します。トラフィックをRoktのデフォルトエンドポイントに送信するには、options.NetworkOptionsを省略します。

4Identifying your user and setting attributes#

identifyRequest.UserIdentitiesにおいて、ユーザーの生のハッシュされていないメールをUserIdentity.Emailを通じて渡します。ハッシュされたメールやその他の識別子については、Supported user identifiersを参照してください。識別された後、追加のユーザー属性を設定するためにIdentityStateListenerコールバックを使用します — 推奨されるリストについてはUser attributesを参照してください。

IdentityStateListener
OnUserIdentified onIdentifyComplete = newUser =>
{
  if (newUser != null)
  {
      newUser.SetUserAttribute("example attribute key", "example attribute value");
  }
};
options.IdentityStateListener = onIdentifyComplete;
注記

初期化スニペットには常にidentifyRequestを含めてください。初期化時にユーザーのメールがない場合は、UserIdentity.Emailエントリを省略してください — SDK+はそれでも初期化され、後でIdentify the userを通じてユーザーを識別できます。識別の失敗を処理する方法についてはError handlingを参照してください — エラーハンドリングがない場合、大規模なデータの整合性の問題が発生する可能性があります。

3. Identify the User#

SDK+ initialization scriptは、スクリプトの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オブジェクトを作成します。ユーザーの生の、ハッシュ化されていないメールアドレスをUserIdentity.Emailフィールドに統合する必要があります。

2Set additional user attributes via AddSuccessListener#

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

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

ユーザーのアクションに一致するメソッドにidentifyRequestを渡します:

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

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

例えば、Jane Smithという名前のユーザーで、メールがj.smith@example.com、電話番号が+13125551515、顧客IDがcust_10482の場合:

Identify the user
// 1. Create the identifyRequest object
var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
#if __ANDROID__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.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.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.MobileNumber, "+13125551515" },
  { UserIdentity.CustomerId, "cust_10482" }
#elif __IOS__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.Other, "SHA-256 hashed email" },  // only if raw email unavailable
  // Customer phone number in E.164 format.
  { UserIdentity.MobileNumber, "+13125551515" },
  // If you can only provide a SHA-256-hashed mobile number, use Other2 instead of MobileNumber — do not pass both.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.CustomerId, "cust_10482" }
#endif
};

// 2. User attributes are set using the AddSuccessListener callback
// 3. Call one of the following methods that best matches the user's action:
MParticle.Instance.Identity.Login(identifyRequest)
  .AddSuccessListener(result =>
  {
      result.User.SetUserAttribute("firstname", "Jane");
      result.User.SetUserAttribute("lastname", "Smith");
  }); // Call when the user logs in or creates an account
MParticle.Instance.Identity.Identify(identifyRequest)
  .AddSuccessListener(result =>
  {
      result.User.SetUserAttribute("firstname", "Jane");
      result.User.SetUserAttribute("lastname", "Smith");
  }); // Call when you obtain the user's email mid-session, but not during a login
MParticle.Instance.Identity.Logout(); // Call when the user logs out

4. Set User Attributes#

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

Set user attributes
using mParticle.MAUI;

// 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 = MParticle.Instance.Identity.CurrentUser;

// 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.SetUserAttribute("favorite-genres", string.Join(", ", new string[] { "documentary", "comedy", "romance", "drama" }));

// To remove a user attribute, call RemoveUserAttribute and pass in the attribute name.
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.Instance.LogScreenを呼び出します。情報辞書に追加のカスタム属性を含めます。

Log a screen view
MParticle.Instance.LogScreen(
  "homepage",
  new Dictionary<string, string>() { { "custom-attribute", "custom-value" } }
);

6. Show a Placement#

Roktがコンテンツを表示する支払い画面や確認画面ごとに、SelectPlacementsを呼び出します。画面タイプとテストまたは本番環境であるかを指定するために、以下のページ識別子のいずれかを含めてください:

  • 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.

画面が読み込まれた時点で、すべての関連属性が利用可能になったらすぐにSelectPlacementsを呼び出します。最低限、email、firstname、lastname、billingzipcode、およびconfirmationrefを渡します。完全なリストについてはPlacement attributesを参照してください。

Pay+

Pay+プレースメントの場合、各画面でのSelectPlacements呼び出しにpaymenttypeとpaymentServiceProviderを含めます。paymentServiceProviderは支払い画面で利用可能な支払い方法を伝え、paymenttypeはユーザーが支払った方法を伝えます。

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

これらの属性を 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）。関連性に使用されます。
cartItemsarrayカートラインオブジェクトの構造化された配列。関連性に使用されます。
adsexperiencestringShoppable Ads エクスペリエンスを意図的にターゲットにする場合は "shoppable" を渡します。
Placement position

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

Overlay placement
using mParticle.MAUI;

var attributes = new Dictionary<string, string>
{
  // 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"
};

MParticle.Instance.Rokt.SelectPlacements(
  identifier: "RoktExperience",
  attributes: attributes
);

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

機能目的
MParticle.Instance.Rokt.Close()オーバーレイプレースメントを自動的に閉じます。

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

RoktConfigなどのオプションパラメータを渡して、プレースメントUIをカスタマイズします（例：ダーク/ライトモード、キャッシング）。

SelectPlacements with RoktConfig
using mParticle.MAUI;

var roktConfig = new RoktConfig()
{
  ColorMode = RoktConfig.RoktColorMode.Light
};

MParticle.Instance.Rokt.SelectPlacements(
  identifier: "RoktExperience",
  attributes: attributes,
  config: roktConfig
);
注記

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

Events APIEvents API への直接リンク

SDK+は、MParticle.Instance.Rokt APIを通じて配置のライフサイクルイベントを提供します。 Eventsを使用して、配置識別子ごとにサブスクライブし、読み込み状態、準備完了、インタラクション、完了、および失敗に応答します。

Subscribe to placement events
void HandleRoktEvent(object roktEvent)
{
  switch (roktEvent.GetType().Name)
  {
      case "RoktShowLoadingIndicator":
          Console.WriteLine("Rokt is loading...");
          break;
      case "RoktHideLoadingIndicator":
          Console.WriteLine("Rokt finished loading.");
          break;
      case "RoktPlacementReady":
          Console.WriteLine("Placement is ready.");
          break;
      case "RoktPlacementInteractive":
          Console.WriteLine("Placement is interactive.");
          break;
      case "RoktPositiveEngagement":
      case "RoktFirstPositiveEngagement":
          Console.WriteLine("User positively engaged.");
          break;
      case "RoktPlacementCompleted":
          Console.WriteLine("Placement completed.");
          break;
      case "RoktPlacementFailure":
          Console.WriteLine("Placement failed or no fill.");
          break;
      default:
          Console.WriteLine($"Unhandled event: {roktEvent.GetType().Name}");
          break;
  }
}

MParticle.Instance.Rokt.Events("RoktExperience", roktEvent =>
{
  HandleRoktEvent(roktEvent);
});

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

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

7. Configure Apple Pay (iOS only)#

iOSでShoppable Adsを使用するにはApple Payが必要です。Shoppable Adsを使用しない場合、このステップをスキップしてください。

支払い拡張機能を登録する前に、Apple PayのマーチャントIDを作成し、Xcodeプロジェクトを設定し、支払い処理証明書を生成してください。

Apple Pay — iOS setupの手順に従い、その後iOS固有のプラットフォームコードでRoktPaymentExtensionを登録します。MAUIプロジェクトでは、これをiOSプラットフォームのAppDelegate.cs（またはMauiProgram.csの#if __IOS__ブロック内）に配置し、MParticle.Instance.Initialize(options)の後、SelectPlacementsやSelectShoppableAdsの呼び出しの前に呼び出します。

Register RoktPaymentExtension (iOS only)
#if __IOS__
// iOS only: register after MParticle.Instance.Initialize(options),
// before SelectPlacements/SelectShoppableAds.
RoktPaymentExtension.Register("merchant.com.yourapp.rokt");
#endif
注意

RoktPaymentExtensionは、MParticle.Instance.Initialize(options)の後、およびSelectPlacementsやSelectShoppableAdsの呼び出しの前に登録する必要があります。順序が正しくないと、Apple Payが正しく機能しません。

注記

RoktPaymentExtensionの登録に関する正確なC# APIは、MAUIバインディングのバージョンによって異なる場合があります。上記のメソッドシグネチャがNuGetパッケージと一致しない場合は、NuGetのリリースノートで同等の呼び出しを確認するか、バインディング固有のガイダンスについてRoktサポートにお問い合わせください。

8. Appendix#

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

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

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

値説明
Lightアプリケーションはライトモードです
Darkアプリケーションはダークモードです
Systemアプリケーションはシステムのカラーモードをデフォルトにします
RoktConfig with ColorMode
var roktConfig = new RoktConfig()
{
    ColorMode = RoktConfig.RoktColorMode.Light
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    config: roktConfig
);

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

パラメータ説明
CacheDurationInSecondsRokt SDK+ がエクスペリエンスをキャッシュする秒数のオプションの期間。最大許容値は90分です。提供されないか無効な場合、デフォルトは90分です。
CacheAttributesキャッシュキーとして使用するオプションの属性。null の場合、SelectPlacements で送信されたすべての属性がキャッシュキーとして使用されます。
Cache for 1200 seconds
var roktConfig = new RoktConfig()
{
    CacheConfig = new CacheConfig()
    {
        CacheDurationInSeconds = 1200,
        CacheAttributes = new Dictionary<string, string>()
        {
            { "email", "j.smith@example.com" },
            { "orderNumber", "123" }
        }
    }
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    config: roktConfig
);

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

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

この設定を Android のみにスコープするには、#if __ANDROID__ ブロックを使用します:

EdgeToEdgeDisplay (Android only)
#if __ANDROID__
var roktConfig = new RoktConfig()
{
    EdgeToEdgeDisplay = true
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    config: roktConfig
);
#endif

付録 B: MAUI 宣言型 UI サポート付録 B: MAUI 宣言型 UI サポート への直接リンク

MAUI SDK+ は、XML ベースのレイアウト (RoktEmbeddedView in XAML) とコードビハインドの配置統合の両方をサポートしています。XAML での埋め込み配置の場合、RoktEmbeddedViewHandler を MauiProgram.CreateMauiApp() に登録し、コードビハインドでビューをその x:Name で参照します（Embedded placements を参照）。

現時点では、MAUI に Jetpack Compose (RoktLayout) や SwiftUI (MPRoktLayout) に相当するものはありません。埋め込み配置には XML + コードビハインドパターンを使用してください。

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

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

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

失敗リスナーは errorResponse オブジェクトを受け取ります。HttpCode プロパティを使用して原因を特定し、再試行するかどうかを決定します。

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

Android では、IdentityApi.UNKNOWN_ERROR はクライアント側の失敗（デバイスがオフラインまたはクライアント側のタイムアウト）を示します — リクエストを再試行してください。HTTP 429 (IdentityApi.THROTTLE_ERROR) はリクエストがレート制限されたことを意味します — 指数バックオフで再試行してください。他の HTTP エラーコードは実装またはサーバーの問題を示しており、ログに記録して調査する必要があります。

IDSync error handling (Android)
#if __ANDROID__
MParticle.Instance.Identity.Identify(identifyRequest)
    .AddFailureListener(errorResponse =>
    {
        if (errorResponse.HttpCode == IdentityApi.UnknownError)
        {
            // Device is likely offline or client-side timeout — retry the request
        }
        else if (errorResponse.HttpCode == 429)
        {
            // Throttled — retry with exponential backoff
        }
        else
        {
            // Log errorResponse.HttpCode and investigate — likely an implementation issue
        }
    })
    .AddSuccessListener(result =>
    {
        // Proceed with the identified user
    });
#endif

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

iOS では、失敗リスナーの HttpCode はネイティブ iOS SDK+ の MPIdentityErrorResponseCode 値にマッピングされます。ネットワーク障害 (clientNoConnection, clientSideTimeout) はすぐに再試行する必要があります。スロットルエラー (HTTP 429、retry に対応) はバックオフで再試行する必要があります。requestInProgress は別の IDSync コールが進行中であることを意味します — これが頻繁に発生する場合は実装を確認し、その後再試行してください。他のすべてのコードは通常、実装の問題を示します。errorResponse の詳細を確認して診断してください。

IDSync error handling (iOS)
#if __IOS__
MParticle.Instance.Identity.Identify(identifyRequest)
    .AddFailureListener(errorResponse =>
    {
        if (errorResponse.HttpCode == IdentityApi.UnknownError)
        {
            // clientNoConnection or clientSideTimeout — device is offline or timed out, retry the request
        }
        else if (errorResponse.HttpCode == 429)
        {
            // Throttled (MPIdentityErrorResponseCodeRetry) — retry with exponential backoff
        }
        else if (errorResponse.HttpCode == (int)IdentityApi.RequestInProgress)
        {
            // Another IDSync request is already in progress — inspect implementation frequency, then retry
        }
        else
        {
            // Log errorResponse details and investigate — likely an implementation issue
        }
    })
    .AddSuccessListener(result =>
    {
        // Proceed with the identified user
    });
#endif
注記

上記のC#定数名 (IdentityApi.UnknownError, IdentityApi.RequestInProgress) は、MAUIバインディングレイヤーを反映しています。NuGetバージョンが異なる定数名を公開している場合、それらは基盤となるiOSのMPIdentityErrorResponseCode値にマッピングされます:

MAUI C#定数iOS MPIdentityErrorResponseCode
IdentityApi.UnknownErrorclientNoConnection, clientSideTimeout, または unknown
IdentityApi.RequestInProgressrequestInProgress
HTTP 429retry (スロットル)

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

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

Handle deep link and set sessionId
// Extract sessionId from the incoming deep link URI
// and set it on the Rokt SDK+ before calling SelectPlacements
var uri = new Uri(deepLinkUrl);
var query = System.Web.HttpUtility.ParseQueryString(uri.Query);
var sessionId = query["sessionId"];

if (!string.IsNullOrEmpty(sessionId))
{
    MParticle.Instance.Rokt.SetSessionId(sessionId);
}

// Proceed with your confirmation flow

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

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

9. Test Your Integration#

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

1Enable verbose SDK+ logging#

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

Enable verbose SDK+ logging
#if __ANDROID__
  MParticle.Instance.SetLogLevel(LogLevel.Verbose);
#elif __IOS__
  MParticle.Instance.SetLogLevel(LogLevel.Verbose);
#endif

2Build and run against a development key#

アプリをビルドして実行し、options.Environment = mParticle.MAUI.Environment.Developmentを設定します。

3Trigger SelectPlacements#

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

4Verify events#

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

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

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

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

  • プラットフォーム固有のブロック内のキーとシークレットが、Roktアカウントマネージャーから提供された値と一致していることを確認してください。
  • MParticle.Instance.Initialize(options) が、SelectPlacements または LogEvent の呼び出しの前に実行されることを確認してください。
  • RoktKit.Register() が MParticle.Instance.Initialize(options) の前に呼び出されることを確認してください。

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

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

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

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