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

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

エンドポイント

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

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

テストエンドポイント https://server-api-demo.rokt.com/v2/partner/events は、テスト専用に設計されており、本番データやパフォーマンスに影響を与えることなく統合を検証するために使用する必要があります。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

Root/Body

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

Integration

プロパティ名	必須	データ型	説明
Name	はい	string	リクエストを行う統合の一般名を示します
Version	はい	string	リクエストを行う統合のバージョン
Framework	はい	string	使用されている統合フレームワーク（例: Flutter, React Native）
Platform	はい	string/enum	オファーをリクエストするパートナープラットフォーム（例: Web, Mobile, iOS）
LayoutSchemaVersion	はい	string	統合のための最高互換スキーマバージョン
DeviceLocale	はい	string	ユーザーのデバイスからのロケール設定
DeviceModel	はい	string	iOSのデバイスモデルまたはAndroidのビルドモデル
DeviceType	はい	string	デバイス/フォームファクタのタイプ（例: Phone, Tablet）
OperatingSystem	はい	string	ユーザーのデバイスのオペレーティングシステム
OperatingSystemVersion	はい	string	ユーザーのデバイスのOSバージョン
PackageName	はい	string	ホストアプリケーションのパッケージ名またはバンドル識別子
PackageVersion	Yes	string	ホストアプリケーションのパッケージバージョンまたはバンドルバージョン
Metadata	No	Map<string, string>	インテグレーションまたはデバイスに関連する追加データ

PartnerEvent

Property Name	Required	DataType	Description
EventType	Yes	string	発行されるイベントの名前。Event Types セクションの eventType に一致します。
EventTime	Yes	string	イベントが作成された時間を `DateTimeOffset` (GMT+0 の ISO 文字列) で表します。例: 2022-04-20T00:11:47.529Z
SessionId	Yes	string	イベントに関連付けられたセッションの ID。`/experiences` レスポンスから取得されます。SuccessBody を参照してください。
ParentGuid	Yes	string	リンクされた親のインスタンス GUID。このフィールドのソースについては Event Types - Parent GUID Source を参照してください。
PageInstanceGuid	Yes	string	オファーが取得されたページ/ビューの一意の識別子。`/experiences` レスポンスから取得されます。PageContext を参照してください。
ClientUniqueId	No	string	Rokt セッションとパートナーセッションをトラブルシューティングのためにリンクするための識別子 (例: Uber Session ID)。
EventData	No	string	イベントに必要な追加データ。
メタデータ	必須	NameValuePair[]	イベントに関連する追加のメタデータのコレクション。

NameValuePair

プロパティ名	必須	データ型	説明
Name	はい	string	提供されるプロパティの名前/識別子
Value	はい	string	提供された名前に関連するデータ

注記

エンドポイントは一度に最大25のイベントしか処理できません
同じリクエストに属するすべてのイベントは同じセッション識別子 sessionId を共有する必要があります
各イベントのEventTimeは以下の条件を満たす必要があります:
- 未来の日付でないこと（5分の猶予あり）
- 過去3日以上前でないこと

イベントタイプ

イベントタイプ	説明
SignalImpression	レイアウト、スロット、またはクリエイティブがレンダリングされ、顧客に表示されるたびに発生します。表示の遅延がある場合は、ビューが表示される際に発生します。これはOne Platformダッシュボードのレイアウトインプレッションメトリクスに関連しています。
SignalViewed	レイアウトがビューポート内で50%以上可視で、少なくとも1秒間表示されているときに発生します。
SignalResponse	消費者がクリエイティブの応答オプションにエンゲージしたときに発生します。
SignalGatedResponse	消費者がクリエイティブの「後で通知する」応答オプションにエンゲージしたときに発生します。
SignalInitialize	ライブラリがレイアウトを表示しようとする際に発生します
SignalDismissal	顧客がレイアウトを閉じるか却下したときにトリガーされます。
SignalActivation	顧客がレイアウトと対話したときにトリガーされます。
SignalSdkDiagnostic	Roktレイアウト内またはレンダリングプロセス中にエラーが発生したときにトリガーされます。パートナーはこのイベントをリッスンして例外を処理できます。

リクエスト例

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)

ルート/ボディ

プロパティ名	データ型	説明
success	boolean	イベントがRoktによって正常に受信されたかどうかを示します
processedEventsCount	number/int	Roktによって正常に受け入れられたイベントの数を示します
unprocessedEvents	UnprocessedEvent[]	受け入れられなかったイベントのコレクションと、各イベントごとのエラー説明を含みます

UnprocessedEvent

プロパティ名	データ型	説明
event	PartnerEvent	イベントがRoktによって正常に受信されたかどうかを示します
errors	Error[]	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)

ルート/ボディ

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

バリデーションエラー

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "TooManyEvents",
            "message": "The number of events provided exceeds the limit 25"
        },
        {
            "code": "IntegrationNotProvided",
            "message": "Integration is required"
        }
    ]
}

空のイベントリクエスト

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "NoEventsProvided",
            "message": "Events cannot be null or empty"
        }
    ]
}

空のボディリクエスト

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

エラー

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

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

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

エンドポイント​

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

リクエスト​

認証ヘッダー​

必須ヘッダー​

Root/Body​

Integration​

PartnerEvent​

NameValuePair​

イベントタイプ​

リクエスト例​

レスポンス​

成功レスポンス (200)​

ルート/ボディ​

UnprocessedEvent​

例​

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

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

ルート/ボディ​

バリデーションエラー​

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

空のボディリクエスト​

エラー​

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

エンドポイント

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

リクエスト

認証ヘッダー

必須ヘッダー

Root/Body

Integration

PartnerEvent

NameValuePair

イベントタイプ

リクエスト例

レスポンス

成功レスポンス (200)

ルート/ボディ

UnprocessedEvent

例

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

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

ルート/ボディ

バリデーションエラー

空のイベントリクエスト

空のボディリクエスト

エラー

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