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

サーバーイベントAPI仕様書

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

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

エンドポイントエンドポイント への直接リンク

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

テストのベストプラクティステストのベストプラクティス への直接リンク

テストエンドポイント https://server-api-demo.rokt.com/v1/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-idRoktタグIDstring1234567890

ルート/ボディルート/ボディ への直接リンク

プロパティ名必須データタイプ説明
eventsはいPartnerEvent[]Roktに送信されるイベントのコレクション

PartnerEventPartnerEvent への直接リンク

プロパティ名必須データタイプ説明
eventTypeはいstring公開されるイベントの名前。イベントタイプセクションのEventTypeと一致します。
eventTimeはいstringイベントが作成された時間をDateTimeOffset（GMT+0のISO文字列）として表します。
例: 2022-04-20T00:11:47.529Z
sessionIdはいstringイベントが関連付けられているセッションのID。/v1/partner/offersエンドポイントのOffers APIのレスポンスから取得されます。
parentGuidはいstringリンクされた親のインスタンスGUID。/v1/partner/offersエンドポイントのOffers APIのレスポンスから取得されます。
clientUniqueIdはいstringトラブルシューティングのためにRoktセッションとパートナーセッションをリンクする識別子:
<Transaction ID>
metadata任意NameValuePair[]イベントに関連する追加メタデータのコレクション

NameValuePairNameValuePair への直接リンク

プロパティ名必須データ型説明
Nameはいstring提供されるプロパティの名前/識別子
Valueはいstring提供された名前に関連するデータ
注記
  • イベント instanceGuid の作成はRokt APIによって処理されます
  • 共通メタデータはRokt APIによって追加されます
  • エンドポイントは一度に最大25のイベントのみ処理を許可します
  • 同じリクエストに属するすべてのイベントは同じセッション識別子を共有する必要があります: sessionId
  • 各イベントのEventTimeは以下でなければなりません:
    • 将来の日付でないこと（5分の余裕あり）
    • 過去3日を超えないこと

イベントタイプイベントタイプ への直接リンク

イベントタイプ説明
SignalImpression配置、スロット、またはクリエイティブがレンダリングされ、顧客に見えるときに発生します。表示の遅延がある場合は、ビューが非表示から表示されるときに発生します。これはOne Platformダッシュボードの配置インプレッションメトリックに関連しています。
各placementGuid/slotGuid/creativeGuidに必要です。
SignalViewed配置がビューポートで少なくとも1秒間連続して50%以上表示されるときに発生します。これはインタラクティブ広告局（IAB）によって設定されたビューアビリティの定義に一致し、非人間（ボット）トラフィック、不正なインプレッション、または無効な活動のいかなる形態も除外する必要があります。
各creativeGuidに必要です。
SignalResponse消費者がクリエイティブの応答オプションに関与したときに発生します。
各responseOptionGuidに必要です。
注記

parentGuidフィールドで使用するslotGuid、creativeGuid、placementGuid、およびresponseOptionGuidはOffers APIレスポンスで見つけることができます。

リクエスト例リクエスト例 への直接リンク

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

{
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394", // This should be a slotGuid, creativeGuid, or placementGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalViewed",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd", // This should be a creativeGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863", // This should be a responseOptionGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}'

レスポンスレスポンス への直接リンク

成功レスポンス (200)成功レスポンス (200) への直接リンク

ルート/ボディルート/ボディ への直接リンク

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

UnprocessedEventUnprocessedEvent への直接リンク

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

例例 への直接リンク

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

部分的な成功応答 (207)部分的な成功応答 (207) への直接リンク

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

{
    "processedEventsCount": 5,
    "unprocessedEvents": [
        {
            "errors": [
                {
                    "code": "InvalidEventType",
                    "message": "Event type is invalid"
                },
                {
                    "code": "SessionIdMissing",
                    "message": "SessionId is missing or invalid"
                },
                {
                    "code": "ParentGuidIsMissing",
                    "message": "ParentGuid is null or empty"
                },
                {
                    "code": "EventTimeIsMissing",
                    "message": "EventTime is null or default"
                }
            ],
            "event": {
                "eventType": "Unknown",
                "sessionId": "",
                "eventTime": "0001-01-01T00:00:00+00:00",
                "parentGuid": "",
                "clientUniqueId": "265d3a90-4c84-4c17-99af-e09b862b925c"
            }
        }
    ],
    "success": false
}

リクエストエラー応答 (4XX)リクエストエラー応答 (4XX) への直接リンク

ルート/ボディルート/ボディ への直接リンク

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

バリデーションエラーバリデーションエラー への直接リンク

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

空のイベントリクエスト空のイベントリクエスト への直接リンク

{
    "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"
        }
    ]
}

エラーエラー への直接リンク

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

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

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

この記事は役に立ちましたか？
Last updated Aug 4, 2026