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

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)成功レスポンス (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に提供されるランタイム構成のコレクション

SdkOptionsSdkOptions への直接リンク

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

PageContextPageContext への直接リンク

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

LayoutPluginLayoutPlugin への直接リンク

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

PluginPlugin への直接リンク

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

PluginConfigPluginConfig への直接リンク

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

SlotSlot への直接リンク

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

LayoutVariantLayoutVariant への直接リンク

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

OfferOffer への直接リンク

プロパティ名型説明
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)リクエストエラーレスポンス (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レスポンスコード: 422httpレスポンスコード-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 レスポンスコード: 400HTTP レスポンスコード: 400 への直接リンク

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

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

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

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

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

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

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

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

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