SDKインテグレーション
このAPIサーフェスは、Roktネットワーク上で構築するインテグレーションパートナー向けです。Roktのeコマースパートナーで、自社のチェックアウトにプレースメントを統合する場合は、Rokt Ecommerce開発者ドキュメントを使用してください。
マーチャントがPOST /v1/accounts/register/partnershipを通じて登録されると、レスポンスにはaccount_idと、pagesを提供した場合、各サーフェスごとに1つのpage_identifierが含まれます。マーチャントのページには以下が必要です：
- 各ページに1回Rokt SDKをロードする（以下のステップ1のローダースクリプト）。
- 各サーフェスで
selectPlacementsを呼び出し、対応するpage_identifierを渡します。埋め込みサーフェスの場合、プレースメントをレンダリングするアンカー要素（デフォルトでは<div id="rokt-container"></div>）。
サーフェスの用語とレスポンスがSDKコードにどのようにマッピングされるかについては、Pages and Layoutsを参照してください。
このページでは標準的なマルチページアプリケーションの統合について説明します。シングルページアプリケーションについては、ページ下部のSPAノートを参照してください。
1. SDKをロードする1. SDKをロードする への直接リンク
マーチャントのページの<head>にローダーを埋め込みます。ローダーはlauncher.jsを非同期で取得し、準備ができたらプロミスを解決します。
マーチャントのPOST /v1/accounts/register/partnershipレスポンスから返されたaccount_idで<your-rokt-account-id>を置き換えてください。各マーチャントには独自のaccount_idがあります。
Google Tag Managerユーザー: カスタムHTMLタグでdocument.writeフィールドがチェックされていることを確認してください。これがないと、ローダーのスクリプトインジェクションステップがブロックされ、SDKが初期化されません。
<!DOCTYPE html>
<html lang="en">
<head>
<!-- Meta tags -->
<!-- Part #1: Load the Rokt SDK -->
<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>
<!-- Other scripts and meta tags -->
</head>
<body>
<!-- Your HTML content here -->
<!-- Part #2: As soon as customer attributes are available, render the placement -->
<script type="module">
await window.RoktLauncherScriptPromise;
const launcher = await window.Rokt.createLauncher({
// SDK param (camelCase); the API registration response returns account_id (snake_case)
accountId: "<your-rokt-account-id>",
sandbox: true,
});
await launcher.selectPlacements({
identifier: "confirmation_page", // ← page_identifier from /register response, matched per surface
attributes: {
email: "",
firstname: "",
lastname: "",
confirmationref: "",
billingzipcode: "",
amount: "",
country: "",
currency: "",
mobile: "",
// ... additional attributes
},
});
</script>
<!-- Your HTML content here -->
</body>
</html>
SDKを早期にロードし（<head>）、顧客属性（メール、注文合計など）が利用可能になったらすぐにselectPlacementsを呼び出します。属性が早く利用可能になるほど、SDKはページがインタラクティブになる前にプレースメントをレンダリングする時間が増えます。
2. 顧客属性2. 顧客属性 への直接リンク
マーチャントのチェックアウトで収集されたものをできるだけ多く渡します。より多くの属性は、より良い関連性と高いフィルレートを意味します。
| 属性 | 説明 |
|---|---|
email | 生の、ハッシュされていないメール。主要な識別信号。 |
firstname, lastname | 顧客名。 |
confirmationref | 注文確認番号。 |
billingzipcode | 請求先ZIP/郵便番号。 |
amount | 注文合計。 |
country | ISO 3166-1 alpha-2国コード（US, GB, AU）。 |
currency | ISO 4217通貨コード（USD, GBP, AUD）。 |
mobile | E.164形式の電話番号（+13125551515）。 |
age, gender | デモグラフィック信号。 |
billingaddress1, billingaddress2 | 請求先住所。 |
language | ページのロケール（ISO 639-1）。 |
cartItems | カートのラインアイテムの文字列化されたJSON配列。 |
識別子のハッシュされた形式のみが利用可能な場合、email_sha256またはmobile_sha256をemail / mobileの代わりに使用してください。
3. サンドボックス対本番3. サンドボックス対本番 への直接リンク
テスト中は、sandbox: trueをcreateLauncher呼び出しに設定します。マーチャントが本番稼働の準備ができたら、sandbox: falseに設定するか、フィールドを完全に削除します。
スニペットの直接統合が推奨されるパスですが、タグマネージャー（Google Tag Manager、Tealium、Adobe Experience Platform）を介してSDKを展開することもサポートされています。直接インジェクションはロード時間のオーバーヘッドを最小化し、タグマネージャー固有の問題を回避します。
4. 埋め込み配置4. 埋め込み配置 への直接リンク
パートナーシッププリセットが埋め込み配置を作成する場合、マーチャントのページには配置がアンカーするターゲットHTML要素を含める必要があります（デフォルト: <div id="rokt-container"></div>）。正確なセレクターはパートナーシッププリセットで設定されます。
5. 統合のテスト5. 統合のテスト への直接リンク
マーチャントのブラウザコンソールで以下を確認してください:
window.Roktがlauncher.jsの読み込み後に定義されていることcreateLauncherがエラーなく解決されることselectPlacementsが顧客属性を含めて呼び出されること
もし selectPlacements が正常に返ってきても配置がレンダリングされない場合、渡している identifier がそのサーフェスに対して /register から返される page_identifier と一致しているか確認してください。識別子の完全なリスト（confirmation_page, tracking_page, returns_page）はページとレイアウトに記載されています。
ページの読み込みが遅いですか？ 配置がページがインタラクティブになった後に一貫してレンダリングされ、マーチャントがそれを読み込み速度の問題としてフラグを立てた場合、準備用のiframeが selectPlacements が呼び出される前にSDKを事前に温めることができます。これを検討したい場合は、Roktの担当者にお問い合わせください。これはマーチャントごとの最適化であり、デフォルトではありません。
シングルページアプリケーションシングルページアプリケーション への直接リンク
SPA（React、Vue、Angularなど）の場合、Rokt配置を表示すべきページにルートが変わるたびに selectPlacements を呼び出してください。セッションごとに createLauncher を複数回呼び出さないでください。