メインコンテンツまでスキップ

ページとレイアウト

Audience

このAPIサーフェスは、Roktネットワーク上に構築する統合パートナー向けです。Roktのeコマースパートナーで、独自のチェックアウトに配置を統合する場合は、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

ほとんどのパートナー統合では、各マーチャントが複数のサーフェスにRokt配置をレンダリングできます。pages 配列の POST /v1/accounts/register/partnership で、マーチャントが使用するサーフェスと各サーフェスが取得するレイアウトスタイルを宣言します。Roktはエントリごとに1つのページと1つのレイアウトを作成し、それらをレンダリングするために必要な識別子を返します。

3つのサーフェス3つのサーフェス への直接リンク

pages の各エントリは、3つのサーフェスのいずれかを選択します。それぞれが、Rokt側のルールがその意図に合わせて調整された個別のページコンテキストにマッピングされます。

surface使用するタイミングトランザクションとしてカウントされますか？
confirmationチェックアウト完了直後に表示される注文確認ページ。はい
tracking購入後に顧客が訪れる出荷または注文追跡ページ。いいえ
returns顧客が返品を開始または表示する返品ポータル。いいえ

confirmation はトランザクションサーフェスです。tracking と returns は購入後のエンゲージメントサーフェスであり、チェックアウト後に表示されるにもかかわらず、意図的にトランザクションを記録しません。そのページでの顧客の意図に合ったサーフェスを使用し、内部ページ名に最も近いものを使用しないでください。

注記

payment サーフェス（注文完了前のチェックアウト中に表示されるページ）は、意図的に後のリリースに延期されています。支払いページには独自のコントロールと、まだスコープされているリザーブ品質の処理が必要です。支払いサーフェスのユースケースがある場合は、Roktの担当者に連絡してください。

2つのレイアウトタイプ2つのレイアウトタイプ への直接リンク

各 pages エントリは、サーフェスとレイアウトスタイルをペアにします。

Overlay

配置がトリガーされたときにマーチャントのページ上に表示されるモーダル。顧客の完全な注意を引きたいサーフェスに最適です。

Embedded

マーチャントのページ上のアンカー要素内にインラインでレンダリングされます。デフォルトのアンカーセレクタは #rokt-container であり、配置がレンダリングされるべき場所にマーチャントのページに <div id="rokt-container"></div> を含める必要があります。

Overlay と Embedded を組み合わせて使用することができます（たとえば、confirmation で Overlay、tracking で Embedded）pages 配列に各サーフェスを個別にリストし、それぞれに layout_type を指定します。

注記

一部の統合では、レイアウトタイプのサブセットのみをサポートしています。認識されていない列挙値（例：タイプミスや不明な文字列）の layout_type を渡すと、入力検証レイヤーから 422 が返されます。layout_type が有効な列挙値であるが、統合でこのページのサーフェスに対してサポートされていない場合、サーバーから許可された値を示す 400 が返されます。統合が受け入れるものが不明な場合は、Roktの担当者に連絡してください。

各統合にはデフォルトがあります各統合にはデフォルトがあります への直接リンク

統合には、予想されるサーフェスとレイアウトタイプに合わせた pages デフォルトが付属しています。登録時にフィールドを省略してそれを使用します。pages を渡して上書きします。これは、サーフェスごとに異なるレイアウトタイプを使用したい場合や、デフォルトセットのサブセットのみを使用したい場合に便利です。統合がサポートしていない (surface, layout_type) の組み合わせを渡すと、サポートされている値を示す 400 が返されます。pages: [] を送信することは、フィールドを省略するのと同じ扱いです。

リクエストとレスポンスリクエストとレスポンス への直接リンク

配列を POST /v1/accounts/register/partnership に渡します:

{
  "brand": "Acme Apparel",
  "vertical_id": 1500,
  "sub_vertical_id": 1610,
  "country_code": "US",
  "platform_parent_account_id": "<your-platform-parent-account-id>",
  "store_identifier": "https://acme-apparel.example.com",
  "external_account_id": "partner-merchant-abc123",
  "pages": [
    { "surface": "confirmation", "layout_type": "Overlay"  },
    { "surface": "tracking",     "layout_type": "Embedded" },
    { "surface": "returns",      "layout_type": "Embedded" }
  ]
}

レスポンスには、各サーフェスごとに1つのエントリを持つ pages 配列が含まれています。各エントリは、SDKコードがどの page_identifier 文字列を selectPlacements に渡すべきかを示します:

{
  "account_id": "<your-account-id>",
  "pages": [
    { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" },
    { "surface": "tracking",     "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" },
    { "surface": "returns",      "page_id": "7a31963a-...", "layout_id": "4865f1ab-...", "page_identifier": "returns_page" }
  ]
}

page_identifier の値 (confirmation_page, tracking_page, returns_page) は、Roktによって定義された固定定数であり、統合タイプに応じて使用されます。登録されたすべてのマーチャントは同じ識別子を受け取ります。これらはマーチャントごとの値ではありません。SDK統合に保存し、配置を正しいサーフェスにルーティングします。

SDKコードはこの文字列を読み取り、selectPlacements に渡します:

await launcher.selectPlacements({
  identifier: "confirmation_page",   // ← from the response above
  attributes: { email: customer.email, /* ... */ }
});

完全なSDKセットアップについては、SDK Integration を参照してください。

検証ルール検証ルール への直接リンク

エンドポイントは、以下の場合に説明的な 400 エラーでリクエストを拒否します:

  • surface 値が confirmation / tracking / returns のいずれでもない場合。
  • layout_type 値が統合のプリセットで宣言されていない場合。完全なセットは Overlay と Embedded です。統合はそのサブセットのみをサポートする場合があります。エラーメッセージはプリセットが受け入れる値を示します。
  • 同じ surface が配列内で複数回出現する場合。
  • pages 配列が存在するが空の場合（フィールドを省略してプリセットのデフォルトを使用するか、少なくとも1つのエントリを含めます）。
  • 統合のプリセットに LayoutSpecs が全く設定されていない場合。このエラーが表示されたらRoktに連絡してください。

マーチャントのレイアウトのカスタマイズマーチャントのレイアウトのカスタマイズ への直接リンク

登録レスポンスには、ページごとに layout_id が含まれています。既存のレイアウトをテーマ化するには、/v1/partnership/accounts/{account_id}/layouts/{layout_id} にスパースPATCHを送信します。現在、5つのテーマトークンが公開されています:

  • primaryColor: インタラクティブアクセント（進行コントロール/インジケーター）
  • backgroundColor: 外側/メインおよびボディコンテナの背景
  • textColor: ヘッダー、段落、およびフッターのテキストカラー
  • borderRadius: コンテナのコーナー半径（0–24 px）
  • closeButtonColor: 閉じるボタンのテキスト + ボーダー（Overlayのみ）

これら5つのフィールドはすべてオプションです。変更したいキーのみを送信し、その他はそのままにします。Roktはまた、保存のたびに基礎となるテンプレートを最新の公開パッチに自動で更新するため、マーチャントは小さな上流の修正を自動で受け取ります。

注記

フォントファミリーのオーバーライドはまだこのエンドポイントで公開されていません。パートナーがアカウントに対してフォントをアップロードする必要があり、現在はパートナー向けのエンドポイントがありません。カスタムフォントは、そのアップロードフローと共に後のリリースで提供されます。暫定的にデフォルト以外のフォントが必要な場合は、Roktの担当者に連絡してください。

curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/9d11d8aa-5678-4def-9abc-bbbbccccdddd \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#FF6B35",
    "backgroundColor": "#FFFFFF",
    "borderRadius": 8
  }'

より深いカスタマイズ（新しいテーマキー、コピーオーバーライド）については、Roktの担当者に連絡してください。

登録後のページ追加登録後のページ追加 への直接リンク

既に登録されたマーチャントにサーフェスを追加する必要がありますか（例: tracking ページを、confirmation のみが設定されているマーチャントに追加する）? POST /v1/partnership/accounts/{account_id}/pages は、登録 pages 配列と同じ surface + layout_type エントリを受け入れます:

注記

platform_integration の値は、統合の識別子です（例: your-integration-name）。これは登録するすべてのマーチャントに対して同じです。Rokt は統合を設定する際にこれを設定します。

curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_integration": "<your-preset-key>",
    "pages": [
      { "surface": "tracking", "layout_type": "Embedded" }
    ]
  }'

各エントリは新しい Page と、レイアウトタイプの標準Roktテンプレートにリンクされたマーチャントごとのテンプレート Layout を作成します。レスポンスは登録と同じ pages の形状を持ちます。返された page_identifier を各サーフェスごとに保存し、Web SDK に渡します。

現在の add-page エンドポイントは、新しいページをアカウントのターゲティングルールセットにリンクしません。統合がルールセットのリンクに依存する場合は、最初の登録呼び出しで完全なサーフェスセットを設定してください。

同じサーフェスに対して2回呼び出すと、基礎となるハンドラーから 422 が返されます（クリーンな 409 ではありません）。これはV1の制限です。アカウントに存在するサーフェスを登録レスポンスの pages[].page_identifier から追跡してください。

レイアウトタイプの切り替えレイアウトタイプの切り替え への直接リンク

既存のページのレイアウトタイプを変更する必要がある場合（例えば、マーチャントが確認ページのOverlayレイアウトからEmbeddedレイアウトに変更したい場合）、PUT /v1/partnership/accounts/{account_id}/pages/{page_id}を呼び出します。ここで、{page_id}は更新したいページのIDです。この切り替えはマーチャントの再登録やページの再作成を行いません。page_idは登録またはページ追加のレスポンスで返されるpages[].page_idです:

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages/bfb5b9be-1234-4abc-9def-aaaabbbbcccc \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_integration": "<your-preset-key>",
    "layout_type": "Embedded"
  }'

ページが切り替え可能なレイアウトタイプは、統合のプリセットが登録時およびページ追加時に受け入れるセットと同じです。認識されない列挙値（例えば、タイプミスや未知の文字列）をlayout_typeとして渡すと、入力検証レイヤーから422が返されます。layout_typeが有効な列挙値であっても、統合でこのページのサーフェスに対してサポートされていない場合、サーバーから許可された値を示す400が返されます。これは登録時と同じ契約です。

切り替えが変更しない3つのこと:

  • page_identifierは同じままです。 SDKコードは引き続き同じ識別子をselectPlacementsに渡します。マーチャント側で必要な変更はアンカー要素以外ありません（Embeddedレイアウトはマーチャントのページに<div id="rokt-container"></div>が必要です）。
  • ページのURLターゲティングは同じままです。 切り替えは配置のレンダリング方法を変更するだけで、ページが発火する場所は変わりません。
  • テーマの編集は保持されます。 レイアウトPATCHエンドポイントを通じて適用されたカスタマイズはそのレイアウトに残ります。以前に使用していたレイアウトタイプに戻すと、テーマ編集を含む以前のレイアウトが復元されます。

ページが既に使用しているlayout_typeを要求すると、200レスポンスが返され、変更は行われません。これは調整ループの一部として安全に呼び出せます。

レスポンスには、ページで現在アクティブなlayout_idが含まれます。その値を使用して後続のテーマ編集を行います。切り替え前に取得したlayout_idは、現在非アクティブなレイアウトを指します:

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "status": "ok",
    "page": {
      "surface": "confirmation",
      "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc",
      "layout_id": "f8700369-5678-4def-9abc-bbbbccccdddd",
      "page_identifier": "confirmation_page"
    }
  }
}

エンドポイントは、404 を返します。これは、page_id（または account_id）が存在しないか、マネージャーアカウントでアクセスできない場合です。また、ページが切り替え可能な状態でない場合には、422 を返します。登録または add-pages によって返されるすべての page_id は切り替え可能であるため、標準フローを使用するパートナーは 422 のケースに遭遇することはありません。

この記事は役に立ちましたか？
Last updated Aug 4, 2026