Last updated

Web SDK 統合ガイド

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

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

注記

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

注記

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

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

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

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

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 ハッシュ化されたメールアドレスをここに置く'
       }
    },
    // ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定してください。
    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.6; 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"].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つのデータ環境を維持しています：開発環境はテスト目的でデータをラベリングし保存するためのものであり、本番環境は実際の顧客活動を収集するためのものです。

まだ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');
    }
}

ユーザーに対して収集を推奨される属性のリストについては、推奨ユーザー属性を参照してください。

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');	
    }
};

ユーザーに対して収集を推奨される属性のリストについては、推奨ユーザー属性を参照してください。

最後に、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. ページビューをトラッキングする

トラッキングできる最も基本的なイベントタイプの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クリックIDとサイト滞在時間がキャプチャされます。これらは、コンバージョンイベントをログする際に含まれます。

// コンバージョンイベントのログを行う前にユーザー属性を設定
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": "",                   // トランザクション金額 e.g. 300.5
    "currency": "",                 // トランザクション通貨 e.g. USD
 
    // 独自のカスタムイベント属性を追跡可能！
    "CUSTOM_EVENT_ATTRIBUTE_NAME" : "CUSTOM_EVENT_ATTRIBUTE_VALUE"
  }
);

6. 統合をテストする

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

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

トラブルシューティング

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

Rokt SDK に関係のないエラーが発生している可能性もありますが、確認すべき一般的な Rokt SDK のエラーには以下のものがあります。

構文エラー

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

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

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

不正:

email: ''
emailsha256: '',

正しい:

email: '',
emailsha256: '',

初期化エラー

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

付録

上記の説明に従ってプレースメントとページビューのトラッキングを実装したら、追加のイベントトラッキングを実装することを考えるかもしれません。

カスタムイベントをトラックする

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. 統合をテストする​

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

構文エラー​

初期化エラー​

付録​

カスタムイベントをトラックする​