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

V2 Partner Experiences API

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

エンドポイント​

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

テストのベストプラクティス​

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

リクエスト​

認証ヘッダー​

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

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

必須ヘッダー​

Header-key必須説明タイプ例
content-typeはいメディアタイプstring“application/json”
acceptはいレスポンスの期待メディアタイプstring“application/json”
rokt-tag-idはいRoktタグIDstring1234567890

本文​

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

統合​

プロパティ名必須データ型説明
nameYesstringリクエストを行う統合の一般名を示します
versionYesstringリクエストを行う統合のバージョン
frameworkYesstring使用されている統合フレームワーク（例: Flutter, React Native）
platformYesstring/enumオファーを要求するパートナープラットフォーム（例: Web, Mobile, iOS）
layoutSchemaVersionYesstring統合に対して最も互換性のあるスキーマバージョン
deviceLocaleYesstringユーザーのデバイスからのロケール設定
deviceModelYesstringiOSのデバイスモデルまたはAndroidのビルドモデル
deviceTypeYesstringデバイスの種類/フォームファクター（例: Phone, Tablet）
operatingSystemYesstringユーザーのデバイスのオペレーティングシステム
operatingSystemVersionYesstringユーザーのデバイスのOSバージョン
packageNameYesstringホストアプリケーションのパッケージ名またはバンドル識別子
packageVersionYesstringホストアプリケーションのパッケージバージョンまたはバンドルバージョン
metadataNoMap<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)​

ヘッダー​

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

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

成功ボディ​

ルート​

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

SdkOptions​

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

PageContext​

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

LayoutPlugin​

プロパティ名タイプ説明
FontsFont[]SDKがオファーで利用するフォントの配列
PluginPluginプラグインの設定

Plugin​

プロパティ名タイプ説明
ConfigPluginConfigレイアウトをレンダリングするための設定を定義
IdstringレイアウトID / トランザクションレイアウト外部ID
Namestringレンダリングに使用されるプラグインの名前
TargetElementPositionstringtargetElementSelectorに基づく位置配置のアクション
TargetElementRelationstring配置とtargetElementSelectorの関係
TargetElementSelectorstringページ内にレイアウトを配置する位置を識別
TargetSectionstringさまざまなターゲティングタイプを識別、例: サンキューページ
UrlstringプラグインをダウンロードするためのURL

PluginConfig​

プロパティ名型説明
InstanceGuidstringプラグイン/レイアウトの特定のインスタンスを表すGUID
LayoutSchemaVersionstringレイアウトに使用されるレイアウトスキーマのバージョン
OuterLayoutSchemastringOuter LayoutのUIを定義するJSONスキーマ
SlotsSlot []オファースロットのコレクション
Tokenstringプラグイン/レイアウトレベルのデータ整合性JWT

Slot​

プロパティ名型説明
InstanceGuidstringSlotの特定のインスタンスを表すGUID
LayoutVariantLayoutVariantSlot/Offerに使用されるLayoutVariantの定義
OfferOffer顧客に表示するために使用されるOfferの定義
Tokenstringプラグイン/レイアウトレベルのデータ整合性JWT

LayoutVariant​

プロパティ名型説明
LayoutVariantIdstring自動生成されたID
ModuleNamestringレイアウトモジュール名
FormatTypestringオファーを表示するフォーマットタイプ
LayoutVariantSchemastringバリアントを活用してオファーをレンダリングするUIを定義するJSONスキーマ

Offer​

プロパティ名型説明
AccountIdlongオファーに関連付けられたRoktアカウントID
CampaignIdstringOPでリンクされたキャンペーンのID
CreativeCreativeOPで定義されたオファークリエイティブ
Metadatastringオファーに関連するメタデータを含む

クリエイティブ​

プロパティ名タイプ説明
ReferralCreativeIdstringクリエイティブ設定に関連付けられたID
InstanceGuidstringクリエイティブの特定のインスタンスを表すGUID
CopyMap<string, string>オファーコンテンツに関連するテキストを含む
ResponseOptionsMapMap<string, ResponseOption>CTAボタンの設定
LinksMap<string, Link>レイアウトスキーマによって参照されるオファーの利用可能なリンク
ImagesMap<string, Image>レイアウトスキーマによって参照されるオファーの利用可能な画像
IconsMap<string, Icon>レイアウトスキーマによって参照されるオファーの利用可能なアイコン
Tokenstringクリエイティブレベルのデータ整合性JWT

フォント​

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

レスポンスオプション​

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

リクエストエラーレスポンス (HTTP 4xx)​

ルート/ボディ​

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

エラー​

プロパティ名型説明
codestring対応するエラーコード
messagestringエラーを説明するメッセージ
valueboolean無効だった提供値があればそれを示します

成功レスポンスボディ​

成功レスポンス​

クリックして展開
{
    "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>"
```json
                                        },
                                        "negative": {
                                            "id": "2760914349384466796",
                                            "action": "CaptureOnly",
                                            "instanceGuid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "結構です",
                                            "longLabel": "結構です",
                                            "isPositive": false,
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        }
                                    },
                                    "links": {
                                        "termsAndConditions": {
                                            "url": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797",
                                            "title": "利用規約"
                                        }
                                    },
                                    "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": "T&Cについては[rokt.com](https://www.rokt.com)をご覧ください",
                                        "creative.termsAndConditions.close.copy": "閉じる",
                                        "creative.termsAndConditions.title": "利用規約",
                                        "creative.tag": "B2Bサービス",
                                        "creative.success.title": "成功",
                                        "creative.success.copy": "確認メールをtest1593754986316@rokt.comに送信しました。",

``````json
                                        "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レスポンスコード: 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 が必要です"
        },
        {
            "code": "IntegrationPackageVersionNotProvided",
            "message": "Integration.PackageVersion が必要です"
        },
        {
            "code": "PageIdentifierNotProvided",
            "message": "PageIdentifier が必要です"
        },
        {
            "code": "PartnerIdNotProvided",
            "message": "rokt-tag-id が不足しているか/間違っています"
        }
    ]
}

HTTP レスポンスコード: 400​

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

内部サーバーエラー (HTTP 5xx)​

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

オファーのキャッシュ​

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

パフォーマンスを向上させるために、ユーザーのトランザクションの流れの中で、Roktの/v2/partner/experiences APIエンドポイントからオファーコンテンツを早めに取得することをお勧めします。オファーがレンダリングされる前に、トランザクションを完了することにユーザーが大きな興味を示した後にオファーコンテンツの取得を開始するのがベストプラクティスです。これにより、不必要なネットワーク呼び出しを避けることができます。

データを受け取ったら、それをキャッシュに保存できます。これにより、同じトランザクション内でクライアントが後で迅速に取得できるようになります。

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

この記事は役に立ちましたか？
Last updated Oct 29, 2025