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

V2 パートナーエクスペリエンス API

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

エンドポイント​

環境アクション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、およびウェブ用のUXHelperライブラリから取得できます

統合​

プロパティ名必須データ型説明
nameはいstringリクエストを行う統合の一般的な名前を示します
versionはいstringリクエストを行う統合のバージョン
frameworkはいstring使用されている統合フレームワーク (例: Flutter, React Native)
platformはいstring/enumオファーを要求するパートナープラットフォーム (例: Web, Mobile, iOS)
layoutSchemaVersionはいstring統合に対応する最大のスキーマバージョン
deviceLocaleはいstringユーザーのデバイスからのロケール設定
deviceModelはいstringiOSのデバイスモデルまたはAndroidのビルドモデル
deviceTypeはいstringデバイスタイプ/フォームファクター (例: Phone, Tablet)
operatingSystemはいstringユーザーのデバイスのオペレーティングシステム
operatingSystemVersionはいstringユーザーのデバイスのOSバージョン
packageNameはいstringホストアプリケーションのパッケージ名またはバンドル識別子
packageVersionはいstringホストアプリケーションのパッケージバージョンまたはバンドルバージョン
metadataいいえ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)​

ヘッダー​

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

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

成功本文​

ルート​

プロパティ名タイプ説明
PageContextPageContext検出されたページに関連するデータ
PluginsLayout[]プラグインオブジェクトとフォント
SessionIdstringRoktセッションID。ウェブの場合、このセッション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プラグインの設定

プラグイン​

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

プラグイン設定​

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

スロット​

プロパティ名型説明
InstanceGuidstringスロットの特定のインスタンスを表すGUID
LayoutVariantLayoutVariantスロット/オファーに使用するレイアウトバリアントの定義
OfferOfferお客様に表示するために使用するオファーの定義
Tokenstringプラグイン/レイアウトレベルのデータ整合性JWT

レイアウトバリアント​

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

オファー​

プロパティ名タイプ説明
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>"
                                    },

                                    "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. ウィジェットテスト用",

                                    "brand": "000. ウィジェットテスト用"

                                },

                                "copy": {

                                    "creative.copy": "Nicholas Grasevski 2",

                                    "creative.termsAndConditions.message": "T&Csについては [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に送信しました。",
                                    }
                                },
                                "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": "検証に失敗しました",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "IntegrationNameNotProvided",
            "message": "Integration.Name は必須です"
        },
        {
            "code": "IntegrationVersionNotProvided",
            "message": "Integration.Version は必須です"
        },
        {
            "code": "IntegrationFrameworkNotProvided",
            "message": "Integration.Framework は必須です"
        },
        {
            "code": "IntegrationPlatformInvalid",
            "message": "Integration.Platform が無効です"
        },
        {
            "code": "IntegrationLayoutSchemaVersionNotProvided",
            "message": "Integration.LayoutSchemaVersion は必須です"
        },
        {
            "code": "IntegrationDeviceLocaleNotProvided",
            "message": "Integration.DeviceLocale は必須です"
        },
        {
            "code": "IntegrationDeviceModelNotProvided",
            "message": "Integration.DeviceModel は必須です"
        },
        {
            "code": "IntegrationDeviceTypeNotProvided",
            "message": "Integration.DeviceType は必須です"
        },
        {
            "code": "IntegrationOperatingSystemNotProvided",
            "message": "Integration.OperatingSystem は必須です"
        },
        {
            "code": "IntegrationOperatingSystemVersionNotProvided",
            "message": "Integration.OperatingSystemVersion は必須です"
        },
        {
            "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エンドポイントから新しい体験を取得する必要があります。これにより、レンダリングされたオファーが顧客の現在のコンテキストに関連したものとして保たれます。

この記事は役に立ちましたか？