サーバーオファーAPI仕様

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

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

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

環境	アクション	URL
本番環境	`POST`	`https://server-api.rokt.com/v1/partner/offers`
テスト環境	`POST`	`https://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-id	Rokt タグID	String	1234567890
rokt-ui-locale	ユーザーインターフェースの文化と言語	String	ISO ロケールと国の識別子。例: en-US
rokt-client-unique-id	パートナーとRoktシステム間のトラブルシューティング用	String	参照トランザクションID（ユニークID）
rokt-platform-type	オファーがリクエストされるプラットフォームを示します	string	デフォルト: `Mobile` 受け入れ可能な値: `Mobile`, `Web`, `WebMobile`, `WebDesktop`

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

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

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

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

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

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

リクエスト例 (モバイル/デスクトップ Web)リクエスト例 (モバイル/デスクトップ Web) への直接リンク

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) への直接リンク

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

プロパティ名	データ型	説明
sessionId	string	Rokt セッション ID
pageInstanceGuid	string	ユーザーのページインスタンスの一意の識別子
pageDetectionTime	string	ページ検出が発生した時間
success	boolean	リクエストが成功したかどうかを示します
placements	Placement[]	オファー/プレースメントのコレクション

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

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

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

プロパティ名	データ型	説明
creativeId	string	Roktプラットフォームでのオファーのクリエイティブに対するユニークID。¹
campaignId	string	Roktプラットフォームでのオファーのキャンペーンに対するユニークID。¹
slotGuid	string	オファースロットを表すユニークなGUID
creativeGuid	string	オファー/クリエイティブを表すユニークなGUID
copy	Dictionary<string, string> / Map<string, string>	オファーデータを提供するために使用されるKVPのコレクション
responseOptions	ResponseOption[]	可能な応答オプションのコレクション
advertiser	Advertiser	このオファーの背後にいる広告主の詳細
formatType	string	オファーを表示するためのフォーマットタイプ

¹ IDはEコマースキャンペーンに対して提供され、他のキャンペーンタイプには値NotSetが設定されます

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

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

レスポンスオプションレスポンスオプションへの直接リンク

プロパティ名	データ型	説明
action	string	レスポンスのアクション “CaptureOnly” - イベントを発火するだけ “Url” - URLを開いてイベントを発火する必要がある
responseOptionGuid	string	レスポンスオプションに固有のGUIDが生成され、イベントコールの一部として送信される
signalType	string	インタラクション時にイベントを送信する際に使用するEventType。ほとんどの場合、`SignalResponse`
label	string	ボタン/リンクに表示されるラベル
successText	string	インタラクション時に表示されるテキスト（パイロットには関連しない）
isPositive	boolean	レスポンスがポジティブなエンゲージメントかネガティブなエンゲージメントかを示す
url	string	アクションを実行するURL

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

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

広告主 (Advertiser)広告主 (Advertiser) への直接リンク

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

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

プロパティ名	データ型	オファー応答の場所 (JSON パス)
Disclaimer	string	body.placements[i].offers[j].copy.creative.disclaimer
Terms and Conditions Link	string	body.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": "パートナーがRoktを使用して、顧客に最も関連性の高いオファーを表示する方法を示すテキスト",
                "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": "これはモバイルチームアカウントからのRokt Commerce Email Campaignです。これはモバイルSDKの自動テストのために主要な位置に表示されるべきです。",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732356166940819466",
                        "creative.termsAndConditions.close.copy": "閉じる",
                        "creative.termsAndConditions.title": "利用規約",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732356166940819466",
                        "creative.privacyPolicy.close.copy": "閉じる",
                        "creative.privacyPolicy.title": "プライバシーポリシー",
                        "creative.confirmation.message": "詳細はtest1593754986316@rokt.comに送信されます",
                        "creative.success.title": "成功",
                        "creative.success.copy": "確認をtest1593754986316@rokt.comに送信しました。"
                    },
```json
"advertiser": {
    "name": "Legal Name One",
    "brand": "Brand Name One"
}
"responseOptions": [
    {
        "action": "CaptureOnly",
        "responseOptionGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
        "signalType": "SignalResponse",
        "label": "はい",
        "successText": "登録完了",
        "isPositive": true,
        "url": ""
    },
    {
        "action": "CaptureOnly",
        "responseOptionGuid": "04c74a56-9fa7-408e-b722-052ae275f53f",
        "signalType": "SignalResponse",
        "label": "結構です",
        "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>免責事項</strong>",
        "creative.copy": "これは、モバイルSDKの自動テスト用にMobileチームアカウントから送信されたメール取得キャンペーンです。",
        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732357120423559183",
        "creative.termsAndConditions.close.copy": "閉じる",
        "creative.termsAndConditions.title": "利用規約",
        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732357120423559183",
        "creative.privacyPolicy.close.copy": "閉じる",
        "creative.privacyPolicy.title": "プライバシーポリシー",
        "creative.confirmation.message": "確認はtest1593754986316@rokt.comに送信されます",
```                        "creative.success.title": "成功",
                        "creative.success.copy": "確認を test1593754986316@rokt.com に送信しました。"
                    },
                    "advertiser": {
                        "name": "Legal Name Two",
                        "brand": "Brand Name Two"
                    },
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "779e41cd-5653-4143-b0bb-3df4eb3a2325",
                            "signalType": "SignalResponse",
                            "label": "はい、お願いします",
                            "successText": "メール送信済み",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "87af7302-0c53-4676-a002-8f0f8fcbb530",
                            "signalType": "SignalResponse",
                            "label": "いいえ、結構です",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "テキスト"
                }
            ],
            "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) への直接リンク

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

プロパティ名	データ型	説明
title	string	上位レベルの失敗理由
status	number	HTTPステータスコード
success	boolean	リクエストが成功したかどうかを示します
errors	Error[]	発生したバリデーションエラーのコレクション

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

プロパティ名	データ型	説明
code	string	対応するエラーコード
message	number	エラーを説明するメッセージ
value	boolean	無効だった提供値（ある場合）

例: リクエスト検証エラー (422)例: リクエスト検証エラー (422) への直接リンク

{
    "title": "検証に失敗しました",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "PartnerIdNotIncluded",
            "message": "rokt-tag-id が欠落している/不正です",
            "value": "0"
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-os-type."
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-package-name."
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-package-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-device-model."
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-sdk-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "ヘッダーが欠落しています: rokt-os-version."
        },
        {
            "code": "ClientUniqueIdIsMissing",
            "message": "ヘッダーが欠落しています: rokt-client-unique-id."
        },
        {
            "code": "PlatformTypeIsInvalid",
            "message": "無効なヘッダーです: rokt-platform-type."
        }
    ]
}

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

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "リクエストボディの形式が無効です"
        }
    ]
}

例: リクエストが多すぎる場合 (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エンドポイントから新しいプレースメントを取得する必要があります。これにより、レンダリングされたオファーが顧客の現在のコンテキストに関連性を保つことが保証されます。

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

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

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

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

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

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

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

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

リクエスト例 (モバイル/デスクトップ Web)リクエスト例 (モバイル/デスクトップ Web) への直接リンク

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

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

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

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

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

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

レスポンスオプションレスポンスオプション への直接リンク

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

広告主 (Advertiser)広告主 (Advertiser) への直接リンク

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

例例 への直接リンク

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

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

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

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

例: リクエスト検証エラー (422)例: リクエスト検証エラー (422) への直接リンク

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

レスポンスオプションレスポンスオプションへの直接リンク

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

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

例例への直接リンク

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

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

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

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