Web SDK インテグレーションガイド

このページでは、Rokt Ecommerce の Web SDK を実装して、チェックアウト時により関連性の高い顧客体験を提供する方法を説明します。SDK を使用すると、設定されたページで発火し、ユーザーおよびトランザクションデータを Rokt に渡してパーソナライズと測定を行うことにより、これらの体験（確認ページでのオファーの表示など）をトリガーして追跡することができます。

専任のアカウント担当者が、Web SDK のためのアカウント設定をサポートします。SDK を初期化するために必要な API キー と、顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。

注記

これらの指示を完了するには、開発リソースが必要です。追加の支援が必要な場合は、Rokt のアカウントマネージャーにお問い合わせください。Shopify ストアは、Rokt Ecommerce アプリを使用して数秒で Rokt プレースメントを設定できます — コーディングは不要です！

注記

まず開発環境で SDK を実装するために、Rokt のアカウントマネージャーと協力してください。これにより、本番環境でリリースする前に、統合を徹底的にテストおよびトラブルシューティングすることができます。

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

Roktは、SDKをサイトに統合する際にファーストパーティドメインを使用することを推奨します。これにより、Rokt SDKがRoktのAPIへの呼び出しを行う際に自社のドメインを使用し、顧客にシームレスな体験を提供し、コンテンツがブロックされるリスクを最小限に抑えることができます。

SDK統合のためのファーストパーティドメインの設定方法については、ファーストパーティドメイン統合を参照してください。

1. Rokt SDKの初期化

SDKを初期化するには、SDK初期化スクリプト全体をサイトにコピー＆ペーストしてください。

サイトはそれぞれ異なりますが、RoktはサイトのすべてのページにSDK初期化スクリプトを含めることを推奨します。これにより、SDKが常に初期化され、最小のオファー配信遅延と最高のユーザー識別精度を提供します。

シングルページアプリケーション (SPA): ウェブサイトがSPAの場合、初期化スクリプトをメインのindex.htmlページの<head>、または他のコンテンツがレンダリングされる主要な場所に挿入してください。
マルチページアプリケーション (MPA): ウェブサイトがMPAでテンプレートベースのレンダリングシステムを使用している場合（最も一般的）、初期化スクリプトを主要な共有レイアウトファイルに配置してください。テンプレートベースのレンダリングシステムを使用していない場合は、ウェブサイトの各HTMLファイルにスクリプトを配置してください。

各ページにスクリプトが含まれている場合でも、ブラウザのキャッシュにより、SDKはデフォルトでキャッシュからロードされ、ウェブサイトの各ページロード時に再ロードされることはありません。

SDK 初期化スクリプト

<script type="text/javascript">

// Rokt APIキーを入力
const API_KEY = "YOUR_API_KEY";

// ファーストパーティドメイン設定を使用している場合は、カスタムサブドメインを入力（オプション）
const ROKT_DOMAIN = "https://apps.rokt-api.com";

window.mParticle = {
    config: {
        // データ環境を設定:
        // 統合のテスト中であれば、isDevelopmentModeをtrueに設定。
        // 統合が本番データの準備ができている場合は、isDevelopmentModeをfalseに設定。
        isDevelopmentMode: true,
        // 現在のユーザーを識別:
        // ユーザーのメールアドレスがない場合は、null値を渡すことができます
        identifyRequest: {
            userIdentities: {
                // ハッシュされていないメールアドレスを使用している場合は、'email'に設定。
                email: 'j.smith@example.com',
                // ハッシュされたメールアドレスを使用している場合は、`email`の代わりに'other'に設定。
                other: 'sha256 hashed email goes here'
            }
        },
        // ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定。
        identityCallback: function(result) {
            if (result.getUser()) {
                result.getUser().setUserAttribute('attribute-key', 'attribute-value');
            }
        }
    }
};

// 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.7; 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","setExtensionData","use","getVersion","terminate"].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("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

サイトに初期化スクリプトを挿入する際、次の設定を構成してください:

1.1 Rokt APIキーを入力

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

Rokt APIキーは、Roktアカウント担当者から提供される一意の認証情報であり、あなたのサイトがRokt SDKと安全に接続し、やり取りすることを可能にします。

1.2 カスタムサブドメインを入力（オプション）

SDKを独自のドメイン経由でルーティングしたい場合は、First-Party Domain Configurationの指示に従い、ROKT_DOMAIN を作成したサブドメインに設定します。

カスタムサブドメインを使用すると、Rokt SDKを独自のドメイン経由でルーティングでき、ブラウザや広告ブロッカーによって広告やデータがブロックされるリスクを減らすことができます。

このステップはオプションです。ROKT_DOMAIN を https://apps.rokt-api.com に設定したままにすることもできますが、その場合、Rokt SDKへのリクエストは apps.rokt-api.com 経由でルーティングされます。

1.3 データ環境の設定

Roktは2つのデータ環境を維持しています: テスト目的でデータをラベル付けし保存するための開発環境 (Development) と、実際の顧客活動を収集するための本番環境 (Production) です。

Rokt SDKのテストを続けている場合は、isDevelopmentMode を true に設定してください。

テストが完了し、実際の顧客活動の収集を開始したい場合は、isDevelopmentMode を false に設定してください。

1.4 ユーザーの識別

SDKが初期化されると、現在のユーザーを識別することができ、収集されたデータが正しくユーザーに帰属され、ユーザーの行動に基づいて最も関連性の高い広告が表示されるようになります。

SDK初期化スクリプトには identifyRequest というオブジェクトが含まれています:

identifyRequest: {
    userIdentities: {
        // ユーザーの生のメールアドレスを 'email' に設定
        email: 'j.smith@example.com',
        // ユーザーのハッシュ化されたメールアドレスを 'other' に設定
        other: 'sha256 hashed email goes here'
    }
}

identifyRequest 内で、ユーザーのメールアドレスをSHA256でハッシュ化していない場合は email フィールドに、ハッシュ化している場合は other フィールドに渡してください。

初期化スクリプトには、ユーザーのメールアドレスが初期化時にない場合でも、常に identifyRequest を含めてください。

注記

ユーザーのメールアドレスがない場合は、null値を渡してください。SDKは依然として初期化され、後で2. ユーザーの識別の指示に従ってユーザーを識別することができます。

1.5 追加のユーザー属性を設定する

初期化スクリプトには、ユーザーがメールアドレスで正常に識別された場合に追加のユーザー属性を設定するためのコールバック関数が含まれています:

// identityCallback は identifyRequest が成功したかどうかを判断します。
identityCallback: function(result) {
    if (result.getUser()) {
        // ユーザーが識別された場合、setUserAttribute で追加のユーザー属性を設定します。
        result.getUser().setUserAttribute('attribute-key', 'attribute-value');
    }
}

Rokt がユーザーに対して収集を推奨する属性の一覧については、推奨ユーザー属性を参照してください。

2. ユーザーを識別する

初期化中に、SDK はユーザーのメールアドレスを使用して Rokt に identifyRequest を送信し、現在のユーザーを識別します。

初期化時にユーザーを識別することに加えて、SDK が初期化された後にユーザーがメールアドレスを提供するたびに（例えば、ログインや購入時）、identify メソッドを呼び出してメールを Rokt に渡す必要があります。これにより、データが現在のユーザーに正しく帰属されます。

ユーザーを識別するには、まずユーザーのメールアドレスを含む identifyRequest オブジェクトを作成します。

ハッシュ化されていないメールアドレスを提供する場合は、以下を使用します:

const identifyRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
};

ハッシュ化されたメールアドレスを提供する場合は、以下を使用します:

const identifyRequest = { 
    userIdentities: { 
        other: 'sha256 hashed email goes here' 
    }
};

次に、ユーザーを識別する際に追加のユーザー属性を設定するオプションとして、コールバック関数を作成します。identifyRequest が成功した場合、setUserAttribute で設定したユーザー属性がユーザーに割り当てられます。

const identityCallback = function(result) { 
    if (result.getUser()) { 
        result.getUser().setUserAttribute('attribute-key', 'attribute-value');	
    }
};

Rokt がユーザーに対して収集を推奨する属性の一覧については、推奨ユーザー属性を参照してください。

最後に、identifyRequest と identityCallback を作成して追加の属性を設定した後、作成した identifyRequest と identityCallback オブジェクトを渡して identify メソッドを呼び出します:

mParticle.Identity.identify(identifyRequest, identityCallback);

例えば、Jane Smithという名前のユーザーをメールアドレスj.smith@example.comで識別する場合（メールアドレスをハッシュ化する必要がない場合）、次のように使用します:

const identifyRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
};

const identityCallback = function(result) { 
    if (result.getUser()) { 
        result.getUser().setUserAttribute('firstname', 'Jane');
        result.getUser().setUserAttribute('lastname', 'Smith');
    }
};

mParticle.Identity.identify(identifyRequest, identityCallback);

3. ユーザー属性の設定

上記の例は、SDKの初期化時にユーザーが識別された場合と、ユーザーがメールアドレスを提供した後に識別された場合にユーザー属性を設定する方法を示しています。

しかし、ユーザーが識別された後は、いつでもユーザー属性を設定することができます。これらの属性は、広告配置やログイベントに含まれます。また、配置を挿入する際に直接ユーザー属性を設定することもできます。

ユーザー属性を設定するには、次のように実行します:

// 現在のユーザーを取得するには、getCurrentUserを呼び出します。
const currentUser = mParticle.Identity.getCurrentUser();

// 現在のユーザーを`currentUser`というconstに正常に設定した後、次のようにユーザー属性を設定できます:
currentUser.setUserAttribute("user-attribute-key", "user-attribute-value");

// リスト属性を設定するには、属性の値を文字列の配列に設定します。例えば:
currentUser.setUserAttribute("favorite-genres", ["documentary", "comedy", "romance", "drama"]);

// ユーザー属性を削除するには、removeUserAttributeを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
currentUser.removeUserAttribute("attribute-to-remove");

推奨されるユーザー属性

Roktは、次のユーザー属性を可能な限り多く設定することを推奨します:

ユーザー属性キー	例の値	備考
firstname	John	顧客の名。
lastname	Doe	顧客の姓。
mobile	3125551515	電話番号は `1112345678` または `+1 (222) 345-6789` の形式でフォーマットできます。
age	33	顧客の年齢。
dob	19900717	生年月日。 `yyyymmdd` の形式でフォーマットされます。
gender	M	顧客の性別。例として、`M`、`Male`、`F`、または `Female`。
city	Brooklyn	顧客の市。
state	NY	顧客の州。
zip	11201	顧客の郵便番号。
title	Mr	顧客の敬称。例として、`Mr`、`Mrs`、`Ms`。
language	en	購入に関連する言語。
value	52.25	顧客の価値。
predictedltv	136.23	顧客の予測される生涯価値の合計。

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

4. ファネルイベントの追跡

Rokt SDKを使用すると、サイトを訪れるユーザーの行動を記録するイベントトラッキングを実装できます。このデータを利用して、ユーザーの体験を最適化することが可能です。

SDKで追跡できる主なイベントタイプは3つあります:

ページビューイベント: サイトのページが読み込まれたときにトリガーできるイベントです。
カスタムイベント: サイト特有の情報を追跡するために作成する自由形式のイベントです。
コマースイベント: eコマースに特化したイベントで、カートへのアイテム追加や最終購入など、ショッピング体験のさまざまな段階を説明できます。

Rokt SDKを初めて統合する際は、ページビューの追跡から始めてください。カスタムイベントとコマースイベントの追跡については、付録を参照してください。

ページビューの追跡

追跡できる最も基本的なイベントタイプの1つがページビューです。

ページビューを記録するには、SDKが初期化された後にlogPageView()メソッドを使用します。

以下の例では、イベントには次のものが含まれます:

URLパスの最後のセグメントから派生したscreen_name（デフォルトは「home」）。
現在のページの完全なurl。
document.referrerから取得したreferring-page。

これは、ページ識別子を手動で指定することなく、サイト全体でのユーザーのナビゲーションを追跡するのに役立ちます。

// SDKが完全に読み込まれるのを待ってからイベントを記録
window.mParticle.ready(function() {
    mParticle.logPageView(
        // イベント名: "page view"は記録されるイベントのタイプを識別
        "page view",
        {
            // URLパスの最後のセグメントを画面名としてキャプチャ、
            // 例: "/products/shoes" → "shoes"。パスが空の場合はデフォルトで"home"。
            "screen_name": location.pathname.split("/").filter(Boolean).pop() || "home",

            // 現在のページの完全なURLを記録（プロトコル、パス、クエリ、ハッシュを含む）
            "url": window.location.toString(),

            // ユーザーをこのページに誘導したページのURLをキャプチャ、
            // 利用可能な場合。ページまたはサイト間のユーザーのナビゲーションを追跡するのに役立ちます。
            "referring-page": document.referrer
        }
    );
});

5. プレースメントを表示する

Rokt SDKの主な価値は、selectPlacements メソッドを通じて解放されます。このメソッドは、提供された属性に基づいてお客様に対して非常に関連性の高いプレースメントを提供します。

Roktの統合が初期化されたら、プレースメントを提供したいサイトの任意のページまたはコンポーネントで selectPlacements メソッドを呼び出すことができます。ページが読み込まれ、SDKが初期化され、以下のコードサンプルに示されている推奨属性が呼び出しに含められるようになったら、すぐに selectPlacements を呼び出すべきです。

また、以下のスニペットに示されているように、ページ識別子を identifier に渡すこともできます。これは、Roktプレースメントが追加されるページを一意に識別し、複数のページで同じURLを使用するマルチステップのチェックアウトフローがある場合に便利です。ページ識別子には任意の値を使用できますが、いくつかの例として以下があります：

stg.rokt.conf - ステージング（またはテスト）環境の確認ページ。
prod.rokt.conf - 本番環境の確認ページ。
stg.rokt.payments - ステージング（またはテスト）環境の支払いページ。
prod.rokt.payments - 本番環境の支払いページ。

selectPlacements を呼び出す際には、少なくとも email、firstname、lastname、billingzipcode、および confirmationref 属性を提供する必要があります。追加で含めることができる属性は例に示されています。

注記

selectPlacements の呼び出し前に currentUser.setUserAttribute を使用して設定されたユーザー属性と、selectPlacements の呼び出しで設定された属性はどちらもRoktに送信されます。しかし、ユーザー属性を2回設定した場合（selectPlacements 呼び出し前と selectPlacements 呼び出し内）、selectPlacements 呼び出しで設定された最新の値が使用されます。

例えば、currentUser.setUserAttribute("firstname", "Johnathan") を使用してユーザーの名前を設定したが、selectPlacements の attributes オブジェクト内に "firstname": "John" を含めた場合、Roktに送信される値は "John" です。

window.mParticle.ready(async function () {
    const selection = await window.mParticle.Rokt.selectPlacements({
        identifier: "yourPageIdentifier",
        attributes: {
            "email": "j.smith@example.com", // チェックアウトで使用される顧客のメールアドレス
            "firstname": "Jenny",           // 顧客の名
            "lastname": "Smith",            // 顧客の姓

"confirmationref": "54321", // 注文 / 確認参照番号 "billingzipcode": "90210", // 顧客の請求先郵便番号 "amount": "100.00", // 小数点以下の取引金額例: 300.5 "paymenttype": "VISA", // 例: ギフトカード | Chase, Visa "ccbin": "372888", // クレジットカードのBIN 例: 372888 "mobile": "123-456-7890", // 顧客の携帯電話番号 "country": "USA", // ISO Alpha-2 国コード "language": "en", // ISO 639-1 2文字言語コード "currency": "USD", // 取引通貨例: USD "billingaddress1": "", // 顧客の住所1行目 "billingaddress2": "", // 顧客の住所2行目 "age": "29", // 顧客の年齢 "gender": "f", // 顧客の性別 m / f "cartItems": JSON.stringify(["item 1", "item 2", "item 3"]), // 文字列化されたカートの内容

// ここに取引に関連する追加属性を渡すこともできます // 属性の完全なリストについては、以下のリンクを参照してください "shippingtype": "Priority Express" } }); });

#### プレースメントへのサブスクライブ

[プレースメントイベント](/developers/integration-guides/web/advanced/event-based-integration/)にサブスクライブすることで、プレースメントが準備完了したときや、顧客がオファーに関与したときにトリガーされる通知を受け取ることができます。

```javascript
window.mParticle.ready(async function () {
  // selection
  const selection = await window.mParticle.Rokt.selectPlacements({
    // add attributes
  });
 
  // プレースメントがインタラクティブ/表示準備完了になったときのリッスン
  selection.on('PLACEMENT_INTERACTIVE').subscribe(() => {
    // プレースメントがインタラクティブになった後に実行するロジック
  });
 
  // ユーザーがオファーに肯定的または否定的に関与したときのリッスン
  selection.on('OFFER_ENGAGEMENT').subscribe(function () {
    // オファーに関与した後に実行するロジック
  });
});

拡張機能による追加機能

コアのRokt統合ランチャーはほとんどのeコマースシナリオを処理しますが、一部の機能には拡張が必要です。これらの拡張を有効にするには、selectPlacements()を呼び出す前にmParticle.Rokt.use()を呼び出します。これにより、基本統合を変更することなく、購入後のアップセルプレースメントなどのオプション機能を追加することが可能になります。

例えば、Thank Youページにアップセルプレースメントを表示するには、最初にThankYouPageJourney拡張を有効にしてください:

window.mParticle.ready(async function() {
    // プレースメントを選択する前に必要な拡張を有効にする
    await window.mParticle.Rokt.use("ThankYouJourney");

    const selection = await mParticle.Rokt.selectPlacements({
      identifier: "yourPageIdentifier",
      attributes: {
        "email": "j.smith@example.com"
        // Roktに渡したい追加のユーザー属性
      },
    });
})

プレースメントを閉じる

サイトがシングルページアプリケーションの場合、selectPlacementsを呼び出してプレースメントを提供した後、ユーザーが別のページに移動した際にプレースメントを閉じることが重要です。これにより、ユーザーが戻ったときにプレースメントが表示され続けるのを防ぎます。

プレースメントを閉じて削除するには、作成したプレースメントオブジェクトに対して.close()を呼び出します:

// 'selection'という名前のプレースメントを閉じます
selection.close();

注記

サポートされている属性の完全なリストについては、Data Attributesを参照してください。

専任のRoktチームが、ブランドとUXスタイルガイドに合わせてプレースメントレイアウトを設定します。

6. 統合のテスト

Roktは、新しい統合をテストして、SDKが正しく初期化され、イベントが正常に記録されることを確認することを推奨します。

新しいブラウザウィンドウを開きます。
ブラウザの開発者ツールパネルを開きます。ほとんどのブラウザでは、画面を右クリックしてInspectをクリックすることでこれを行うことができます。
開発者ツールパネルから、Networkタブに移動し、フィルターバーにexperiencesと入力します。
SDKを統合したサイトとページに移動します。
- 注意: 開発者ツールパネルをサイトに移動する前に開いて、ブラウザが/experiencesコールを記録するようにしてください。
開発者ツールパネルのNetworkタブで、少なくとも1つの/experiencesリクエストが表示されるはずです。これは、Web SDKが正常にロードされたことを示しています。
/experiencesリクエストをクリックします（ステータスが200であるべきです）。Payload/Requestタブを確認して、Roktと共有されているデータを検証します。
- 注意: テスト中に、ステータスが204の別の/experiencesコールが表示されることがあります。ステータスが200のコールでチェックを行っていることを確認してください。

トラブルシューティング

Rokt Web SDKはコンテキストに応じたエラーレポートを提供します。統合の検証に問題がある場合、問題をデバッグする最良の方法は、ブラウザの開発者ツールパネルのコンソールタブを使用することです。

Rokt SDKに関連しないエラーに遭遇することもありますが、確認すべき一般的なRokt SDKのエラーには以下のものがあります：

構文エラー

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

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

ブラウザの開発者ツールパネルに移動し、コンソールタブを選択します。
Web SDKを配置したファイルにエラーがある場合、コンソールにログが記録されます。ファイルをクリックしてコードと報告されたエラーを確認します。
ファイル内にエラーが示されます。特に、すべての属性が以下のようにカンマで区切られていることを確認してください。

不正:

email: ''
emailsha256: '',

正しい:

email: '',
emailsha256: '',

初期化エラー

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

付録

上記の手順に従ってプレースメントとページビューのトラッキングを実装した後、追加のイベントトラッキングを実装したい場合があります。

カスタムイベントのトラッキング

logEventを呼び出し、イベント名、イベントタイプ、およびイベントのカスタム属性のリストを含むJSONオブジェクトを渡すことで、カスタムイベントを定義してトラッキングできます。

サポートされているカスタムイベントタイプは以下の通りです：

Navigation
Location
Search
Transaction
UserContent
UserPreference
Social
Other

イベントタイプはオプションです。イベントタイプを省略した場合、イベントは単にunknownとして分類されます。

mParticle.logEvent(
    // イベント名
    'event-name',
    // イベントタイプ
    mParticle.EventType.Other,
    // イベントをさらに説明するためのカスタムイベント属性を含める
    {
        'custom-attribute-name': 'custom-attribute-value'
    }
);

コマースイベントのトラッキング

コマースイベントをトラッキングするには、次の3つのステップが必要です：

createProduct メソッドを使用して変数内で購入される製品を定義します。
トランザクションの概要を含むオブジェクトを作成します。
製品定義を配列とトランザクションの概要に含めて logProductAction メソッドを呼び出します。

1. 製品を定義する

製品を定義する際には、mParticle.eCommerce.createProduct メソッドを使用して新しい製品を作成し、以下の属性と、キー/バリューペアとして定義できるカスタム製品属性を含むオプションのJSONオブジェクトを渡します。

注記

製品属性は以下に示す順序で追加する必要があります。任意の属性に値がない場合は、その値を null に設定する必要があります。カスタム属性用のオプションのJSONオブジェクトを除き、属性をスキップまたは省略することはできません。

製品属性	説明	データ型	必須
Name	購入される製品の名前。	String	Yes
SKU	製品の在庫管理単位。	String	Yes
Price	製品の価格。	Decimal	Yes
Quantity	ユニット数。	Integer	No
Variant	提供するバリアントがある場合の特定の製品バージョン。例：サイズや色。	String	No
Category	製品が属するカテゴリ。	String	No
Brand	製品のブランド名。	String	No
Position	ポジション。	String	No
Coupon code	製品のクーポンコード。	String	No

var product1 = mParticle.eCommerce.createProduct(
    'Double Room - Econ Rate',  // Name (required)
    'econ-1',                   // SKU（必須）
    100.00,                     // 価格（必須）
    4,                          // 数量
    'variant',                  // バリアント
    'room',                     // カテゴリ
    'lodge-o-rama',             // ブランド
    'banner',                   // ポジション
    null,                       // クーポンコード
    // 任意のカスタム属性をキー/値ペアのオブジェクトとして追加
    {
        'ocean-view': true,
        'balcony': false
    }     
);

2. トランザクションを要約する

transactionAttributesというオブジェクト内にトランザクションの要約を作成します。

var transactionAttributes = {
    Id: 'foo-transaction-id',
    Revenue: 430.00,
    Tax: 30
};

3. コマースイベントをログに記録する

コマースイベントをログに記録するには、mParticle.eCommerce.logProductActionを呼び出し、ProductActionTypeを以下にリストされているサポートされているアクションタイプのいずれかに設定します。

製品定義を配列に含めます。単一の製品定義しかない場合でも、例に示すように配列に含めてください。

コマースイベントのカスタムイベント属性はcustomAttributesで設定することもできます。

// "product actions"のいくつかのタイプがサポートされています。例えば、AddToCartやCheckoutです。この例ではPurchaseの製品アクションを使用しています。
mParticle.eCommerce.logProductAction(
    // ログに記録される製品アクションのタイプ。この例では"Purchase"です。
    mParticle.ProductActionType.Purchase,
    // ステップ1で既に作成した製品定義を含む配列。
    [product1],
    // コマースイベントを説明するカスタム属性
    customAttributes = { 
        'sale': true
    },
    // ここはRokt統合のためのmParticleのカスタムフラグを指定するスペースです。Rokt Ecommerceの顧客はこのセクションを無視して'null'を入力できます。
    null, 
    // ステップ2で既に作成したtransactionAttributesオブジェクト。
    transactionAttributes
);

logProductActionメソッドを呼び出す際には、製品アクションタイプを指定する必要があります。

サポートされているプロダクションアクションタイプ

AddToCart
RemoveFromCart
Checkout
CheckoutOption
Click
ViewDetail
Purchase
Refund
AddToWishlist
RemoveFromWishlist
Unknown

追加のインテグレーションランチャーオプションの渡し方

Rokt SDKは、インテグレーションの動作を構成するための追加のオプションパラメータを受け入れることができます。

オプションのランチャーオプションを含めるには、初期化スクリプト内の window.mParticle.config.launcherOptions オブジェクトに含めます:

// 上記のステップ1の初期化スクリプトの一部としてこれを含めます
window.mParticle.config.launcherOptions = {
    noFunctional: true,
    // 設定可能なすべてのオプションのランチャーオプションを以下に示します
};

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

このオプションを使用して、通常はパーソナライズや強化されたチェックアウト体験に使用される機能的なクッキーを無効にすることで、顧客のオプトアウトのプリファレンスを尊重します。

パラメータ	タイプ	デフォルト
`noFunctional`	boolean	`false`

機能的なクッキーに対するユーザープリファレンスの管理を可能にするブールフラグです。機能的なクッキーは、サイト上で最も関連性が高く最適な顧客体験を提供するために使用され、パーソナライズを強化します。また、チェックアウト内の高度な機能（例：アップセルの販売）をサポートします。実際には、この値をtrueに設定すると、RoktがファーストパーティのトラッキングIDを使用することを防ぎます。

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

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

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

パラメータ	タイプ	デフォルト
`pageInitTimestamp`	Date	`PerformanceNavigationTiming.responseStart`

SPAの仮想ページでIntegration Launcherが初期化される場合、この値を使用してページが初期化された時点のタイムスタンプを提供できます。これにより、Roktはそれをトリガーしたページに関連するロードパフォーマンスを正確に測定でき、ユーザーがそのページに到達するまでにかかった時間などの外部要因を考慮する必要がありません。この情報を使用して、Roktは統合の効率に影響を与える可能性のあるロード時間の異常を検出できます。

RoktセッションIDで顧客のアクティビティをリンクする

異なる部分のエクスペリエンス全体でアクティビティが正しく結び付けられるように、以前に生成されたRoktセッションIDを渡します。

パラメータ	タイプ	デフォルト
`sessionId`	string	—

すでにセッションIDを生成している場合に渡すRoktセッションIDです。

例えば、タグが表示されるページを訪れる前にRoktバックエンドと接続してセッションIDを生成することが可能です。この場合、以前に生成されたRoktセッションIDをこのパラメータとして提供する必要があります。これにより、Roktは両方のインタラクションを結び付けることができます。

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

パラメータ	タイプ	デフォルト
`overrideLinkNavigation`	boolean	`false`

trueに設定すると、Roktはリンクの開きを直接処理しなくなります。その代わりに、LINK_NAVIGATION_REQUESTパートナーイベントが発行されます。

このフラグは、パートナーがカスタマイズされたリンク処理を必要とするシナリオで役立ちます。一般的なユースケースとして、Roktおよび広告主からのリンクを外部ブラウザで使用しながら、リンクをWebView内で開くなどの異なるリンク動作を管理することがあります。Roktと広告主のリンクを区別するために、パートナーはURLに"rokt.com"というサブストリングが含まれているかどうかを確認できます。

適切なイベント処理を確保するために、タイムアウトメカニズムが導入されています。LINK_NAVIGATION_REQUESTイベントが3秒以内に消費されない場合、エラーが発生します。この予防措置により、イベントを処理するためのアクティブなサブスクリプションがパートナー側に存在することを保証し、それがない場合にはRoktに通知されます。

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

1. Rokt SDKの初期化​

SDK 初期化スクリプト​

1.1 Rokt APIキーを入力​

1.2 カスタムサブドメインを入力（オプション）​

1.3 データ環境の設定​

1.4 ユーザーの識別​

1.5 追加のユーザー属性を設定する​

2. ユーザーを識別する​

3. ユーザー属性の設定​

推奨されるユーザー属性​

4. ファネルイベントの追跡​

ページビューの追跡​

5. プレースメントを表示する​

拡張機能による追加機能​

プレースメントを閉じる​

6. 統合のテスト​

トラブルシューティング​

構文エラー​

初期化エラー​

付録​

カスタムイベントのトラッキング​

コマースイベントのトラッキング​

1. 製品を定義する​

2. トランザクションを要約する​

3. コマースイベントをログに記録する​

サポートされているプロダクションアクションタイプ​

追加のインテグレーションランチャーオプションの渡し方​

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

シングルページアプリケーションでのページロードパフォーマンスの測定​

RoktセッションIDで顧客のアクティビティをリンクする​

エクスペリエンス内でリンクが開く方法をカスタマイズする​