V2 Partner Experiences API

このドキュメントは、RoktのAPIと連携してRoktからエクスペリエンスコンテンツを取得するために必要な関連エンドポイントを概説しています。このエンドポイントは、オファー駆動型のエクスペリエンスを直接パートナーに提供するように設計されています。リクエストはこのエンドポイントに送信され、レスポンスは適切に処理されるようにUXヘルパーライブラリに渡されます。

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

環境	アクション	URL
本番環境	`POST`	`https://server-api.rokt.com/v2/partner/experiences`
テスト環境	`POST`	`https://server-api-demo.rokt.com/v2/partner/experiences`

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

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

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

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

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

ヘッダーキー	必須	説明	タイプ	備考
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

BodyBody への直接リンク

プロパティ名	必須	データタイプ	説明
sessionId	No	string	既存のRoktセッションのセッションIDが存在する場合
pageIdentifier	Yes	string	ビューを区別するために使用されるテキスト
attributes	Yes	Map<string, string>	オファー選択時に使用されるユーザー属性データを保持
integration	Yes	Integration	リクエストを行う統合に関連するデータ。これはAndroid、iOS、Web用のUXHelperライブラリから取得可能

IntegrationIntegration への直接リンク

プロパティ名	必須	データタイプ	説明
name	Yes	string	リクエストを行う統合の共通名を示す
version	Yes	string	リクエストを行う統合のバージョン
framework	Yes	string	使用されている統合フレームワーク（例：Flutter、React Native）
platform	Yes	string/enum	オファーを要求するパートナープラットフォーム（例：Web、Mobile、iOS）
layoutSchemaVersion	Yes	string	統合のための最高互換スキーマバージョン
deviceLocale	Yes	string	ユーザーのデバイスからのロケール設定
deviceModel	Yes	string	iOSのデバイスモデルまたはAndroidのビルドモデル
deviceType	Yes	string	デバイス/フォームファクターの種類（例：Phone、Tablet）
operatingSystem	Yes	string	ユーザーのデバイスのオペレーティングシステム
operatingSystemVersion	Yes	string	ユーザーのデバイスのOSバージョン
packageName	Yes	string	ホストアプリケーションのパッケージ名またはバンドル識別子
packageVersion	Yes	string	ホストアプリケーションのパッケージバージョンまたはバンドルバージョン
metadata	No	Map<string, string>	統合またはデバイスに関連する追加データ

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

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

クリックして展開

{
    "attributes": {
        "email": "test@rokt.com",
        "locale": "en-AU"
    },
    "pageIdentifier": "your_page_identifier",
    "integration": {
        "name": "UX Helper iOS",
        "version": "1.0",
        "framework": "Swift",
        "platform": "iOS",
        "layoutSchemaVersion": "2.1.0",
        "packageVersion": "1.0.0",
        "packageName": "com.partner",
        "operatingSystem": "iOS",
        "operatingSystemVersion": "18",
        "deviceType": "Phone",
        "deviceModel": "iPhone",
        "metadata": {
          "IsCharging": "true"
        }
    },
}

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

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

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

これらのヘッダーは他のEcommerce APIとの一貫性のために返されますが、パートナーやUXライブラリがそれらを使用することは期待されていません。

ヘッダーキー	説明
rokt-account-id	提供されたオファーのアカウントID
rokt-session-id	関連するRoktセッションID
etag	ユーザーのRokt etag値

成功ボディ成功ボディへの直接リンク

ルートルートへの直接リンク

プロパティ名	型	説明
PageContext	PageContext	検出されたページに関連するデータ
Plugins	Layout[]	プラグインオブジェクトとフォント
SessionId	string	RoktセッションID。Webの場合、このセッションIDはヘッダーから取得されます
Success	bool	リクエストが成功したか無効であったかを示します
Token	string	セッションレベルのデータ整合性JWT
Options	SdkOptions	Rokt SDKに提供されるランタイム構成のコレクション

SdkOptionsSdkOptions への直接リンク

プロパティ名	型	説明
UseDiagnosticEvents	bool	Rokt SDKが診断を出力するかどうかを示します

PageContextPageContext への直接リンク

プロパティ名	型	説明
IsPageDetected	bool	リクエストがパートナーページに一致したかどうかを示します
PageId	string	一致したOPページ構成を表すGUID
PageInstanceGuid	string	選択されたページの特定のインスタンスを表すGUID
PageVariantName	string	選択されたページバリアントの名前
PartnerContentTemplate	string	支払い体験に使用されるテンプレート
RoktTagId	string	パートナー/広告主のタグID
Token	string	ページレベルのデータ整合性JWT

LayoutPluginLayoutPlugin への直接リンク

Property Name	Type	Description
Fonts	Font[]	SDKによってオファーで活用されるフォントの配列
Plugin	Plugin	プラグインの設定

PluginPlugin への直接リンク

Property Name	Type	Description
Config	PluginConfig	レイアウトをレンダリングするための設定を定義
Id	string	レイアウトID / トランザクションレイアウト外部ID
Name	string	レンダリングに使用されるプラグインの名前
TargetElementPosition	string	targetElementSelectorに基づく位置配置のアクション
TargetElementRelation	string	配置とtargetElementSelectorの関係
TargetElementSelector	string	ページ内にレイアウトを配置する位置を特定
TargetSection	string	さまざまなターゲティングタイプを識別, 例: サンキューページ
Url	string	プラグインをダウンロードするためのURL

PluginConfigPluginConfig への直接リンク

Property Name	Type	Description
InstanceGuid	string	プラグイン/レイアウトの特定のインスタンスを表すGUID
LayoutSchemaVersion	string	レイアウトに使用されるレイアウトスキーマのバージョン
OuterLayoutSchema	string	外部レイアウトのUIを定義するJSONスキーマ
Slots	Slot []	オファースロットのコレクション
Token	string	プラグイン/レイアウトレベルのデータ整合性JWT

SlotSlot への直接リンク

Property Name	Type	Description
InstanceGuid	string	Slotの特定のインスタンスを表すGUID
LayoutVariant	LayoutVariant	Slot / Offerに使用されるLayoutVariantの定義
Offer	Offer	顧客に表示されるOfferの定義
Token	string	プラグイン / レイアウトレベルのデータ整合性JWT

LayoutVariantLayoutVariant への直接リンク

Property Name	Type	Description
LayoutVariantId	string	自動生成されたID
ModuleName	string	レイアウトモジュール名
FormatType	string	オファーを表示するフォーマットタイプ
LayoutVariantSchema	string	バリアントを活用するオファーをレンダリングするためのUIを定義するJSONスキーマ

OfferOffer への直接リンク

Property Name	Type	Description
AccountId	long	オファーに関連付けられたRoktアカウントID
CampaignId	string	OPでリンクされたキャンペーンのID
Creative	Creative	OPで定義されたオファークリエイティブ
Metadata	string	オファーに関連するメタデータを含む

CreativeCreative への直接リンク

Property Name	Type	Description
ReferralCreativeId	string	クリエイティブ構成に関連付けられたID
InstanceGuid	string	クリエイティブの特定のインスタンスを表すGUID
Copy	Map<string, string>	オファーコンテンツに関連するテキストを含む
ResponseOptionsMap	Map<string, ResponseOption>	CTAボタンの構成
Links	Map<string, Link>	レイアウトスキーマで参照されるオファーの利用可能なリンク
Images	Map<string, Image>	レイアウトスキーマで参照されるオファーの利用可能な画像
Icons	Map<string, Icon>	レイアウトスキーマで参照されるオファーの利用可能なアイコン
Token	string	クリエイティブレベルのデータ整合性JWT

フォントフォントへの直接リンク

プロパティ名	データ型	説明
FontFamily	string	フォントファミリーを指定します（例: Arial, Helvetica）。
FontStyle	string	フォントスタイルを指定します（例: normal, italic）。
FontWeight	string	フォントの太さを指定します（例: normal, bold）。
Src	string[]	フォントファイルのソースURLまたはパスの配列です。

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

プロパティ名	データ型	説明
action	string	レスポンスのアクション
responseOptionGuid	string	レスポンスオプションに固有であり、イベントコールの一部として送信されるGUID
signalType	string	インタラクション時にイベントを送信する際に使用するEventType。これはほとんど常に`SignalResponse`です。
label	string	ボタン/リンクに表示されるラベル
successText	string	インタラクション時に表示されるテキスト（パイロットには関連しません）
isPositive	boolean	レスポンスがポジティブまたはネガティブなエンゲージメントであるかを示します
url	string	アクションを実行するURL

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

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

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

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

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

成功レスポンスボディ成功レスポンスボディへの直接リンク

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

クリックして展開

{
    "sessionId": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
    "pageContext": {
        "pageInstanceGuid": "b1fb003c-e905-4375-91bd-242e74b12277",
        "pageId": "6b1214f0-43e1-447d-b0bb-cf493d361411",
        "language": "en",
        "isPageDetected": true,
        "pageVariantName": "iOSVaraint1",
        "token": "<JWT token placeholder>"
    },
    "plugins": [
        {
            "plugin": {
                "id": "3353172846080032866",
                "name": "dcui",
                "url": "https://wsdk.rokt.com/plugins/dcui/index.html",
                "targetElementSelector": "#target_element",
                "targetElementPosition": "append",
                "targetElementRelation": "child",
                "targetSection": "None",
                "config": {
                    "slots": [
                        {
                            "instanceGuid": "8f492d28-83fb-4813-877e-26e752ea9474",
                            "offer": {
                                "campaignId": "2749386944931233793",
                                "accountId": "106",
                                "maxTotalItemsQtyInOffer": 1,
                                "creative": {
                                    "referralCreativeId": "2760914349384466797",
                                    "instanceGuid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                                    "responseOptionsMap": {
                                        "positive": {
                                            "id": "2760914349384466794",
                                            "action": "Url",
                                            "instanceGuid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "Yes",
                                            "longLabel": "Yes",
                                            "shortSuccessLabel": "Email Sent",
                                            "isPositive": true,
                                            "url": "http://example.com",
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        },
                                        "negative": {
                                            "id": "2760914349384466796",
                                            "action": "CaptureOnly",
                                            "instanceGuid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "No thanks",
                                            "longLabel": "No thanks",
                                            "isPositive": false,
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        }
                                    },
                                    "links": {
                                        "termsAndConditions": {
                                            "url": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797",
                                            "title": "Terms & Conditions"
                                        }
                                    },
                                    "images": {},
                                    "icons": {},
                                    "token": "<JWT token placeholder>",
                                    "advertiser": {
                                        "name": "000. For Widget Testing",
                                        "brand": "000. For Widget Testing"
                                    },
                                    "copy": {
                                        "creative.copy": "Nicholas Grasevski 2",
                                        "creative.termsAndConditions.message": "Please visit [rokt.com](https://www.rokt.com)for T&Cs",
                                        "creative.termsAndConditions.close.copy": "Close",
                                        "creative.termsAndConditions.title": "Terms & Conditions",
                                        "creative.tag": "B2B Services",
                                        "creative.success.title": "Success",
                                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com.",
                                        "creative.termsAndConditions.link": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797"
                                    }
                                },
                                "metadata": {}
                            },
                            "layoutVariant": {
                                "layoutVariantId": "3353172846080032865",
                                "moduleName": "standard-marketing",
                                "formatType": "Text",
                                "layoutVariantSchema":"<JSON encoded schema>"
                            },
                            "token": "<JWT token placeholder>"
                        },
                    ],
                    "instanceGuid": "ce5158a9-dc59-4a97-9006-a299901e4587",
                    "outerLayoutSchema": "<JSON encoded schema>",
                    "layoutSchemaVersion": "2.0",
                    "token": "<JWT token placeholder>"
                }
            },
            "fonts": []
        }
    ],
    "options": {
        "useDiagnosticEvents": true
    },
    "success": true
}

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

特定のユーザーに関連するオファーがないという稀なケースがあります。この発生確率は、リクエスト時により多くの属性データを提供することで減少させることができます。この場合、Roktは体験のないペイロードを返します:

{
    "sessionId": "b2170028-cf39-4d23-849d-f1c38be50000",
    "pageContext": {
        "pageInstanceGuid": "b2170028-cf39-4ff4-8e7d-d88eb9e441e6",
        "isPageDetected": true,
        "token": "<JWT token placeholder>"
    },
    "plugins": [],
    "options": {
        "useDiagnosticEvents": false
    },
    "token": "<JWT token placeholder>",
    "success": true,
}

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

HTTPレスポンスコード: 422http-response-code-422 への直接リンク

クリックして展開

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "IntegrationNameNotProvided",
            "message": "Integration.Name is required"
        },
        {
            "code": "IntegrationVersionNotProvided",
            "message": "Integration.Version is required"
        },
        {
            "code": "IntegrationFrameworkNotProvided",
            "message": "Integration.Framework is required"
        },
        {
            "code": "IntegrationPlatformInvalid",
            "message": "Integration.Platform is invalid"
        },
        {
            "code": "IntegrationLayoutSchemaVersionNotProvided",
            "message": "Integration.LayoutSchemaVersion is required"
        },
        {
            "code": "IntegrationDeviceLocaleNotProvided",
            "message": "Integration.DeviceLocale is required"
        },
        {
            "code": "IntegrationDeviceModelNotProvided",
            "message": "Integration.DeviceModel is required"
        },
        {
            "code": "IntegrationDeviceTypeNotProvided",
            "message": "Integration.DeviceType is required"
        },
        {
            "code": "IntegrationOperatingSystemNotProvided",
            "message": "Integration.OperatingSystem is required"
        },
        {
            "code": "IntegrationOperatingSystemVersionNotProvided",
            "message": "Integration.OperatingSystemVersion is required"
        },
        {
            "code": "IntegrationPackageNameNotProvided",
            "message": "Integration.PackageName is required"
        },
        {
            "code": "IntegrationPackageVersionNotProvided",
            "message": "Integration.PackageVersion is required"
        },
        {
            "code": "PageIdentifierNotProvided",
            "message": "PageIdentifier is required"
        },
        {
            "code": "PartnerIdNotProvided",
            "message": "rokt-tag-id is missing/incorrect"
        }
    ]
}

HTTPレスポンスコード: 400HTTPレスポンスコード: 400 への直接リンク

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

内部サーバーエラー (HTTP 5xx)内部サーバーエラー (HTTP 5xx) への直接リンク

稀な状況で、システムが予期せずリクエストを完了できない場合があります。この場合、ボディのないリクエストと、標準のHTTPレスポンスコードに準拠した適切なステータスコードを返します。このレスポンスが発生した場合、短い遅延（1-2秒）の後にリクエストを再試行することをお勧めします。問題が持続するか、頻繁に発生する場合は、問題の特定と修正を支援するためにサポートに連絡してください。

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

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

パフォーマンスを向上させるために、ユーザーのトランザクションジャーニーの早い段階でRoktの/v2/partner/experiences APIエンドポイントからオファーコンテンツを取得することをお勧めします。オファーコンテンツの取得は、ユーザーがトランザクションを完了することに大きな関心を示した後に開始するのが最善のプラクティスです。これにより、不必要なネットワーク呼び出しを避けることができます。

受け取ったデータはキャッシュに保存できます。これにより、同じトランザクション内での使用のためにクライアントによって後で迅速に取得できます。

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

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

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

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

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

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

BodyBody への直接リンク

IntegrationIntegration への直接リンク

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

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

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

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

成功ボディ成功ボディ への直接リンク

ルートルート への直接リンク

SdkOptionsSdkOptions への直接リンク

PageContextPageContext への直接リンク

LayoutPluginLayoutPlugin への直接リンク

PluginPlugin への直接リンク

PluginConfigPluginConfig への直接リンク

SlotSlot への直接リンク

LayoutVariantLayoutVariant への直接リンク

OfferOffer への直接リンク

CreativeCreative への直接リンク

フォントフォント への直接リンク

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

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

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

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

成功レスポンスボディ成功レスポンスボディ への直接リンク

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

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

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

HTTPレスポンスコード: 422http-response-code-422 への直接リンク

HTTPレスポンスコード: 400HTTPレスポンスコード: 400 への直接リンク

内部サーバーエラー (HTTP 5xx)内部サーバーエラー (HTTP 5xx) への直接リンク

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

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

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

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

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

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

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

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

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

成功ボディ成功ボディへの直接リンク

ルートルートへの直接リンク

フォントフォントへの直接リンク

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

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

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

成功レスポンスボディ成功レスポンスボディへの直接リンク

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

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

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

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