Web SDK+ 統合ガイド

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

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

1. Initialize the Rokt SDK+#

サイトのすべてのページにSDK+の初期化スクリプトを含めます。ブラウザのキャッシュにより、SDK+は後続のページでキャッシュから読み込まれ、再取得されません。

シングルページアプリの場合: スクリプトをメインのindex.htmlのheadに挿入するか、コンテンツがレンダリングされる場所に挿入します。

マルチページアプリの場合: スクリプトを主要な共有レイアウトファイルに配置します。テンプレートベースのレンダリングシステムを使用していない場合は、各HTMLファイルに追加します。

ファーストパーティドメインの設定

Web SDK+をサイトに統合する際にファーストパーティドメインを使用することで、SDK+がRoktのAPIへの呼び出し時に自分のドメインを使用し、顧客にシームレスな体験を提供し、コンテンツがブロックされるリスクを最小限に抑えます。SDK+統合のためのファーストパーティドメインの設定方法については、ファーストパーティドメイン統合を参照してください。

Rokt Web SDK+ initialization

<script type="text/javascript">

// Enter your Rokt API key
const API_KEY = "YOUR_API_KEY";

// Enter your custom subdomain if you are using a first-party domain configuration (optional)
const ROKT_DOMAIN = "https://apps.rokt-api.com";

window.mParticle = {
  config: {
      // Set the data environment:
      // Set isDevelopmentMode to true if you are still testing your integration. 
      // Set isDevelopmentMode to false if your integration is ready for production data.
      isDevelopmentMode: true,
      // Identify the current user:
      // If you do not have the user's email address, you can pass in a null value
      identifyRequest: {
          userIdentities: {
              // If you're using an un-hashed email address, set it in 'email' (preferred).
              email: 'j.smith@example.com',
              // If you're using a hashed email address, set it in 'email_sha256' instead of 'email'.
              email_sha256: 'sha256 hashed email goes here',
              // Customer phone number in E.164 format.
              mobile_number: '+13125551515',
              // If you're using a hashed mobile number, set it in 'mobile_sha256' instead of 'mobile_number'.
              mobile_sha256: 'sha256 hashed mobile goes here',
              // Partner's internal customer/account identifier (if the user is logged in).
              customerid: 'cust_10482'
          }
      },
      // If the user is identified with their email address, set additional user attributes.
      identityCallback: function(result) {
          if (result.getUser()) {
              result.getUser().setUserAttribute('attribute_key', 'attribute_value');
          }
      }
  }
};

// Load the SDK+
(function(e) { window.mParticle = window.mParticle || {}; window.mParticle.EventType = { Unknown: 0, Navigation: 1, Location: 2, Search: 3, Transaction: 4, UserContent: 5, UserPreference: 6, Social: 7, Other: 8, Media: 9 }; window.mParticle.eCommerce = { Cart: {} }; window.mParticle.Identity = {}; window.mParticle.Rokt = {}; window.mParticle.config = window.mParticle.config || {}; window.mParticle.config.rq = []; window.mParticle.config.snippetVersion = 2.8; window.mParticle.ready = function(e) { window.mParticle.config.rq.push(e); }; ["endSession", "logError", "logBaseEvent", "logEvent", "logForm", "logLink", "logPageView", "setSessionAttribute", "setAppName", "setAppVersion", "setOptOut", "setPosition", "startNewSession", "startTrackingLocation", "stopTrackingLocation"].forEach(function(e) { window.mParticle[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift(e); window.mParticle.config.rq.push(t); }; }); ["setCurrencyCode", "logCheckout"].forEach(function(e) { window.mParticle.eCommerce[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("eCommerce." + e); window.mParticle.config.rq.push(t); }; }); ["identify", "login", "logout", "modify"].forEach(function(e) { window.mParticle.Identity[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Identity." + e); window.mParticle.config.rq.push(t); }; }); ["selectPlacements","hashAttributes","hashSha256","setExtensionData","use","getVersion","terminate","onShoppableAdsReady"].forEach(function(e) { window.mParticle.Rokt[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Rokt." + e); window.mParticle.config.rq.push(t); }; }); var t = window.mParticle.config.isDevelopmentMode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan; if (a) { var o = a.planId, r = a.planVersion; o && (r && (r < 1 || r > 1e3) && (r = null), n += "&plan_id=" + o + (r ? "&plan_version=" + r : "")); } var i = window.mParticle.config.versions, s = []; i && Object.keys(i).forEach(function(e) { s.push(e + "=" + i[e]); }); var c = document.createElement("script"); c.type = "text/javascript"; c.async = !0; window.ROKT_DOMAIN = ROKT_DOMAIN || 'https://apps.rokt-api.com'; mParticle.config.domain = ROKT_DOMAIN.split('//')[1]; c.src = ROKT_DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); c.onerror = function() { var u = ["https://apps.","rokt","ecommerce",".com"].join(""); window.ROKT_DOMAIN = u; mParticle.config.domain = u.split("//")[1]; var d = document.createElement("script"); d.type = "text/javascript"; d.async = !0; d.src = u + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var f = document.getElementsByTagName("script")[0]; f.parentNode.insertBefore(d, f); }; var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

初期化スクリプトをサイトに挿入すると、カスタマイズ可能なフィールドが表示されます:

1Entering your Rokt API key#

API_KEYをRoktアカウントマネージャーから提供されたRokt APIキーに設定します。

2Entering a custom first-party domain#

ファーストパーティドメインの設定の指示に従い、ROKT_DOMAINをカスタムサブドメインに設定します。Rokt SDK+を自分のドメイン経由でルーティングすることで、広告ブロッカーやブラウザによる広告やデータのブロックのリスクを減らします。

3Setting your data environment#

テスト中はisDevelopmentModeをtrueに設定してデータを開発環境にルーティングし、本番環境にライブの顧客活動を送信するにはfalseに設定します。

4Identifying your user and setting attributes#

identifyRequestでは、ユーザーの生のハッシュ化されていないメールをemailフィールドに渡します。利用可能な場合は、mobile_numberとcustomeridを含めます。より多くのシグナルがアイデンティティ解決を向上させます。識別された後、追加のユーザー属性を設定するためにidentityCallbackを使用します。推奨される属性のリストについては、ユーザー属性を参照してください。

identityCallback

// The identityCallback determines if the identifyRequest was successful.
identityCallback: function(result) {
    if (result.getUser()) {
        // If the user was identified, set additional user attributes with setUserAttribute.
        result.getUser().setUserAttribute('attribute_key', 'attribute_value');
    }
}

注記

初期化スクリプトには常にidentifyRequestを含めてください。初期化時にユーザーのメールがない場合は、emailをnullに設定してください — SDK+はそれでも初期化され、後でステップ2を通じてユーザーを識別できます。

2. Identify the User#

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

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

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

フィールド	タイプ	説明
email	string	生のハッシュされていないメールアドレス。
email_sha256	string	SHA-256でハッシュされたメール。ハッシュされた形式のみが利用可能な場合は、emailの代わりに使用します。
mobile_sha256	string	SHA-256でハッシュされた携帯番号。ハッシュされた形式のみが利用可能な場合は、mobile_numberの代わりに使用します。
mobile_number	string	E.164形式の電話番号（例: +13125551515）。
customerid	string	内部の顧客/アカウント識別子。ログインしているユーザーにはすべてのページで送信します。

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

1Create an identifyRequest object#

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

2Create an identityCallback#

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

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

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

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

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

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

Example user identification

// 1. Create the identifyRequest object
const identifyRequest = {
  userIdentities: {
      email: 'j.smith@example.com',
      // If you are passing a hashed email address, set it inside the 'email_sha256' field instead of 'email'.
      email_sha256: 'SHA-256 hashed email address',
      mobile_number: '+13125551515',
      // If you are passing a hashed mobile number, set it inside the 'mobile_sha256' field instead of 'mobile_number'.
      mobile_sha256: 'SHA-256 hashed mobile number',
      customerid: 'cust_10482'
  }
};
// 2. User attributes are set using identityCallback
const identityCallback = function(result) {
  if (result.getUser()) {
      result.getUser().setUserAttribute('firstname', 'Jane');
      result.getUser().setUserAttribute('lastname', 'Smith');
  }
};
// 3. Call one of the following methods that best matches the user's action:
mParticle.Identity.login(identifyRequest, identityCallback); // Call when the user logs in or creates an account
mParticle.Identity.identify(identifyRequest, identityCallback); // Call when you obtain the user's email mid-session, but not during a login
mParticle.Identity.logout({}); // Call when the user logs out

3. Set User Attributes#

完全な顧客ジャーニー全体を通じてユーザー属性を段階的に設定します。設定する属性が多いほど、Roktは顧客のアイデンティティを解決し、関連するオファーを提供することができます。

できるだけ早く属性を設定する

新しいユーザー属性が利用可能になるとすぐに設定します。早期の属性収集は、Roktに確認ページで表示される配置の速度と関連性を向上させるためのより多くのシグナルを提供します。

Set User Attributes

// To retrieve the current user, call getCurrentUser.
const currentUser = mParticle.Identity.getCurrentUser();

// Once you have successfully set the current user to a const called `currentUser`, you can set user attributes with:
currentUser.setUserAttribute("firstname", "Jane");
currentUser.setUserAttribute("lastname", "Smith");
currentUser.setUserAttribute("mobile_number", "+13125551515");
currentUser.setUserAttribute("birthyear", 1990);
currentUser.setUserAttribute("gender", "F");

// Address attributes (collect the billing address at checkout)
currentUser.setUserAttribute("billingaddress1", "123 Main St");
currentUser.setUserAttribute("billingaddress2", "Apt 4B");
currentUser.setUserAttribute("billingcity", "Brooklyn");
currentUser.setUserAttribute("billingstate", "NY");
currentUser.setUserAttribute("billingzipcode", "11201");
currentUser.setUserAttribute("country", "US");

// Lifecycle and loyalty attributes
currentUser.setUserAttribute("customertype", "logged_in");
currentUser.setUserAttribute("newcustomer", false);
currentUser.setUserAttribute("loyaltytier", "gold");
currentUser.setUserAttribute("loyaltyid", "LOY-7781");
currentUser.setUserAttribute("customersegment", "vip");

// Marketing attribution
currentUser.setUserAttribute("utmsource", "google");
currentUser.setUserAttribute("utmmedium", "cpc");
currentUser.setUserAttribute("utmcampaign", "spring_sale");

// To set a list attribute, set the value of the attribute to an array of strings. For example:
currentUser.setUserAttribute("favorite_genres", ["documentary", "comedy", "romance", "drama"]);

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

ユーザー属性

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

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

フィールド	タイプ	説明
firstname	string	顧客の名。パーソナライズに使用されます。
lastname	string	顧客の姓。パーソナライズに使用されます。
mobile_number	string	電話番号は 1112345678 または +1 (222) 345-6789 の形式で入力してください。識別解決と関連性に使用されます。
birthyear	integer	顧客の生年（例: 1990）。推奨される生年月日フィールド。代替: dob (yyyymmdd)、age。適格性と関連性に使用されます。
dob	string	生年月日、yyyymmdd。birthyear の代替。適格性と関連性に使用されます。
age	integer	顧客の年齢。birthyear の代替。適格性と関連性に使用されます。
gender	string	顧客の性別。例: M、F、Male、または Female。関連性に使用されます。
title	string	敬称。例: Mr、Mrs、Ms。パーソナライズに使用されます。
language	string	購入に関連するISO 639-1言語コード。関連性に使用されます。
billingaddress1	string	住所（例: 123 Main St）。識別解決と関連性に使用されます。
billingaddress2	string	アパート/ユニット（例: Apt 4B）。識別解決に使用されます。
billingcity	string	請求先の市。関連性に使用されます。
billingstate	string	請求先の州/県/地域。関連性と適格性に使用されます。
billingzipcode	string	完全な郵便番号または郵便番号（米国の優先形式はZIP+4）。識別解決と関連性に使用されます。
country	string	ISO 3166-1 alpha-2国コード（例: US、GB、AU）。適格性と関連性に使用されます。
newcustomer	boolean	初回購入者であるかどうか（true / false）。関連性に使用されます。
customertype	string	ユーザーが認証されているかどうか（guest / logged_in）。関連性に使用されます。
loyaltytier	string	パートナーのロイヤルティプログラムの階層。関連性と適格性に使用されます。
loyaltyid	string	ロイヤルティプログラムのメンバーID。アイデンティティ解決に使用されます。
predictedltv	decimal	予測される総生涯価値。通常、パートナーの機械学習モデルによって生成されます。関連性のために使用されます。
subscriptionstatus	string	該当する場合のサブスクリプション状態 (active, trial, churned, paused, none)。関連性と適格性のために使用されます。
customersegment	string	パートナー内部のセグメンテーション（例: vip, at_risk, new, reactivated）。関連性のために使用されます。
acquisitionchannel	string	顧客が最初に獲得された方法。関連性のために使用されます。
utmsource	string	マーケティング帰属ソース。関連性のために使用されます。
utmmedium	string	マーケティング帰属メディア。関連性のために使用されます。
utmcampaign	string	マーケティング帰属キャンペーン。関連性のために使用されます。
utmcontent	string	マーケティング帰属コンテンツのバリアント。関連性のために使用されます。
utmterm	string	マーケティング帰属用語／キーワード。関連性のために使用されます。
referrer	string	リファラーURL — 意図のシグナル。関連性のために使用されます。

注記

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

4. Log Events#

ページビュー、コマースイベント、カスタムイベントをログに記録し、Roktが各顧客のジャーニーのどこにいるかを理解できるようにします。

Event category

ページビューは、顧客がどのページにいるかをRoktに伝えます。各呼び出しをmParticle.ready()でラップし、SDK+が初期化された後に発火するようにします。取引ページ（PLP、PDP、カート、チェックアウト、確認）では、Commerce eventsから対応するコマースイベントも発火し、製品および注文レベルの詳細を送信します。

Page type

顧客がサイトのホームページに到達したときにこれをログに記録します。/のような空のパスルートも含みます。

Field	Type	Description
screenname	string	Last segment of the URL path (e.g. /products/shoes → shoes). Defaults to home if the path is empty.
pagetype	string	Type of page being viewed: home, PLP, PDP, cart, checkout, confirmation.
url	string	Full URL of the current page.
title	string	Page title (from document.title).
sitesection	string	Top-level site section (e.g. mens, womens, support).
referringpage	string	Referring URL captured from document.referrer.

Example home page view

window.mParticle.ready(function() {
mParticle.logPageView("page_view", {
  screenname: "home",
  pagetype: "home",
  url: window.location.toString(),
  title: document.title,
  sitesection: "root",
  referringpage: document.referrer
});
});

5. Show a Placement#

Roktがコンテンツを表示するすべての支払いおよび確認ページで、selectPlacementsをサポートされているページ識別子と顧客＋トランザクション属性を使用して呼び出します。Roktはこれらのシグナルを使用して、最も関連性の高いオファーを選択し、表示します。

selectPlacementsで渡された属性は、setUserAttributeを介して以前に設定された値を上書きします。常に最新の値を提供してください。

ページ識別子

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

Placement position

配置位置に関係なく、同じセットの属性を渡します。完全な属性リファレンスは以下にあります。

すべての配置属性を表示

Field	Type	Description
email	string	Customer email address (unhashed). Used for identity resolution and Shoppable Ads order confirmation.
firstname	string	Customer first name. Used for personalization and Shoppable Ads order fulfillment.
lastname	string	Customer last name. Used for personalization and Shoppable Ads order fulfillment.
mobile_number	string	Customer mobile number (E.164 format, e.g. +13125551515). Used for identity resolution and Shoppable Ads.
confirmationref	string	Order / confirmation reference number. Used for relevance, deduplication, and Shoppable Ads order reconciliation.
currency	string	Transaction currency (ISO 4217, e.g. USD, GBP, AUD, JPY). Used for relevance and Shoppable Ads.
country	string	ISO 3166-1 alpha-2 country code. Used for eligibility and relevance.
language	string	Customer's preferred language (ISO 639-1, e.g. en, de, fr). Used for relevance.
totalprice	decimal	Total cart value including tax and shipping. Used for relevance.
amount	decimal	Cart subtotal before tax and shipping. Distinct from totalprice. Required for Pay+ on the payments page; also used by Shoppable Ads.
cartItems	array	Structured array of cart-line objects. See Cart items reference under Commerce Events. Used for relevance.
couponcode	string	Promo code applied, if any. Used for relevance.
newcustomer	boolean	Whether this is a first-time buyer. Used for relevance.
customertype	string	Whether the user is authenticated (guest / logged_in). Used for relevance.
value	decimal	Customer cumulative purchase value. Used for relevance.
subscriptionstatus	string	Subscription state if applicable (active, trial, churned, paused, none). Used for relevance and eligibility.
customersegment	string	Partner internal segmentation (vip, at_risk, new, reactivated). Used for relevance.
paymenttype	string	Payment method selected (credit_card, paypal, apple_pay, gift_card). Used for Pay+ eligibility and Shoppable Ads payment method prioritization.
paymentServiceProvider	string	Comma-separated list of payment methods accepted on the page (e.g. "cardpayment,paypal"). Accepted values: applepay, googlepay, paypal, venmo, affirm, afterpay, klarna, alipay, amazonpay, cardpayment, rakutenpay. Must be camelCase. Used for Pay+ eligibility.
ccbin	string	Credit card BIN (6-8 digits). Used for relevance.
billingaddress1	string	Billing street address. Used for identity resolution and relevance.
billingaddress2	string	Billing apartment/unit. Used for identity resolution.
billingcity	string	Billing city. Used for relevance.
billingstate	string	Billing state / region. Used for relevance.
billingzipcode	string	Billing ZIP / postcode. Used for identity resolution, relevance, and Shoppable Ads.
billingname	string	Full cardholder name on the billing address. Used for identity resolution and payment validation.
shippingmethod	string	Shipping method selected (standard, express, next_day). Used for relevance.
shippingname	string	Full recipient name on the shipping address. Used for Shoppable Ads order fulfillment.
shippingaddress1	string	Shipping street address. Used for relevance and Shoppable Ads order fulfillment.
shippingcity	string	Shipping city. Used for relevance and Shoppable Ads order fulfillment.
shippingstate	string	Shipping state / region. Used for relevance and Shoppable Ads order fulfillment.
shippingzipcode	string	Shipping ZIP / postcode. Used for relevance and Shoppable Ads order fulfillment.
shippingcountry	string	Shipping country (ISO 3166-1 alpha-2). Used for relevance and Shoppable Ads order fulfillment.
partnerpaymentreference	string	Non-guessable identifier used to look up the customer's vaulted payment method. Required for Shoppable Ads card forwarding; if absent, card forwarding is unavailable.
last4digits	string	Last 4 digits of the card used on the primary transaction. Displayed to the customer for confirmation during Shoppable Ads.
plcc	string	"yes" or "no" — whether the customer has a private-label credit card with the partner. Used for Pay+ relevance.
discountamount	decimal	Order-level discount applied (e.g. 10.00). Used for Pay+ relevance.
prescreen	string	"yes" or "no" — whether the customer has pre-qualified for a credit offer. Used for Pay+ relevance.

注記

カートアイテムをカンマ区切りの文字列や文字列化されたJSONブロブとして送信しないでください。フィールドが型付きのままになるように、実際のJSON配列を送信してください。カートアイテムフィールドの完全なリファレンスについては、Commerce Eventsのカートアイテムセクションを参照してください。

オーバーレイ配置は、確認ページ上にRoktが管理するコンテナでレンダリングされ、ページのDOMに変更を加える必要はありません。標準のThanks AdsおよびShoppable Adsに使用されます。

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

Example overlay selectPlacements call

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  identifier: "prod.rokt.conf",
  attributes: {
    // Identity
    email: "j.smith@example.com",
    firstname: "Jenny",
    lastname: "Smith",
    mobile_number: "+13125551515",

    // Transaction
    confirmationref: "ORDER-10482",
    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 + paymentServiceProvider for Pay+)
    paymenttype: "credit_card",
    paymentServiceProvider: "cardpayment",
    ccbin: "411112",

    // Cart contents — see the Placement Attributes reference for the full
    // attribute set and the Cart items reference for the per-line shape.
    cartItems: [
      { cartitemid: "SKU-001", productsku: "SKU-001", productname: "Trail Runner v3", itemprice: 129.95, quantity: 1 }
    ]
  }
});
});

6. Subscribe to Placement Events#

SDK+は配置ライフサイクル全体でイベントを発行します。配置が準備完了したとき、顧客が配置に関与したとき、またはインタースティシャル配置ラッパーが状態間を遷移するときにカスタムロジックを実行するためにこれらのイベントを購読してください。

Lifecycle event source

配置イベントを購読することで、配置が準備完了したときや顧客がオファーに関与したときにトリガーされる通知を受け取ることができます。

Subscribe to Placement Events

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  // add attributes
});

// Listen for when the placement becomes interactive/ready to display
selection.on('PLACEMENT_INTERACTIVE').subscribe(() => {
  // Logic to run after Placement has become interactive
});

// Listen for when user engages positively or negatively with an offer
selection.on('OFFER_ENGAGEMENT').subscribe(function () {
  // Logic to run after offer is engaged with
});
});

7. Appendix#

シングルページアプリでの配置の閉鎖、拡張機能の有効化による高度な機能、およびオプションのランチャー動作の設定に関するリファレンス。

配置を閉じる

シングルページアプリでは、ユーザーが移動した後に配置オブジェクトで.close()を呼び出して、配置がバックナビゲーションで残らないようにします。

Close a placement

// Closes the placement called 'selection'
selection.close();

Pay+

Pay+を使用している場合、ユーザーが離れた後にプレースメントを閉じる必要があります。

拡張機能による追加機能

一部の機能は拡張機能を必要とします。これらを有効にするには、mParticle.Rokt.use()をselectPlacements()の前に呼び出します。例えば、Thank Youページにアップセルプレースメントを表示するには、まずThankYouPageJourney拡張機能を有効にします:

Enable the ThankYouPageJourney extension

window.mParticle.ready(async function() {
// Enable the necessary extension prior to selecting placements
await window.mParticle.Rokt.use("ThankYouPageJourney");

const selection = await mParticle.Rokt.selectPlacements({
  identifier: "yourPageIdentifier",
  attributes: {
    "email": "j.smith@example.com"
    // Any additional user attributes you want to pass to Rokt
  },
});
})

追加のインテグレーションランチャーオプションの設定

初期化スクリプトでwindow.mParticle.config.launcherOptionsを設定することで、オプションの動作を構成します。

launcherOptions config

// Include this as part of the initialization script in step 1 above
window.mParticle.config.launcherOptions = {
  noFunctional: true,
  noTargeting: true,
  // See all optional launcher options that can be set below
};

顧客のクッキープリファレンスを管理する

機能的またはターゲティングクッキーを無効にすることで、顧客のオプトアウトプリファレンスを尊重するためにこれらのオプションを使用します。

パラメータ	型	デフォルト	説明
noFunctional	boolean	false	顧客が機能的クッキーをオプトアウトした場合に、RoktがファーストパーティトラッキングIDを使用しないようにするには、trueに設定します。機能的クッキーは、ファーストパーティのパーソナライゼーションやUpsellsのような高度なチェックアウト機能をサポートします。
noTargeting	boolean	false	顧客がターゲティングクッキーをオプトアウトした場合に、セッションのクロスサイトトラッキングIDを使用しないようにするには、trueに設定します。機能的識別子は、noFunctionalもtrueに設定されない限り、アクティブのままです。

詳細な議論については、Cookie Consent Flagsを参照してください。

シングルページアプリでのページロードパフォーマンスを測定する

仮想ページがロードされた時点のタイムスタンプを提供することで、RoktがSPAでのパフォーマンスを正確に測定し、顧客体験に影響を与える可能性のある異常を検出できるようにします。

パラメータ	型	デフォルト
pageInitTimestamp	Date	PerformanceNavigationTiming.responseStart

ランチャーがSPAの仮想ページで初期化されるとき、そのページが初期化された時点のタイムスタンプを渡すことで、Roktがそれをトリガーしたページに対するロードパフォーマンスを測定できるようにします。

顧客の活動をRoktセッションIDとリンクする

異なる体験の部分を正しく結びつけるために、以前に生成されたRoktセッションIDを渡します。

パラメータ	型	デフォルト
sessionId	string	—

以前のバックエンドインタラクションからRoktセッションIDを生成した場合、それをここで渡すことで、Roktがフロントエンドの活動とペアリングできるようにします。

体験内でのリンクの開き方をカスタマイズする

Roktや広告主のリンクがどのように開くかを完全に制御したい場合に、このオプションを有効にします（例えば、ブラウザではなくWebView内で）。

パラメータ	型	デフォルト
overrideLinkNavigation	boolean	false

trueに設定すると、Roktはリンクの開きを直接処理するのを停止し、代わりにLINK_NAVIGATION_REQUESTパートナーイベントを発行します。自分のリンクと区別するために、URLが"rokt.com"を含んでいるかどうかを確認してください。

selectPlacementsによって返される選択にイベントをサブスクライブします。各イベントは、顧客がアクティブにしたリンクを示す単一のurl文字列を持ちます。顧客体験を損なわないように、必要なコンテキスト（ブラウザタブ、WebViewなど）で直ちに開いてください。

Handle LINK_NAVIGATION_REQUEST

const selection = await window.mParticle.Rokt.selectPlacements({
  // identifier and attributes as in the examples above
});

selection.on("LINK_NAVIGATION_REQUEST").subscribe((event) => {
  // event.url is the link the customer activated — open it immediately
  window.open(event.url);
});

LINK_NAVIGATION_REQUESTイベントが3秒以内に消費されない場合、エラーが発生します。イベントを処理するためのアクティブなサブスクリプションが存在することを確認してください。

8. Test Your Integration#

SDK+が正しく初期化され、ユーザーを識別し、イベントをログし、オファーを要求することを確認するには:

1Open a new browser window#

新しいブラウザウィンドウを開いて、クリーンな状態で開始します。

2Open developer tools#

ブラウザの開発者ツールパネルを開きます。ほとんどのブラウザでは、画面を右クリックして検証をクリックすることでこれを行うことができます。

ページの読み込みをまたいでネットワークリクエストを保持するオプションを有効にします（Chrome、Edge、Safariではログを保持、Firefoxではログを永続化）。

3Filter network requests#

開発者ツールパネルから、ネットワークタブに移動し、rokt-api.comでフィルタリングします。カスタムファーストパーティドメインを使用している場合は、代わりにカスタムサブドメインでフィルタリングします。

特定のリクエストを見つけるには、エンドポイント名でフィルタリングすることもできます: /identity、/events、/experiences、または /offers。

4Run the test journey#

ネットワークタブを記録状態にして、SDK+を統合したページを通じてテストジャーニーを完了します。

注記

サイトに移動する前に開発者ツールパネルを開いて、ブラウザがすべてのSDK+リクエストを記録するようにします。

5Verify the identity request#

/identityでフィルタリングし、実行したアイデンティティアクションに一致するリクエストを選択します。例えば、identifyやloginです。成功ステータスであることを確認し、PayloadまたはRequestタブで送信する予定のテスト識別子を確認します。

6Verify page-view and commerce events#

/eventsでフィルタリングし、テストジャーニー中に生成されたリクエストを選択します。成功ステータスであることを確認します。PayloadまたはRequestタブで、リクエストにページビューまたはコマースイベントと送信する予定の属性が含まれていることを確認します。

イベントリクエストには複数のイベントが含まれる場合があるため、特定のアクションを確認する際には完全なリクエストペイロードを確認してください。

7Verify the selection request#

/experiences、次に/offersでフィルタリングします。SDK+のルーティングに応じて、成功した選択は次のエンドポイントのいずれかを使用します:

• /v1/experiences
• /v2/sessions/offers

これらのリクエストのいずれかを確認するだけで十分です。ステータス200のリクエストを選択し、PayloadまたはRequestタブでRoktと共有されているデータを確認します。

注記

テスト中に、ステータス204の/v1/experiencesリクエストが表示されることもあります。ペイロードを確認する際にはステータス200のリクエストを使用してください。

トラブルシューティング

統合が機能していない場合は、ブラウザの開発者ツールのコンソールタブでRokt SDK+のエラーを確認してください。一般的な問題には以下が含まれます：

初期化エラー

• SDK+の初期化スクリプトが正しいページに配置されていることを確認してください。
• タグマネージャーを使用して統合した場合、初期化が正しいページでロードされるようにタグトリガーを設定し、selectPlacementsとコンバージョンログタグがSDK+の初期化後に発火するようにしてください。

構文エラー

統合コードにカンマが欠落していないことを確認してください。

構文エラーを確認するには：

1Open the Console tab#

ブラウザの開発者ツールパネルに移動し、コンソールタブを選択します。

2Find the error#

Web SDK+を配置したファイルにエラーがある場合、それはコンソールに記録されます。ファイルをクリックしてコードと報告されたエラーを確認します。

3Verify commas#

ファイル内のエラーはすべて示されています。特に、すべての属性が以下のようにカンマで区切られていることを確認してください。

Missing comma (incorrect)

email: ''
mobile_number: '',

Correct

email: '',
mobile_number: '',