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

レイアウトのカスタマイズ

Audience

このAPIは、Roktネットワーク上で構築する統合パートナー向けです。Roktのeコマースパートナーで独自の直接統合を構築する場合は、Rokt Ecommerce SDK Integration Guideを参照してください。

このレシピは、すでにオンボードされたマーチャントにおけるフルレイアウトカスタマイズライフサイクルをカバーします：レイアウトをテーマ化し、ページを他のレイアウトタイプに切り替え、新しいレイアウトをテーマ化し、元に戻します。2つのエンドポイント（レイアウトPATCHとページスイッチPUT）が作業を行い、登録応答が両方に必要な識別子を提供します。基礎となるモデル（サーフェス、レイアウトタイプ、テーマトークン）については、Pages and Layoutsを参照してください。

注記

レイアウト編集エンドポイントは、パートナーシップAPIにおける唯一のPATCHサーフェスです：スパース更新を受け入れます。変更したいテーマキーのみを送信し、それ以外はすべて保持されます。これは、コントロールエンドポイントのSETセマンティクスとは反対です。

  1. Capture layout_id and page_id from registration

    登録（またはadd-pages）応答のpages[]エントリには、このレシピで使用する2つの識別子が含まれています：テーマ編集用のlayout_idとレイアウトタイプ切り替え用のpage_idです。これらをマーチャントごとにサーフェスごとに保存してください。

    {
      "account_id": "<your-account-id>",
      "pages": [
        { "surface": "confirmation", "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc", "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd", "page_identifier": "confirmation_page" }
      ]
    }
  2. Apply theme edits

    レイアウトにスパースPATCHを送信します。5つのテーマトークンが公開されており（primaryColor, backgroundColor, textColor, borderRadius, closeButtonColor）、これらはすべてオプションです。

    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
      }'
    {
      "status": "ok",
      "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
      "layout_template_version": "3.0.7"
    }

    layout_template_versionは、レイアウトが保存されたテンプレートバージョンです。Roktは保存のたびに最新の公開パッチに自動でバンプするため、編集前に保存されていたものより高い可能性があります。

  3. Switch the page's layout type

    ページを他のレイアウトタイプ（ここではOverlay → Embedded）に移動するには、ページスイッチPUTを使用します。page_idはステップ1で取得したものです。

    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"
      }'
    {
      "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"
        }
      }
    }

    応答のdata.page.layout_idは、ページ上で現在アクティブなレイアウトです。これをキャプチャしてください。以降のテーマ編集はこのIDをターゲットにする必要があります。ステップ1のlayout_idは現在非アクティブなレイアウトを指します。page_idとpage_identifierは変更されません：あなたのSDKコードは同じ識別子をselectPlacementsに渡し続けますが、Embeddedレイアウトにはマーチャントのページ上で<div id="rokt-container"></div>が必要です。

    注記

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

  4. Theme the new layout (optional)

    新しいレイアウトは、そのタイプの標準的なRoktテンプレートから始まります。ステップ2のテーマ編集は古いレイアウトに属し、この新しいレイアウトには属しません。マーチャントが新しいレイアウトもテーマ化したい場合は、スイッチ応答からキャプチャしたlayout_idをPATCHしてください。

    curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/f8700369-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",
        "borderRadius": 8
      }'
  5. Switch back: theme edits are preserved

    ページが以前に使用していたレイアウトタイプに戻すと、以前のレイアウトが復元され、そのテーマ編集も含まれます。応答はステップ1からの元のlayout_idを返します。ステップ2で設定したprimaryColor、backgroundColor、およびborderRadiusはまだ適用されています。

    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": "Overlay"
      }'
    {
      "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": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
          "page_identifier": "confirmation_page"
        }
      }
    }

一般的なエラー一般的なエラー への直接リンク

422: 未認識のlayout_type値

layout_typeが認識されていない列挙型の値（例えば、タイプミスや未知の文字列）である場合に返されます。APIの入力検証が、リクエストがトランザクション層に到達する前にこれをキャッチします。渡した値を、文書化された列挙型であるOverlayおよびEmbeddedと照合してください。

400: layout_typeは有効だが、このサーフェスではサポートされていない

layout_typeが有効な列挙型の値であるが、あなたの統合におけるこのページのサーフェスではサポートされていない場合に返されます。エラーメッセージは、あなたのプリセットが受け入れる値を示します。あなたの統合が何を受け入れるのか不明な場合は、Roktの担当者に連絡してください。

404: 不明なページまたはレイアウト

page_id（switch PUTで）またはlayout_id（theme PATCHで）がアカウントに存在しない、アーカイブされている、またはaccount_idがあなたのマネージャーアカウントでアクセスできない場合に返されます。登録またはadd-pagesのレスポンスに対して識別子を再確認し、スイッチ後のテーマPATCHはスイッチレスポンスからのlayout_idをターゲットにする必要があることを忘れないでください。Errorsを参照して、エンベロープの形状を確認してください。

422: ページまたはレイアウトが編集可能/スイッチ可能な状態にない

ページがパートナーシップフロー（switch PUT）を通じて作成されていないか、レイアウトがパートナーシップオンボーディング（theme PATCH）を通じて作成されていない場合に返されます。登録またはadd-pagesで返されるすべてのpage_idおよびlayout_idはスイッチ可能で編集可能なので、標準フローを使用するパートナーはこれを目にすることはありません。422とerror: "ValidationFailed"は、必要なヘッダーが欠落していることを意味します。X-Platform-Parent-Account-Idを確認してください。

両方のエンドポイントは、標準の書き込みレート制限を共有しています。429が発生した場合、Retry-Afterを遵守し、同じIdempotency-Keyで再試行してください。

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