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

V2 パートナーイベント API 仕様

このドキュメントは、Rokt の API と対話して イベント を Rokt に送信するために必要なエンドポイントを概説します。

エンドポイント​

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

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

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

リクエスト​

認証ヘッダー​

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

ヘッダーキー必須説明型注釈
rokt-pub-idはい提供されたクライアントの公開IDを含む文字列これはRoktから提供されます。
rokt-secretはい提供されたクライアントの公開シークレットで、公開IDと一致する必要があります文字列これはRoktから提供されます。

必要なヘッダー​

ヘッダーキー必須説明型例
content-typeはいメディアタイプ文字列“application/json”
acceptはい応答の期待されるメディアタイプ文字列“application/json”
rokt-tag-idはいRoktタグID文字列1234567890

ルート/ボディ​

プロパティ名必須データ型説明
イベントはいPartnerEvent[]Roktに送信されるイベントのコレクション
統合はいIntegrationリクエストを行っている統合に関するデータ。このデータは、Android、iOS、ウェブ用のUXHelperライブラリから取得できます

統合​

プロパティ名必須データ型説明
名前はいstringリクエストを行っている統合の一般名を示します
バージョンはいstringリクエストを行っている統合のバージョン
フレームワークはいstring使用されている統合フレームワーク (例: Flutter、React Native)
プラットフォームはいstring/enumオファーをリクエストしているパートナー プラットフォーム (例: Web、Mobile、iOS)
レイアウトスキーマバージョンはいstring統合のための最も互換性のあるスキーマバージョン
デバイスロケールはいstringユーザーのデバイスからのロケール設定
デバイスモデルはいstringiOSのデバイスモデルまたはAndroidのビルドモデル
デバイスタイプはいstringデバイス/フォームファクターのタイプ (例: Phone、Tablet)
オペレーティングシステムはいstringユーザーのデバイスのオペレーティングシステム
オペレーティングシステムバージョンはいstringユーザーのデバイスのOSバージョン
パッケージ名はいstringホストアプリケーションのパッケージ名またはバンドル識別子
PackageVersionYesstringホストアプリケーションのパッケージバージョンまたはバンドルバージョン
MetadataNoMap<string, string>統合またはデバイスに関連する追加データ

PartnerEvent​

プロパティ名必須データタイプ説明
EventTypeYesstring公表されるイベントの名前。イベントタイプセクションのeventTypeに一致します。
EventTimeYesstringイベントが作成された時刻はDateTimeOffset（GMT+0のISO文字列）として。例：2022-04-20T00:11:47.529Z
SessionIdYesstringイベントに関連付けられたセッションのID。/experiencesのレスポンスから取得します。SuccessBodyを参照してください。
ParentGuidYesstringリンクされた親のインスタンスGUID。このフィールドのソースは、イベントタイプ - 親GUIDソースを参照してください。
PageInstanceGuidYesstringオファーが取得されたページ/ビューのユニーク識別子。/experiencesのレスポンスから取得します。PageContextを参照してください。
ClientUniqueIdNostringトラブルシューティングのためにRoktセッションとパートナーセッションをリンクする識別子（例：UberセッションID）。
EventDataNostringイベントに必要な追加データ。
メタデータいいえNameValuePair[]イベントに関連する追加のメタデータのコレクション。

NameValuePair​

プロパティ名必須データ型説明
名前はいstring提供されるプロパティの名前/識別子
値はいstring提供される名前に関連するデータ
注記
  • エンドポイントは同時に処理できるイベントの最大数は25です
  • 同じリクエストに属するすべてのイベントは、同じセッション識別子を共有する必要があります: sessionId
  • 各イベントのEventTimeは:
    • 将来の日付は不可（5分の猶予あり）
    • 過去3日を超えてはいけない

イベントタイプ​

イベントタイプ説明
SignalImpressionレイアウト、スロット、またはクリエイティブがレンダリングされ、顧客に見えるときに発生します。表示の遅延が関与する場合、表示が解除されたときに発生します。これはOne Platformダッシュボードのレイアウトインプレッションメトリックに相当します。
SignalViewedレイアウトがビューポートで少なくとも1秒間50%以上見えるときに発生します。
SignalResponse消費者がクリエイティブの応答オプションに関与する際に発生します。
SignalGatedResponse消費者がクリエイティブの「後でリマインド」応答オプションに関与する際に発生します。
SignalInitializeライブラリがレイアウトの表示を試みるときに発生します。
SignalDismissal顧客がレイアウトを閉じるか、または解消するときにトリガーされます。
SignalActivation顧客がレイアウトと対話するときにトリガーされます。
SignalSdkDiagnosticRoktレイアウト内またはレンダリングプロセス中にエラーが発生したときにトリガーされます。パートナーはこのイベントをリッスンして例外を処理することができます。

リクエスト例​

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

展開するにはここをクリック
{
    "integration": { ... 標準の統合ペイロード ... },
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.710Z",
            "parentGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2"
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f"
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}

レスポンス​

成功レスポンス (200)​

ルート/ボディ​

プロパティ名データ型説明
successbooleanRokt にイベントが正常に受信されたかどうかを示す
processedEventsCountnumber/intRokt に正常に受け入れられたイベントの数を示す
unprocessedEventsUnprocessedEvent[]エラーの説明付きで受け入れられなかったイベントのコレクション

UnprocessedEvent​

プロパティ名データ型説明
eventPartnerEventRokt にイベントが正常に受信されたかどうかを示す
errorsError[]Rokt に正常に受け入れられたイベントの数を示す

例​

{
    "processedEventsCount": 5,
    "unprocessedEvents": [],
    "success": true }

部分成功レスポンス (207)​

無効なイベントと共に有効なイベントが送信された場合、Roktは依然として有効なイベントを処理しようとし、受け入れられた数を示し、処理されなかったイベントを提供する混合レスポンス（HTTP 207）ステータスを返します。

クリックして展開
{
    "processedEventsCount": 5,
    "unprocessedEvents": [
        {
            "errors": [
                {
                    "code": "InvalidEventType",
                    "message": "イベントタイプが無効です"
                },
                {
                    "code": "SessionIdMissing",
                    "message": "SessionIdが欠落または無効です"
                },
                {
                    "code": "ParentGuidIsMissing",
                    "message": "ParentGuidがnullまたは空です"
                },
                {
                    "code": "EventTimeIsMissing",
                    "message": "EventTimeがnullまたはデフォルトです"
                }
            ],
            "event": {
                "eventType": "Unknown",
                "sessionId": "",
                "eventTime": "0001-01-01T00:00:00+00:00",
                "parentGuid": "",
                "clientUniqueId": "265d3a90-4c84-4c17-99af-e09b862b925c"
            }
        }
    ],
    "success": false
}

リクエストエラー応答 (4XX)​

ルート/ボディ​

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

検証エラー​

{
    "title": "検証に失敗しました",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "TooManyEvents",
            "message": "提供されたイベントの数が制限 25 を超えています"
        },
        {
            "code": "IntegrationNotProvided",
            "message": "統合が必要です"
        }
    ]
}

空のイベントリクエスト​

{
    "title": "バリデーションに失敗しました",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "NoEventsProvided",
            "message": "イベントはnullまたは空であってはいけません"
        }
    ]
}

空のボディリクエスト​

{
    "title": "不正なリクエスト",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "リクエストボディのフォーマットが無効です"
        }
    ]
}

エラー​

プロパティ名データ型説明
codestring対応するエラーコード
messagestringエラーを説明するメッセージ

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

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

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