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

サーバーオファーAPI仕様

このドキュメントは、RoktのAPIと連携してRoktからオファーコンテンツを取得するために必要な関連エンドポイントを概説しています。

このエンドポイントと連携するために必要な資格情報を取得するには、アカウントマネージャーと協力してください。

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

環境アクションURL
本番POSThttps://server-api.rokt.com/v1/partner/offers
テストPOSThttps://server-api-demo.rokt.com/v1/partner/offers

テストのベストプラクティステストのベストプラクティス への直接リンク

テストエンドポイント https://server-api-demo.rokt.com/v1/partner/offers はテスト専用に設計されており、本番データやパフォーマンスに影響を与えることなく統合を検証するために使用されるべきです。APIドキュメントで指定されている適切なヘッダーとリクエスト形式を使用して、本番に近いシナリオを効果的にエミュレートしてください。

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

ルート/ボディルート/ボディ への直接リンク

プロパティ名必須データ型説明
pageIdentifierはいstringビューを区別するために使用されるテキスト
attributesはいDictionary<string, string> / Map<string, string>オファー選択に使用されるユーザー属性データを含む。

WebMobile/WebDesktop リクエストのみ:
userAgent（ブラウザから派生）を属性として含めます。以下の例を参照してください。

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

ヘッダーキー説明タイプ注記
rokt-pub-id提供されたクライアントパブリックIDを含むstringこれはRoktによって提供されます。
rokt-secret提供されたクライアントパブリックシークレットを含み、パブリックIDと一致する必要がありますstringこれはRoktによって提供されます。

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

ヘッダーキー説明タイプ例
content-typeメディアタイプstring“application/json”
acceptレスポンスの期待されるメディアタイプstring“application/json”
rokt-tag-idRoktタグIDString1234567890
rokt-ui-localeユーザーインターフェースの文化と言語StringISOロケールと国の識別子。例: en-US
rokt-client-unique-idパートナーとRoktシステム間のトラブルシューティング用String参照トランザクションID（ユニークID）
rokt-platform-typeオファーが要求されているプラットフォームを示すstringデフォルト: Mobile
受け入れ可能な値: Mobile, Web, WebMobile, WebDesktop

モバイル用追加必須ヘッダーモバイル用追加必須ヘッダー への直接リンク

Mobile プラットフォームのオファーをリクエストする際、以下のヘッダーも必要です：

Header-key説明タイプ例
rokt-os-typeOS タイプstring"iOS" または "Android"
rokt-os-versionOS バージョンString"8.0" または "4.4.1"
rokt-device-modeliOS のデバイスモデルまたは Android のビルドモデルString"iPhone 6s", "Galaxy S9", など
rokt-package-nameホストアプリケーションの PackageName または BundleIdentifierStringiOS: com.APPNAME.ios
Android: com.APPNAME.android
指定されたクライアントアプリケーションの実際のパッケージ名を使用
rokt-package-versionホストアプリケーションのパッケージバージョンまたはバンドルバージョンString1.0.5
指定されたクライアントアプリケーションの実際のパッケージバージョンを使用

リクエスト例（モバイルアプリ）リクエスト例（モバイルアプリ） への直接リンク

JSON リクエストボディ/ペイロード

{
    "attributes": {
        "country": "AU",
        "firstname": "jenny",
        "mobile": "(323) 867-5309",
        "postcode": "90210",
        "email": "test1593754986316@rokt.com",
        "lastname": "Smith"
    },
    "pageIdentifier": "page_identifier"
}

リクエスト例（モバイル/デスクトップウェブ）リクエスト例（モバイル/デスクトップウェブ） への直接リンク

JSON リクエストボディ/ペイロード

{
    "attributes": {
        "country": "AU",
        "firstname": "jenny",
        "mobile": "(323) 867-5309",
        "postcode": "90210",
        "email": "test1593754986316@rokt.com",
        "lastname": "Smith",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3.1 Safari/605.1.15"
    },
    "pageIdentifier": "page_identifier"
}

  • userAgent はブラウザから取得可能、例：window.navigator.userAgent を介して。

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

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

ルート/ボディルート/ボディ への直接リンク

プロパティ名データタイプ説明
sessionIdstringRokt セッション ID
pageInstanceGuidstringユーザーのページインスタンスの一意の識別子
pageDetectionTimestringページ検出が行われた時間
successbooleanリクエストが成功したかどうかを示します
placementsPlacement[]オファー/プレースメントのコレクション

プレースメントプレースメント への直接リンク

プロパティ名データタイプ説明
experienceIdstringRokt から選択されたエクスペリエンスを表す識別子。明示的にエクスペリエンスが選択されていない場合、値は NotSet になります
placementGuidstringプレースメントに固有の GUID で、イベントコールの一部として送信されます
configurablesDictionary<string, string> / Map<string, string>オファーをレンダリングするために使用される動的パラメータのコレクション
targetingDataTargetingData現在のオファーセットが表示された理由に関する情報、広告主情報を含む、デジタルサービス法の要件のため
offersPartnerOffer[]表示するオファーのコレクション

パートナーオファーパートナーオファー への直接リンク

プロパティ名データ型説明
creativeIdstringRoktプラットフォームにおけるオファーのクリエイティブのユニークID。1
campaignIdstringRoktプラットフォームにおけるオファーのキャンペーンのユニークID。1
slotGuidstringオファースロットを表すユニークなGUID
creativeGuidstringオファー/クリエイティブを表すユニークなGUID
copyDictionary<string, string> / Map<string, string>オファーデータを提供するために使用されるKVPのコレクション
responseOptionsResponseOption[]可能な応答オプションのコレクション
advertiserAdvertiserこのオファーの背後にいる広告主の詳細
formatTypestringオファーを表示するフォーマットタイプ

1 IDはEコマースキャンペーンに提供され、他のキャンペーンタイプには値が提供されます: NotSet

コピーコピー への直接リンク

プロパティ名データ型説明
creative.copystringコピーの内容
creative.titlestringコピーのタイトル
creative.disclaimerstring免責事項のテキスト
creative.termsAndConditions.linkstring利用規約へのリンク
creative.privacyPolicy.linkstringプライバシーポリシーへのリンク

応答オプション応答オプション への直接リンク

プロパティ名データ型説明
actionstring応答のアクション
“CaptureOnly” - イベントを発火するだけ
“Url” - URLを開いてイベントを発火する必要がある
responseOptionGuidstring応答オプションに固有でイベント呼び出しの一部として送信されるGUID
signalTypestringインタラクション時にイベントを送信する際に使用するEventType。ほとんどの場合、これはSignalResponseです
labelstringボタン/リンクに表示されるラベル
successTextstringインタラクション時に表示されるテキスト（パイロットには関連しない）
isPositiveboolean応答がポジティブなエンゲージメントかネガティブなエンゲージメントかを示す
urlstringアクションを実行するURL

ターゲティングデータターゲティングデータ への直接リンク

プロパティ名データ型説明
linkstringこのオファーの選択が表示された理由に関する詳細情報へのハイパーリンクで、セッションに固有の広告主情報を含みます。このリンクを表示することで、デジタルサービス法の義務を果たすのに役立ちます
copystringパートナーがRoktを使用して顧客に最も関連性の高いオファーを表示する方法を示すテキスト
advertisersAdvertiser[]現在のオファーセットの背後にいる広告主のコレクションで、オファーが表示される順序で並べられています

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

プロパティ名データ型説明
namestring広告主のアカウント名/法的実体
brandstring広告主のブランド名

免責事項と利用規約の見つけ方免責事項と利用規約の見つけ方 への直接リンク

プロパティ名データ型オファー応答位置 (JSON パス)
免責事項stringbody.placements[i].offers[j].copy.creative.disclaimer
利用規約リンクstringbody.placements[i].offers[j].copy.creative.termsAndConditions.link

ここで:

  • i は表示されている配置のインデックスを表します
  • j は表示されているスロットのインデックスを表します

例例 への直接リンク

{
    "sessionId": "aec20020-2d5c-45e7-ac3d-6f5daa22b983",
    "pageInstanceGuid": "aec20020-2d5c-4497-87e8-475576ddffa5",
    "pageDetectionTime": "2022-06-28T01:57:09.2147413+00:00",
    "placements": [
        {
            "experienceId": "RedButton",
            "placementGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "targetingData": {
                "link": "https://apps-demo.rokt.com/dsa/rokt-en.html?name=Legal%20Name%20One&brand=Brand%20Name%20One&name=Legal%20Name%20Two&brand=Brand%20Name%20Two",
                "copy": "Text displaying how Partners use Rokt to determine the most relevant offers to show customers",
                "advertisers": [
                    {
                        "name": "Legal Name One",
                        "brand": "Brand Name One"
                    },
                    {
                        "name": "Legal Name Two",
                        "brand": "Brand Name Two"
                    }
                ]
        },
            "offers": [
                {
                    "creativeId": "NotSet",
                    "campaignId": "NotSet",
                    "slotGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
                    "creativeGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
                    "copy": {
                        "creative.copy": "This is an Rokt Commerce Email Campaign from Mobile team Account. This should appear in prime position for the mobile SDK automated testing. ",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732356166940819466",
                        "creative.termsAndConditions.close.copy": "Close",
                        "creative.termsAndConditions.title": "Terms of Use",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732356166940819466",
                        "creative.privacyPolicy.close.copy": "Close",
                        "creative.privacyPolicy.title": "Privacy Policy",
                        "creative.confirmation.message": "Details will go to test1593754986316@rokt.com",
                        "creative.success.title": "Success",
                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
                    },
                    "advertiser": {
                        "name": "Legal Name One",
                        "brand": "Brand Name One"
                    }
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
                            "signalType": "SignalResponse",
                            "label": "Yes",
                            "successText": "Subscribed",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "04c74a56-9fa7-408e-b722-052ae275f53f",
                            "signalType": "SignalResponse",
                            "label": "No thanks",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "Text"
                },
                {
                    "creativeId": "2732357120423559183",
                    "campaignId": "2732344566234284034",
                    "slotGuid": "e499763e-769e-4621-8591-c55c6b833e1f",
                    "creativeGuid": "11096aa6-878f-4bb7-acb5-156d0999edb8",
                    "copy": {
                        "creative.disclaimer": "<strong>Disclaimer</strong>",
                        "creative.copy": "This is an acquire email campaign from Mobile team Account for mobile SDK automated testing.",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732357120423559183",
                        "creative.termsAndConditions.close.copy": "Close",
                        "creative.termsAndConditions.title": "Terms &amp; Conditions",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732357120423559183",
                        "creative.privacyPolicy.close.copy": "Close",
                        "creative.privacyPolicy.title": "Privacy Policy",
                        "creative.confirmation.message": "Confirmation will go to test1593754986316@rokt.com",
                        "creative.success.title": "Success",
                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
                    },
                    "advertiser": {
                        "name": "Legal Name Two",
                        "brand": "Brand Name Two"
                    },
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "779e41cd-5653-4143-b0bb-3df4eb3a2325",
                            "signalType": "SignalResponse",
                            "label": "Yes please",
                            "successText": "Email Sent",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "87af7302-0c53-4676-a002-8f0f8fcbb530",
                            "signalType": "SignalResponse",
                            "label": "No thanks",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "Text"
                }
            ],
            "configurables": {
                "positive.button.color": "red"
            }
        }
    ],
    "success": true
}

空の成功応答 (200)空の成功応答 (200) への直接リンク

特定のユーザーに関連するオファーがないという稀なケースがあります。この場合、Roktは配置のないペイロードを返します:

{
    "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
    "pageInstanceGuid": "aec20024-8d24-4ee5-8b6b-2b45364e678b",
    "pageDetectionTime": "2022-06-28T02:13:04.7608276+00:00",
    "placements": [],
    "success": true
}

リクエストエラー応答 (4XX)リクエストエラー応答 (4XX) への直接リンク

ルート/ボディルート/ボディ への直接リンク

プロパティ名データ型説明
titlestringトップレベルの失敗理由
statusnumberHTTP ステータスコード
successbooleanリクエストが成功したかどうかを示します
errorsError[]発生したバリデーションエラーのコレクション

エラーエラー への直接リンク

プロパティ名データ型説明
codestring対応するエラーコード
messagenumberエラーを説明するメッセージ
valueboolean無効だった提供値（あれば）

例: リクエストバリデーションエラー (422)例: リクエストバリデーションエラー (422) への直接リンク

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "PartnerIdNotIncluded",
            "message": "rokt-tag-id is missing/incorrect",
            "value": "0"
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-os-type."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-package-name."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-package-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-device-model."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-sdk-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-os-version."
        },
        {
            "code": "ClientUniqueIdIsMissing",
            "message": "Missing header: rokt-client-unique-id."
        },
        {
            "code": "PlatformTypeIsInvalid",
            "message": "Invalid header: rokt-platform-type."
        }
    ]
}

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

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Request body format is not valid"
        }
    ]
}

例: リクエストが多すぎる場合 (429)例: リクエストが多すぎる場合 (429) への直接リンク

Roktは、プラットフォームの安定性を保護したり、ポリシーを施行するためにトラフィックを制限したり、一時的にブロックしたりすることがあります。このような場合、APIはHTTP 429を空のボディとRetry-Afterヘッダーなしで返します。これらのリクエストを再試行しないでください。自動再試行は負荷を増加させ、スロットリングを長引かせる可能性があります。このフローのさらなる呼び出しを一時停止し、リクエストレートを確認し、429が続く場合はRoktの担当者に連絡してください。

内部サービスエラー (5XX)内部サービスエラー (5XX) への直接リンク

まれに、システムが予期せずリクエストを完了できない場合があります。この場合、標準的なHTTPレスポンスコードに準拠した適切なステータスコードを持つボディなしのリクエストを返します。このレスポンスが発生した場合、短い遅延（1〜2秒）の後にリクエストを再試行することをお勧めします。

問題が続くか、一貫して発生する場合は、問題の特定と修正を支援するためにサポート（support@rokt.com）に連絡してください。

オファーのキャッシングオファーのキャッシング への直接リンク

Roktのオファーをタイムリーにレンダリングすることで、ユーザーのエンゲージメントとコンバージョンからの収益機会を最大化できます。しかし、サーバー間の統合には、Roktのバックエンドサーバーとあなたのサーバー間で追加のネットワーク呼び出しが含まれ、オファーをレンダリングするために必要なデータの取得が遅れます。

パフォーマンスを向上させるために、ユーザーのトランザクションの流れの中で、Roktの/offers APIエンドポイントからオファーコンテンツを早めに取得することをお勧めします。オファーがレンダリングされることが予想される前に、ユーザーがトランザクションを完了することに大きな関心を示した後でオファーコンテンツの取得を開始するのがベストプラクティスです。

受信したデータはキャッシュに保存できます。これにより、同じトランザクション内でのクライアントによる後の高速な取得が可能になります。

ユニークなトランザクションID、ユーザーID、およびユーザーのデバイスタイプの組み合わせに対してキャッシュすることをお勧めします。ユーザーコンテキストが変化するシナリオ（例：AndroidデバイスからiOSデバイスへの移行）では、クライアントは更新された顧客属性を使用して/offersエンドポイントから新しい配置を取得する必要があります。これにより、レンダリングされたオファーが顧客の現在のコンテキストに関連するものとして維持されます。

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