Web SDK 統合ガイド

このページでは、Rokt Ads の Web SDK を実装して、コンバージョンをキャンペーンにリンクすることでループを閉じる方法を説明します。コンバージョンを Ads エンゲージメントにリンクすることで、より正確なアトリビューション、リアルタイムの最適化、およびキャンペーンの測定が可能になります。

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

注記

以下の指示を完了するには開発リソースが必要です。追加の支援が必要な場合は、Rokt のアカウントマネージャーにお問い合わせください。

注記

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

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

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

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

1. Rokt SDKの初期化

SDKを初期化するには、SDK初期化スクリプトをサイトにコピーして貼り付けます。

各サイトは異なりますが、Roktはすべてのページに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.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"].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を独自のドメイン経由でルーティングしたい場合は、ファーストパーティドメインの設定の指示に従い、ROKT_DOMAIN を作成したサブドメインに設定します。

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

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

1.3 データ環境の設定

Roktは2つのデータ環境を維持しています。テスト目的でデータをラベリングおよび保存するための開発環境と、実際の顧客活動を収集するための本番環境です。

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内では、ユーザーのメールアドレスをハッシュ化されていない場合はemailフィールドに、SHA256でハッシュ化されている場合は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`という定数に設定したら、次のようにしてユーザー属性を設定できます。
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. ページビューのトラッキング

トラッキングできる最も基本的なイベントタイプの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
           }
   );
});

Web SDKのlogPageViewメソッドは2つの引数を取ります：

ページ名: ロードされるページの名前を示す文字列
カスタム属性: ページに関する情報を含むキー/バリューペアのオブジェクト

ページ名フィールドは一般的なページ名に設定する必要があります。例えば、eコマースサイトには何百もの商品詳細ページがあるかもしれません。これらを正しくログに記録するには、一般的な名前（例: "Product Detail Page"）を使用し、ページのURLやその他の属性を属性としてログに記録する必要があります。

5. コンバージョンをトラッキングする

コンバージョンをトラッキングするには、顧客がコンバートした後に読み込まれる最も適切なページ（購入確認ページや「ありがとう」ページなど）で、次のコードスニペットを実行します。

サイトにコードスニペットを貼り付ける際には、以下の点に注意してください：

.setUserAttribute 呼び出しでサンプルのユーザー属性を実際のユーザーまたは顧客の値に置き換えます。Rokt は少なくとも以下のユーザー属性を設定することを推奨します：
- firstname
- lastname
- zipcode
- mobile
サンプルのコンバージョンイベント属性をコンバージョンイベントからの実際の値に置き換えます。

コンバージョンイベントをログに記録する際には、できるだけ多くのユーザー属性とイベント属性を含めることで、Rokt がキャンペーンを最適化する能力を向上させることができます。

注記

Rokt SDK を初期化すると、Rokt Click ID と Time on Site が自動的にキャプチャされます。これらはコンバージョンイベントをログに記録する際に含まれます。

// コンバージョンイベントをログに記録する前にユーザー属性を設定
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
currentUser.setUserAttribute("zipcode", "98103");
currentUser.setUserAttribute("mobile", "3125551515");

// コンバージョンイベントをログに記録
mParticle.logEvent( 
  "conversion", // イベントの名前
  mParticle.EventType.Transaction, // イベントタイプ
  { 
    "conversiontype": "signup",      // コンバージョンのタイプ
    "confirmationref": "54321",     // トランザクション ID / 注文 ID
    "amount": "",                   // トランザクション金額 例: 300.5
    "currency": "",                 // トランザクション通貨 例: USD
 
    // 独自のカスタムイベント属性をトラッキングできます！
    "CUSTOM_EVENT_ATTRIBUTE_NAME" : "CUSTOM_EVENT_ATTRIBUTE_VALUE"
  }
);

6. 統合をテストする

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

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

トラブルシューティング

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

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

構文エラー

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

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

ブラウザの開発者ツールパネルに移動し、Consoleタブを選択します。
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'
    }
);

カスタムイベントとコンバージョンイベントのトラッキングに加えて、以下はトラッキングしたいコマースイベントの例です。トラッキングする最適なイベントの特定とサイトへの実装方法については、アカウントマネージャーに相談してください:

purchase - ユーザーが購入または取引を行ったとき。
sign_up - ユーザーがイベントまたはサービスにサインアップまたは登録したとき。
first_time_deposit - ユーザーが初めてデポジットを提供したとき。
subscription_started - ユーザーがサブスクリプションを開始したとき。
app_install - ユーザーがアプリをインストールしたとき。
add_payment_info - ユーザーが支払い情報を追加したとき。
add_to_cart - ユーザーがアイテムをカートに追加したとき。
add_to_wishlist - ユーザーがアイテムをウィッシュリストに追加したとき。

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

1. Rokt SDKの初期化​

SDK 初期化スクリプト​

1.1 Rokt APIキーを入力​

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

1.3 データ環境の設定​

1.4 ユーザーの識別​

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

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

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

推奨ユーザー属性​

4. ページビューのトラッキング​

5. コンバージョンをトラッキングする​

6. 統合をテストする​

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

構文エラー​

初期化エラー​

付録​

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