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

セッションAPI統合 (S2S)

統一された**セッションAPI (v2)**を使用してRoktのサーバー間通信を統合します。これはRoktのSDKを支える同じ /v2/sessions/* エンドポイントです。サーバーがRoktにオファーを取得するために呼び出し、オファーをレンダリングし、エンゲージメントとコンバージョンイベントを報告します。

資格情報を取得するには、Roktアカウントチームと連携してください。

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

目的メソッドURL
オファーを取得POSThttps://api.rokt.com/v2/sessions/offers
イベントを報告POSThttps://api.rokt.com/v2/sessions/events

各エンドポイントの完全なリクエスト/レスポンスリファレンスについては、オファーAPI仕様およびイベントAPI仕様を参照してください。

サーバー間通信はデフォルトでWebとして分類されます。Roktページがネイティブプラットフォーム（iOSまたはAndroid）用に設定されている場合、各オファー呼び出しでそのプラットフォームに**rokt-platform-type**ヘッダーを設定してください。そうしないと、リクエストはWebとして扱われ、ネイティブ設定されたページは一致せず、ページ検出はオファーを返しません。Web設定されたページにはヘッダーは不要です。受け入れられる値はiOS、Android、Web、WebDesktop、WebMobile（大文字小文字を区別しない）です。それ以外はWebにフォールバックします。

注記

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

認証認証 への直接リンク

  • rokt-account-idヘッダーはすべての呼び出し（オファーとイベント）で必須です。これはセッションAPI上のアカウント識別のソースです。
  • オファー呼び出し — 最初のセッションなしの呼び出しでは、**Authorization: Basic base64(rpub:rsec)**で認証します。ここでrpubとrsecはアカウントチームから提供される公開および秘密のAPIキーです。(Authorization: Bearer <session_token>は既存のセッションを継続するためにのみ使用されます。)
  • イベント呼び出し — オファー呼び出しと同じ公開および秘密のAPIキーを使用して、**Authorization: Basic base64(rpub:rsec)**で認証します。

1. オファーをリクエストする1. オファーをリクエストする への直接リンク

型付きリクエストボディを送信し、channel.typeを"s2s"に設定します。以下のすべての値は合成例です。

POST https://api.rokt.com/v2/sessions/offers
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
rokt-platform-type: <iOS | Android | 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"
  }
}
  • トップレベルオブジェクト (page, customer, transaction, payment, device, cart, shipping) は型指定されており、定義されたフィールドのみを受け入れます。それらに適合しないパートナー固有のシグナルは、自由形式のattributes文字列マップに入れてください。
  • 所有する値のみを送信してください。 Rokt由来の属性 — 地理、年齢およびその他の人口統計（Roktプロファイルから）、デバイスタイプ/OS/バージョン（ユーザーエージェントから解析）、支払い方法/サブメソッド（カードBINから）、およびML/Carbonシグナル — はサーバー側で計算され、送信された場合は上書きされます。それらを含めないでください。

2. オファーのレスポンスを解析する2. オファーのレスポンスを解析する への直接リンク

2xx の場合、オファーは直接返されます（success/errors のエンベロープはありません）。plugins は空である可能性がありますが、これは有効なノーフィルであり、実際のプロダクショントラフィックの一部です: 何もレンダリングせずにページを続行します。slots には、実際に埋められたスロットのみが含まれ、レイアウトで定義された最大数までです。ネストされたプラグイン構造からオファーを読み取り、非2xx の場合、構造化されたエラーボディを解析します。

必要な情報レスポンス内のパス
オファーplugins[].plugin.config.slots[].offer
タイトル / コピー…offer.creative.copy["creative.title"]
画像…offer.creative.copy["creative.image.src"]
広告主…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

エラーは意味のあるHTTPステータスを返し、ボディには { "error": "<code>", "message": "<detail>" } が含まれます（検証失敗には details[] 配列が追加されます）。

3. オファーをレンダリングする3. オファーをレンダリングする への直接リンク

レンダリング方法は、アカウントのレイアウトがどのように構成されているかによって異なります — アカウントがどの契約を提供しているかをRoktチームに確認してください:

  • セルフレンダー（データ統合） — レスポンスはオファーのコンポーネント（クリエイティブコピー、画像、レスポンスオプション — ステップ2のパス）を持ち、レイアウトの説明はありません: 自分のUIでオファーを描画し、各エンゲージメントイベントを自分で報告します（ステップ4）。
  • Rokt UX Helper（Rokt設計のレイアウト） — レスポンスの plugins[] はRoktのオープンソースUX Helperライブラリ（Web、iOS、Android）がUI内でレンダリングし、エンゲージメントイベントを転送するための完全なレイアウト説明を持っています。UX HelperはExperiences APIのペイロード形状を消費します; セッションAPIは異なるエンベロープ（スネークケース）で同じレイアウトコンテンツを返すため、/v2/sessions/offers とペアリングするには現在、小さなレスポンスの適応が必要です — Roktチームに相談してください。

契約はレスポンス自体から区別できます: データ統合アカウントは空のレイアウトスキーマでオファーを返し、レイアウトアカウントは outer_layout_schema とスロットごとの layout_variant フィールドが埋められた状態で返します。

4. イベントの報告4. イベントの報告 への直接リンク

エンゲージメントとコンバージョンイベントを /v2/sessions/events に報告し、オファーコールと同じBasic認証情報で認証します。各イベントでオファーの応答によって返されるトップレベルの session_id と single_session: true を使用してセッションを識別します。

POST https://api.rokt.com/v2/sessions/events
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
Content-Type: application/json
{
  "channel": { "type": "s2s" },
  "single_session": true,
  "events": [
    {
      "event_type": "impression",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ab",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234567000,
      "data": {
        "parent_id": "018f2a1b-3333-7abc-8def-creative001",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>",
        "capture_method": "ClientProvided"
      }
    }
  ]
}

  • event_type — スネークケースの文字列で表されるイベントの種類。一般的な値:

    イベントevent_type
    インプレッションimpression
    表示済みviewed
    ポジティブ/ネガティブ応答signal_response
    解約dismissal
    コンバージョンconversion_signal
    購入purchase

  • instance_id — このイベントを識別するクライアント生成のUUIDで、重複を排除するために使用されます。

  • session_id — オファーの応答によって返されるトップレベルの session_id。

  • data.parent_id — イベントに関する要素の instance_guid で、オファーの応答から取得されます（例：インプレッションの場合はクリエイティブの instance_guid、応答の場合は応答オプションのもの）。セッションツリーを構築します。値をそのままエコーします; ad:<uuid> のようなタイププレフィックスを含む場合があります。

  • data.page_instance_guid — オファーの応答からの page_instance_guid。

  • data.token — オファーの応答からその要素のイベントトークン。

  • timestamp — Unixエポックミリ秒。

  • リクエスト内のすべてのイベントに single_session を true に設定し、session_id を含めます。

成功した呼び出しは、次の呼び出しのために更新された session_token、event_ids[]、各イベントの {index, code, message} を含む errors[]、および warnings[] と共に 202 Accepted を返します。

チェックリストチェックリスト への直接リンク

  • Roktアカウントチームとクレデンシャルおよび完全なAPIリファレンスを確認してください。
  • /v2/sessions/offersを、型付きボディchannel.type: "s2s"およびrokt-account-idヘッダー（ページがネイティブプラットフォーム用に設定されている場合はrokt-platform-typeも）で呼び出します。
  • plugins[].plugin.config.slots[].offer.creativeからオファーを解析し、成功/失敗のためにHTTPステータスを使用し、空のplugins（ノーフィル）の場合は何もレンダリングしないように処理します。
  • アカウントのレイアウト設定に従って、オファーを自分でまたはUXヘルパーライブラリを通じてレンダリングします。
  • session_idをキャプチャし、Basic認証、single_session: true、イベントごとのsession_id、およびレスポンスのdata.parent_idとdata.page_instance_guidの値を使用して、イベントを/v2/sessions/eventsに報告します。
  • rokt-test-session: trueヘッダーで検証します（報告のみ—オファーの提供を強制しません）、その後、プロダクションに切り替えるために削除します。
この記事は役に立ちましたか？
Last updated Aug 4, 2026