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

Event API

概要​

RoktのEvent APIは、購入、アプリのオープン、店舗訪問など、あらゆる種類のクライアントイベントと、それに関連する属性（例：メールアドレス、購入金額、クレジットカードBIN）をサポートできる柔軟で堅牢なインターフェースです。

Rokt Ecommerceのパートナーは、Web SDKと併用してEvent APIを使用することで、配置動作の不整合を検出する異常検出を支援できます。

Rokt Adsのクライアントは、Event APIを使用してRoktとコンバージョンデータを統合し、キャンペーンのパフォーマンスと最適化を向上させることができます。

認証​

コンバージョンイベントを送信したいアカウントのために、公開鍵と秘密鍵のペアを作成するには、Roktのアカウントマネージャーに連絡してください。受け取るキーは以下の通りです：

名前値
Rokt Public Keyrpub-*****-*****
Rokt Secret Keyrsec-*****-*****

APIエンドポイント​

POST Events​

Event APIは、クライアントがRoktプラットフォームと1つ以上のイベントを統合することを可能にします。イベントは通常、コンバージョンやトランザクションイベントを指しますが、使用は柔軟です。

Event APIには2つの主なユースケースがあります：異常検出（パートナー向け）およびコンバージョンレポート（広告主向け）。

POST /v2/events

リクエスト​

ヘッダー​
名前値必須説明
Content-Typeapplication/jsonはいN/A
Charsetutf-8はいN/A
Rokt-Version2020-05-21はいRoktのAPIバージョン。現在の最新バージョンは2020-05-21です。
注意: このヘッダーを空にすると、最新バージョンが適用され、後方互換性がない可能性があります。無効な値は400 bad requestを引き起こします。
AuthorizationBasic base64(rpub-...:rsec-...)はい標準的なベーシック認証ヘッダーで、資格情報の値はrpub-とrsec-をコロンで結合したものをbase64エンコードしたものです。
パラメータ​

リクエストには、イベントと関連する詳細がJSON形式で含まれています。

レベル 1レベル 2レベル 3必須タイプ説明
accountIdはいString; 最大64文字Rokt アカウントID
eventsはいList[EventObject]; 1回の呼び出しで最大100項目インジェストされるイベントのリスト
clientEventIdはいString; 最大36文字イベントを一意に識別するために使用される識別子
eventTypeはいString; 最大128文字イベントの種類
eventTimeはいStringイベントの時間はUTCおよびRFC 3339である必要があります。イベントAPIが受信した時点から18か月以上前または5分以上未来のタイムスタンプを含むイベントがある場合、リクエストは拒否されます。この範囲外のタイムスタンプを持つイベントは処理されません。
metaDataいいえList[metaData]イベントに関する非ビジネスクリティカルな情報を提供
nameはいString; 最大256文字フィールド名; プレフィックス rokt. (大文字小文字を区別しない) はRokt専用です
valueはいString; 最大65536文字フィールド値; バイナリ値はBase64でエンコード
objectDataいいえList[objectData]イベントのコンテキストに関する詳細を含む
nameはいString; 最大256文字プレフィックス rokt. (大文字小文字を区別しない) はRokt専用です
valueはいString; 最大65536文字フィールド値; バイナリ値はBase64でエンコード
標準 objectData フィールド​

以下は、RoktがEvent APIを通じて受け入れる標準の objectData フィールドの一覧です。利用ケースに応じて、いくつかのフィールドは他のフィールドよりも関連性が高くなります。利用ケースに基づいた特定のペイロードサンプルについては、異常検出 または コンバージョンレポート を参照してください。

追加のデータフィールドを追加したい場合や特定のフィールドに異なる名前を使用したい場合は、アカウントマネージャーにお知らせください。

名前説明例
emailプレーンテキストで渡されるメールアドレス、小文字で末尾にスペースがないことjohn@email.com
emailsha256メールアドレスのSHA-256ハッシュ。ハッシュ化前に小文字で末尾にスペースがないこと。fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingidコンバージョンイベントを元のクリックに一致させるために使用されるRokt生成のID。別の統合が必要です。1bc29b36f623ba82aaf6724fd3b16718
amount取引金額（小数点を許可）100.25
currency通貨コードUSD
quantity特定のコンバージョン内のアイテムの数量（整数）4
conversiontype異なるコンバージョンイベントを区別するために使用されます。
注: デフォルトのコンバージョンイベントタイプが提供されている場合にのみ適用されます。		ticketpurchase, seatupgrade, signup
productname購入された製品の名前。複数のアイテムをカンマで区切ることができます。Maroon 5 t-shirt, Warriors vs. Raptors
sku購入された製品の識別子（注: 1つのSKUのみを受け入れます）230847, tshirt-blue-39487, 398fhdnff
paymenttype取引時に使用された支払い方法VISA, American Express
ccbinコンバージョンされた支払いのクレジットカードBIN123456
marginコンバージョンの利益率（絶対値）- 例: $10.12の利益率の場合は10.1210.12
transactionidトランザクションID、ユニークな取引を識別するために使用されます。
ABC789
confirmationref確認参照ID。ユニークな取引を識別したり、注文確認を追跡するために使用される代替識別子。
注: 提供された場合、Roktはこの識別子を使用してコンバージョンイベントを重複排除します。		XYZ123
firstname顧客の名前John
firstnamesha256名前のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをすべてトリムします。fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
lastname顧客の名字Smith
lastnamesha256名字のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをすべてトリムします。fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
mobileコンバージョンされた顧客の携帯電話番号3053211654, +1 (323) 867-5309
mobilesha256携帯電話番号のSHA-256ハッシュ。
注: ハッシュ化する前に、携帯電話番号はこの特定の形式にフォーマットする必要があります: 5551234567（ダッシュやスペースを含まない）。		fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
ipaddress顧客のIPアドレス172.3.51.182
ipaddresssha256IPアドレスのSHA-256ハッシュ。fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
useragentコンバージョンした顧客のブラウザユーザーエージェントMozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
DeviceTypeデバイスタイプDesktop, Mobile, Tablet
osデバイスのオペレーティングシステムiOS
osversionオペレーティングシステムのバージョン8.1
browserブラウザSafari
browserversionブラウザのバージョン11.1
title顧客の称号Mr, Mrs, Ms, Miss
gender顧客の性別M, Male, F, Female
dobフォーマット yyyymmdd19851220
age顧客の年齢33
language購入に関連する言語en, en-US
unitno住所に関連するユニット番号Unit A
address1住所の第一行123 Sesame St
address2住所の第二行（アパート番号、階数など）Alphabet Boulevard
zipcode顧客の郵便番号90210, SW1W 0DT
city顧客の都市San Francisco
state顧客の州CA, California, NY, New York
country顧客の国US, United States, AU, Australia
value顧客の価値19.98
predictedltv顧客の予測生涯価値500.0
サンプル​

これは、2つの予約イベントを含むJSONペイロードを使用したサンプルのEvent API呼び出しです。

POST /v2/events
{
	"accountId": "12345",
	"events": [
		{
			"clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
			"eventType": "booking",
			"eventTime": "2020-05-22T10:21:29.339Z",
			"metaData": [
				{
					"name": "sourceServer",
					"value": "192.0.0.1"
				}
			],
			"objectData": [
				{
					"name": "email",
					"value": "email123@emailserver.com"
				},
				{
					"name": "amount",
					"value": "85.00"
				}
			]
		},
		{
			"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
			"eventType": "booking",
			"eventTime": "2020-05-22T10:21:29.339Z",
			"metaData": [
				{
					"name": "sourceServer",
					"value": "192.0.0.1"
				}
			],
			"objectData": [
				{
					"name": "email",
					"value": "email456@emailserver.com"
				},
				{
					"name": "amount",
					"value": "99.99"
				}
			]
		}
	]
}

レスポンス​

名前説明
X-Rokt-Trace-Idトラブルシューティングのために使用される、リクエストに関連付けられた一意の識別子。
ボディ​

Event APIへの成功した呼び出しは200ステータスを返します。unprocessedRecordsオブジェクトは空であるべきで、これはすべてのイベントが正常に処理されたことを示します。

サンプル​

以下のコードサンプルは、Event APIへの成功した呼び出しを表しています。

{
    "data": {
        "unprocessedRecords": []
    }
}
200レスポンスと潜在的なエラー

200レスポンスを検証する際には、unprocessedRecordsにイベントが返されていないことを確認してください。unprocessedRecordsにレコードがある場合、1つ以上のイベントが正しく処理されていない可能性があります。

レスポンス​

HTTP レスポンスコードエラーコード説明
200N/A通常はOKですが、以下の200エラーシナリオの例を参照してください。
400RequestBodyReadErrorリクエストボディの読み取り中にエラーが発生しました。
400RequestJsonUnmarshalErrorEvent APIがリクエストボディをアンマーシャルできませんでした。
400RequestValidationErrorリクエストボディの内容がバリデーションチェックに失敗しました。 パラメーター要件を正しく遵守しているか確認してください。
401UnauthorizedError認証トークンが無効または不正です。
403Forbidden提供されたアクセストークンはあなたのアカウントで認可されていません。
500, 502, 503InternalServerError, ServiceUnavailableErrorRokt側の予期しないエラーです。指数バックオフを使用して再試行するか、Roktサポートチームに連絡してください。
サンプル​
{
    "data": {
        "code": "RequestJsonUnmarshalError",
        "message": "unable to unmarshal request body"
    }
}

200 エラーシナリオ​

HTTP Status 200 は通常、呼び出しが成功したことを示します。しかし、Event API はバッチ API であるため、200 レスポンスは必ずしもリクエスト全体が正しく処理されたことを意味しません。開発者は、すべてのレコードが処理されたことを確認するためにレスポンスペイロードを確認する必要があります。レスポンスペイロードには、エラーメッセージと失敗した特定のイベントオブジェクトが含まれています。

レベル 1レベル 2レベル 3レベル 4タイプ説明
dataBulkResponseItemObject
unprocessedRecordsList[BulkResponseItemObject]処理に失敗したレコードを含むオブジェクトのリスト。
errorErrorObjectレコードに関連するエラーを説明します。
codeStringエラーコード
messageString詳細なエラーメッセージ
recordEventObject失敗した元のレコードを含むフィールド。
{
	"data": {
		"unprocessedRecords": [
			{
				"error": {
					"code": "ValidationError",
						"message": "Invalid content"
				},
				"record": {
					"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
					"eventType": "conversion",
					"eventTime": "2020-05-22T10:21:29.339Z",
					"objectData": [
						{
							"name": "firstname",
							"value": "john"
						}
					]
				}
			}
		]
	}
}

レガシー認証 (v1)​

注記

これは既存ユーザーおよび特定のカスタマーデータプラットフォーム (CDPs)（具体的には Census、Hightouch、mParticle、Segment、Tealium）にオンボーディングするユーザーのみを対象としています。 Event API の新規ユーザーおよび他のすべての統合は、より簡単な認証体験のために /v2/events を使用する必要があります。

Event API は、クライアント統合に OAuth 2.0 アプローチを活用しています。詳細については、OAuth 2.0 Credentials Flow を参照してください。Rokt Event API にアクセスするには、Rokt App ID と App Secret が必要です。

同じ手順で Rokt Reporting API のクレデンシャルを生成できます。

Rokt Event API の任意のエンドポイントを呼び出すにはアクセストークンが必要です。アクセストークンは、Rokt がクライアントアプリを識別し、各クライアントアプリがアクセスするデータの種類を特定し、悪意のあるアプリがアクセス権のないデータにアクセスするのを防ぐことを可能にします。

App IDとApp Secretの生成​

  1. One Platformにサインインします。

  2. 左下のアカウントアイコンの下にあるProfile Settingsに移動します。

img

  1. Generate Personal API Credentialsセクションまでスクロールダウンします。

  2. アプリの名前を入力します。

  3. Generateをクリックします。

  4. Event APIとReporting APIの両方の資格情報がすぐに生成され、以下のようになります:

    AppId: "40svbin0d194subpohl079rhck"
    AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"

  5. App IDとApp Secretを安全な場所に保管してください。このセッション後、App Secretに再度アクセスすることはできません。

  6. これらの資格情報はすぐに使用できます。

資格情報は機密情報として保持し、アカウントを保護するために絶対にメールで送信しないでください。たとえRoktからの問い合わせのように見えても、組織外に共有しないでください。Roktを正当に代表する者がApp Secretを尋ねることは決してありません。

呼び出しタイミング​

このエンドポイントを呼び出して、Event API と1時間やり取りするためのアクセストークンを生成します。APIとのやり取りを1時間以上続ける必要がある場合は、新しいアクセストークンを取得するためにこのエンドポイントを再度呼び出してください。

リクエスト​

サンプル​

curl -vX POST  https://api.rokt.com/auth/oauth2/token \
	-H 'Authorization: Basic ${AuthToken}' \
	-H 'Content-Type: application/x-www-form-urlencoded' \
	-d 'grant_type=client_credentials'

フィールド​

キー位置説明必須?例
Authorizationheaderapp_id と app_secret は Basic HTTP 認証を通じて認証ヘッダーに渡す必要があり、One Platform の Profile Settings で生成できます。ヘッダーの内容は Basic base64encode(app_id:app_secret) ですはいBasic base64encode(12345:abcde)
Content-Typeheaderリクエストのメディアタイプは常に application/x-www-form-urlencoded でなければなりませんはいapplication/x-www-form-urlencoded
grant_typebodyclient_credentials でなければなりませんはいclient_credentials

レスポンス​

例​

{
"access_token":
"eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA"
"expires_in": 3600,
"token_type": "Bearer"
}
POST /v1/events

リクエスト​

リクエストは、ヘッダーを除いてPOST /v2/events とすべての点で同一です。ヘッダーは次の形式を取ります：

ヘッダー​
名前値必須説明
Content-Typeapplication/jsonはいN/A
Charsetutf-8はいN/A
AuthorizationBearer ${access-token}はい/auth/oauth2/token エンドポイントから取得したアクセストークン
Rokt-Version2020-05-21はいRoktのAPIバージョン。現在の最新バージョンは2020-05-21です。
注意: このヘッダーを空にすると、最新バージョンが適用され、後方互換性がない可能性があります。無効な値は 400 bad request を返します。
この記事は役に立ちましたか？
Last updated Oct 29, 2025