Web SDK 移行ガイド
このガイドは、古いバージョンの Rokt Web SDK（バージョン 2.5926.0 以前）から最新バージョンへの移行方法を説明します。これは Rokt Ecommerce と Rokt Ads の両方の実装に関連しており、更新された初期化スクリプトのような重大な変更点や、移行をスムーズに完了するために Rokt アカウントチームとどのように連携するかについて説明します。
Web SDK の初期化
新しい SDK で導入された最大の変更点は、ウェブサイト内での初期化方法です。現在のバージョン以前は、Rokt はサイト内の各ページの <head> タグから launcher.js または snippet.js スクリプトを呼び出すことで、SDK を初期化またはロードすることを許可していました。
これらのオプションはすべて、単一の初期化スクリプトに置き換えられました。
非推奨の launcher.js スクリプトを削除する
サイトのコードを検索し、launcher.js スクリプトのインスタンスをすべて削除してください。
それは次のように見えるはずです：
<script type="module">
window.RoktLauncherScriptPromise = new Promise((resolve, reject) => {
const target = document.head || document.body;
const script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
script.fetchPriority = "high";
script.crossOrigin = "anonymous";
script.async = true;
script.id = "rokt-launcher";
script.addEventListener('load', () => resolve());
script.addEventListener('error', (error) => reject(error));
target.appendChild(script);
});
</script>
非推奨の snippet.js 自動ランチャーを削除する
自動ランチャースニペットを使用している場合は、サイトのコードを検索し、スクリプトのインスタンスをすべて削除してください。
それは次のように見えるはずです:
(function (r, o, k, t, n, e, w, a, _) {
r._ROKT_ = n;
r[n] = r[n] || {
id: t,
h: w,
lc: [],
it: new Date(),
onLoaded: function (c) {
r[n].lc.push(c);
},
};
a = o.createElement("script");
a.type = "text/javascript";
a.async = !0;
a.src = k;
if (e) {
a.integrity = e;
a.crossOrigin = "anonymous";
}
_ = o.getElementsByTagName("script")[0];
_.parentNode.insertBefore(a, _);
})(
window,
document,
"https://apps.rokt.com/wsdk/integrations/snippet.js",
"roktAccountid",
"rokt"
);
新しいSDK初期化スニペットを挿入する
古いSDKスニペットのインスタンスをすべて削除した後、サイトの各ページの <head> タグに新しいSDK初期化スニペットを挿入してください。サイトがテンプレートを使用するマルチページアプリケーションの場合は、この新しいスニペットが各ページロード時にできるだけ早く実行されるようにテンプレートを更新してください。
新しい Rokt Web SDK 初期化スニペット
<script type="text/javascript">
// Rokt API キーを入力してください
const API_KEY = "YOUR_API_KEY";
// ファーストパーティドメインを設定した場合は、デフォルトの apps.rokt-api ドメインの代わりに DOMAIN の値として設定してください
const ROKT_DOMAIN = "https://apps.rokt-api.com";
// SDK の設定を行います
window.mParticle = {
config: {
// データ環境を isDevelopmentMode で指定します:
// 統合をテスト中の場合は、isDevelopmentMode を true に設定してください。
// 統合が本番データの準備ができている場合は、isDevelopmentMode を false に設定してください。
isDevelopmentMode: true,
// 現在のユーザーを識別します:
// ユーザーのメールアドレスがある場合は、以下のように `identifyRequest` 内の `userIdentities` オブジェクトに含めてください。
identifyRequest: {
userIdentities: {
// ハッシュされていないメールアドレスを使用している場合は、'email' に設定してください。
email: 'j.smith@example.com',
// ハッシュされたメールアドレスを使用している場合は、`email` の代わりに 'other' に設定してください。
other: 'sha256 hashed email goes here'
},
}
},
};
// 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>
新しいスニペットには、いくつかの新しい構成オプションが導入されています:
Rokt APIキー
以前は、SDKスニペットにRokt Account IDを入力する必要がありました。この要件はRokt API Keyに置き換えられました。
Roktアカウント担当者がRokt API Keyを提供します。
ファーストパーティドメイン
新しいWeb SDKでは、Roktへのリクエストを独自のサブドメインを通じてルーティングすることができます。これは「ファーストパーティドメイン統合」と呼ばれ、コンテンツがブロックされるのを防ぐのに役立ちます。
カスタムサブドメインを使用して統合するには、First Party Domain Integrationの指示に従い、初期化スニペットのDOMAINの値を独自のサブドメインに置き換えてください:
const DOMAIN = "your-new-subdomain-goes-here";
開発モード
以前は、SDKスニペットでsandbox: trueを設定して統合をテストすることができました。
現在、Rokt SDKにはisDevelopmentModeという構成オプションが含まれています。これをtrueに設定すると、Rokt SDKはデータを「開発」（テスト）データとして収集して転送します。統合のテストが完了したら、isDevelopmentModeをfalseに変更してください。
初期化時のユーザー識別
初期化中に、SDKはユーザーの生のメールアドレスまたはハッシュ化されたメールアドレス（どちらを提供できるかによります）を使用してidentifyRequestをRoktに送信し、現在のユーザーを識別します。初期化スクリプトの設定内で、次のようにidentifyRequest内に生のメールアドレスまたはハッシュ化されたメールアドレスを指定できます。
identifyRequest: {
userIdentities: {
// ハッシュ化されていないメールアドレスを使用している場合は、'email'に設定します。
email: 'j.smith@example.com',
// ハッシュ化されたメールアドレスを使用している場合は、`email`の代わりに'other'に設定します。
other: 'sha256 hashed email goes here'
},
}
ユーザーを識別する
SDKが初期化された際にユーザーのメールアドレスを提供できない場合は、ユーザーがメールアドレスを提供したらすぐに、SDKが初期化された後にidentifyメソッドを呼び出してユーザーを識別する必要があります。
ハッシュ化されていないメールアドレスを提供する場合は、次を使用します。
const identityRequest = {
userIdentities: {
email: 'j.smith@example.com'
}
};
mParticle.Identity.identify(identityRequest);
ハッシュ化されたメールアドレスを提供する場合は、次を使用します。
const identityRequest = {
userIdentities: {
other: 'sha256 hashed email goes here'
}
};
mParticle.Identity.identify(identityRequest);
ユーザー属性の設定
現在のユーザーを識別した後、広告配置やログイベントに含まれる説明的なユーザー属性を設定できます。ユーザー属性は、配置を挿入する際にも直接設定できます。
ユーザー属性を設定するには、SDKが初期化され、ユーザーを識別した後に次を実行します:
// 現在のユーザーを取得するには、getCurrentUserを呼び出します。これは、SDKの初期化時またはidentifyメソッドを呼び出すことでユーザーを識別した場合にのみ成功します。
const currentUser = mParticle.Identity.getCurrentUser();
// 現在のユーザーを`currentUser`というconstに正常に設定したら、次のようにしてユーザー属性を設定できます:
currentUser.setUserAttribute("user-attribute-name", "user-attribute-value");
// 注: すべてのユーザー属性（リスト属性およびタグを含む）は、異なる名前を持たなければなりません。
// Roktは、可能な限り多くの以下のユーザー属性を設定することを推奨します:
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
// 電話番号は '1234567890' または '+1 (234) 567-8901' の形式でフォーマットできます
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("age", "33");
currentUser.setUserAttribute("gender", "M");
currentUser.setUserAttribute("city", "Brooklyn");
currentUser.setUserAttribute("state", "NY");
currentUser.setUserAttribute("zip", "123456");
currentUser.setUserAttribute("dob", "yyyymmdd");
currentUser.setUserAttribute("title", "Mr");
currentUser.setUserAttribute("language", "en");
currentUser.setUserAttribute("value", "52.25");
currentUser.setUserAttribute("predictedltv", "136.23");
// リスト属性を設定するには、属性の値を文字列の配列に設定します。例えば:
currentUser.setUserAttribute("favorite-genres", ["documentary", "comedy", "romance", "drama"]);
// ユーザー属性を削除するには、removeUserAttributeを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
currentUser.removeUserAttribute("attribute-to-remove");
プレースメントの挿入
サイトにプレースメントを挿入するために使用されるスクリプトは、新しいSDKで置き換えられました。
非推奨の selectPlacements メソッド:
以前は、Rokt SDKランチャースクリプトが完了した後に selectPlacements を呼び出してプレースメントを挿入していました:
<script type="module">
await window.RoktLauncherScriptPromise;
const launcher = await window.Rokt.createLauncher({
accountId: "rokt-account-id",
sandbox: true,
});
await launcher.selectPlacements({
attributes: {
email: "",
firstname: "",
lastname: "",
confirmationref: "",
billingzipcode: "",
amount: "",
paymenttype: "",
ccbin: "",
mobile: "",
country: "",
language: "",
currency: "",
billingaddress1: "",
billingaddress2: "",
age: "",
gender: "",
cartItems: JSON.stringify(cartItems),
},
});
</script>
これは mParticle.Rokt.selectPlacements メソッドに置き換えられました:
新しい selectPlacements メソッド:
プレースメントを挿入するには、SDKを初期化した後に新しい mParticle.Rokt.selectPlacements を呼び出します。前のセクションと同様に、表示されるコンテンツの関連性を向上させるために属性のリストを提供できます。
const selection = await window.mParticle.Rokt.selectPlacements({
attributes: {
"email": "j.smith@example.com", // チェックアウト時に使用される顧客のメールアドレス
"firstname": "Jenny", // 顧客の名
"lastname": "Smith", // 顧客の姓
"confirmationref": "54321", // 注文/確認参照番号
"billingzipcode": "90210", // 顧客の請求先郵便番号
"amount": "", // 取引金額（例: 300.5）
"paymenttype": "", // 例: ギフトカード | Chase, Visa
"ccbin": "", // クレジットカードのBIN（例: 372888）
"mobile": "", // 顧客の携帯電話番号
"country": "", // ISO Alpha-2 国コード
"language": "", // ISO 639-1 2文字言語コード
"currency": "", // 取引通貨（例: USD）
"billingaddress1": "", // 顧客の住所1行目
"billingaddress2": "", // 顧客の住所2行目
"age": "", // 顧客の年齢
"gender": "", // 顧客の性別 m / f
"cartItems": JSON.stringify(["item 1", "item 2", "item 3"]), // 文字列化されたカートの内容
// ここに取引に関連する追加属性を渡すこともできます
// 属性の完全なリストについては、以下のリンクを参照してください
shippingtype: "Priority Express"
}
});
イベントトラッキングの実装
新しいRokt SDKは、イベントおよびユーザー属性を簡単に収集できます。これらの新しいトラッキングメソッドをサイトに実装する方法については、新しいGetting Started for EcommerceまたはGetting Started for Advertisersガイドを参照してください。