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

セッションオファーAPI仕様 (S2S)

このドキュメントは、セッションAPI (v2) を使用してRoktからオファーコンテンツを取得するために必要なエンドポイントを概説しています。

必要な認証情報を取得するには、Roktのアカウントチームと連携してください。エンドツーエンドの統合手順については、セッションAPI統合 (S2S)を参照してください。

エンドポイントエンドポイント への直接リンク

環境アクションURL
本番POSThttps://api.rokt.com/v2/sessions/offers
注記

別のサンドボックスURLはありません。本番稼働前に検証するには、同じエンドポイントでrokt-test-session: trueヘッダーを送信してください。テストセッションはタグ付けされ、本番のメトリクスから除外されます。このヘッダーは報告のみをマークし、オファーの提供を強制するものではありません。決定論的なエンドツーエンドテストのために、アカウントチームは専用のテストキャンペーンを持つステージングページを設定できます。本番稼働するにはヘッダーを削除してください。

リクエストリクエスト への直接リンク

認証ヘッダー認証ヘッダー への直接リンク

ヘッダー説明タイプ注記
Authorizationベーシック認証情報stringBasic base64(rpub:rsec) — アカウントチームから提供された公開および秘密のAPIキーを使用します。
rokt-account-idあなたのRoktアカウントIDstringすべての呼び出しで必要です。これはセッションAPI上のアカウント識別のソースです。

必須ヘッダー必須ヘッダー への直接リンク

ヘッダー説明タイプ例
Content-Typeメディアタイプstringapplication/json
rokt-platform-typeオファーがリクエストされるプラットフォームstringiOS, Android, Web, WebDesktop, または WebMobile (大文字小文字を区別しません)。デフォルトは Web です。
注記

サーバー間トラフィックはデフォルトでWebとして分類されます。Roktページがネイティブプラットフォーム（iOSまたはAndroid）用に設定されている場合は、そのプラットフォームにrokt-platform-typeヘッダーを設定してください。そうしないと、ページ検出がネイティブ設定されたページと一致せず、オファーが返されません。Web設定されたページにはヘッダーは必要ありません。

Root/BodyRoot/Body への直接リンク

PropertyRequiredTypeDescription
channelはいobject"type": "s2s"を含む必要があります。
pageはいobjectPageを参照してください。
customerいいえobjectCustomerを参照してください。
transactionいいえobjectTransactionを参照してください。
paymentいいえobjectPaymentを参照してください。
deviceいいえobjectDeviceを参照してください。
attributesいいえobject型付きオブジェクトに適合しないパートナー固有のシグナルのための自由形式のstring → stringマップ。
注記

所有する値のみを送信してください。Rokt由来の属性 — 地理、年齢やその他の人口統計、デバイスタイプ/OS/バージョン、支払い方法、MLシグナル — はサーバー側で計算され、送信された場合は上書きされますので、含めないでください。

PagePage への直接リンク

PropertyRequiredTypeDescription
page_identifierはいstringビュー/ページを区別するために使用されるテキスト。
page_variation_codeいいえstringページのオプションのバリエーションコード。

CustomerCustomer への直接リンク

PropertyRequiredTypeDescription
emailいいえstring顧客のメールアドレス。
first_nameいいえstring顧客の名。
last_nameいいえstring顧客の姓。
genderいいえstring顧客の性別。
postal_codeいいえstring顧客の郵便番号/ZIPコード。
languageいいえstring顧客の言語コード（例: en）。

TransactionTransaction への直接リンク

PropertyRequiredTypeDescription
transaction_valueいいえnumberトランザクションの値。
currencyいいえstringISO 4217通貨コード（例: USD）。
confirmation_refいいえstringパートナー側の注文または確認参照。

支払い支払い への直接リンク

プロパティ必須タイプ説明
typeいいえstring支払い方法のタイプ（例: card）。

デバイスデバイス への直接リンク

プロパティ必須タイプ説明
user_agentいいえstringクライアントデバイスまたはアプリケーションのユーザーエージェント文字列。

リクエスト例リクエスト例 への直接リンク

POST https://api.rokt.com/v2/sessions/offers
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
rokt-platform-type: Web
Content-Type: application/json
{
  "channel": { "type": "s2s" },
  "page": { "page_identifier": "checkout" },
  "customer": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "gender": "F",
    "postal_code": "10001",
    "language": "en"
  },
  "transaction": {
    "transaction_value": 19.99,
    "currency": "USD",
    "confirmation_ref": "ORDER-000123"
  },
  "payment": { "type": "card" },
  "device": {
    "user_agent": "YourApp/1.0 (mobile)"
  },
  "attributes": {
    "your_custom_attribute": "value"
  }
}

レスポンスレスポンス への直接リンク

成功レスポンス (2xx)成功レスポンス (2xx) への直接リンク

2xx レスポンスはオファーを直接返します — success/errors エンベロープはありません。 plugins は空である場合があり、これは実際のプロダクショントラフィックのシェアを表す有効なノーフィルシナリオです: 何もレンダリングせずにページを続行します。

キーフィールドキーフィールド への直接リンク

必要なものレスポンス内のパス
オファーplugins[].plugin.config.slots[].offer
タイトル / コピー…offer.creative.copy["creative.title"]
画像…offer.creative.copy["creative.image.src"]
免責事項…offer.creative.copy["creative.disclaimer"]
利用規約リンク…offer.creative.copy["creative.termsAndConditions.link"]
プライバシーポリシーリンク…offer.creative.copy["creative.privacyPolicy.link"]
広告主…offer.creative.advertiser
ポジティブアクション + URL…offer.creative.response_options_map.positive.url
辞退アクション…offer.creative.response_options_map.negative
要素インスタンスID（イベントとして使用 parent_id）…slots[].instance_guid, …offer.creative.instance_guid, …response_options_map[key].instance_guid
ページインスタンス（イベントとして使用 page_instance_guid）page_instance_guid
セッションID（イベントとして使用 session_id）session_id
セッショントークン（更新されたセッション参照）session_token.token

広告主広告主 への直接リンク

プロパティタイプ説明
namestring広告主の法的実体名。
brandstring広告主のブランド名。

Example success response (2xx)Example success response (2xx) への直接リンク

レイアウトが設定されたアカウントは、outer_layout_schema とスロットごとの layout_variant フィールドが埋め込まれて返されます。データ統合アカウントは、同じ offer/creative コンテンツを返しますが、これらのレイアウトスキーマは空です。以下のすべての値は合成例です — 必要なフィールドは上記の Key fields パスを使用して読み取ってください。

{
  "session_id": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  },
  "plugins": [
    {
      "plugin": {
        "id": "3353172846080032866",
        "name": "dcui",
        "config": {
          "instance_guid": "ce5158a9-dc59-4a97-9006-a299901e4587",
          "outer_layout_schema": "<JSON-encoded layout schema>",
          "layout_schema_version": "2.0",
          "slots": [
            {
              "instance_guid": "8f492d28-83fb-4813-877e-26e752ea9474",
              "offer": {
                "campaign_id": "2749386944931233793",
                "account_id": "<your Rokt account ID>",
                "creative": {
                  "referral_creative_id": "2760914349384466797",
                  "instance_guid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                  "advertiser": {
                    "name": "Example Advertiser Inc.",
                    "brand": "Example Brand"
                  },
                  "copy": {
                    "creative.title": "Get 20% off your next order",
                    "creative.image.src": "https://example.com/creative/hero.png",
                    "creative.disclaimer": "New customers only. Terms apply.",
                    "creative.termsAndConditions.link": "https://example.com/terms",
                    "creative.privacyPolicy.link": "https://example.com/privacy"
                  },
                  "response_options_map": {
                    "positive": {
                      "id": "2760914349384466794",
                      "action": "Url",
                      "instance_guid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                      "signal_type": "SignalResponse",
                      "short_label": "Yes",
                      "long_label": "Yes please",
                      "is_positive": true,
                      "url": "https://example.com/redeem",
                      "url_behavior": "newTab",
                      "token": "<event-token>"
                    },
                    "negative": {
                      "id": "2760914349384466796",
                      "action": "CaptureOnly",
                      "instance_guid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                      "signal_type": "SignalResponse",
                      "short_label": "No thanks",
                      "long_label": "No thanks",
                      "is_positive": false,
                      "token": "<event-token>"
                    }
                  },
                  "token": "<event-token>"
                }
              },
              "layout_variant": {
                "layout_variant_id": "3353172846080032865",
                "module_name": "standard-marketing",
                "format_type": "Text",
                "layout_variant_schema": "<JSON-encoded layout schema>"
              },
              "token": "<event-token>"
            }
          ]
        }
      },
      "fonts": []
    }
  ]
}

No-fill response (2xx)No-fill response (2xx) への直接リンク

特定のユーザーに関連するオファーがない場合、Rokt は空の plugins 配列で 2xx を返します。何もレンダリングせず、ページを続行してください。

{
  "plugins": [],
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  }
}

Error responses (4xx / 5xx)Error responses (4xx / 5xx) への直接リンク

エラーは、構造化されたボディを持つセマンティックなHTTPステータスを返します：

{
  "error": "<code>",
  "message": "<detail>"
}

バリデーションの失敗には、追加の details[] 配列が含まれます。

Common error codesCommon error codes への直接リンク

HTTP status意味
400不正なリクエストボディ。
401欠落または無効な Authorization ヘッダー。
422リクエストのバリデーションに失敗しました（details[] を参照）。
429レート制限。自動的に再試行しないでください — 429が続く場合は、Roktの担当者に連絡してください。
5xx予期しないサーバーエラー。短時間（1–2秒）待ってから再試行してください。問題が続く場合は、support@rokt.com に連絡してください。

Caching offersCaching offers への直接リンク

収益機会を最大化するために、ユーザーのトランザクションの流れの早い段階で /v2/sessions/offers からオファーコンテンツを取得し、オファーが表示される前にキャッシュして、同じトランザクション内での迅速なクライアント取得を可能にします。

ユニークなトランザクションID、ユーザーID、およびユーザーのデバイスタイプの組み合わせに対してキャッシュすることをお勧めします。ユーザーのコンテキストが変わった場合（例：デバイスの変更）、オファーの関連性を確保するために更新された属性で再取得してください。

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