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.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つのデータ環境を維持しています:開発環境はテスト目的でデータをラベリングし保存するためのものであり、本番環境は実際の顧客活動を収集するためのものです。
まだ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");