Event API
概要概要 への直接リンク
RoktのEvent APIは、購入、アプリのオープン、店舗訪問など、あらゆる種類のクライアントイベントと、それに関連する属性（例：メールアドレス、購入金額、クレジットカードBIN）をサポートできる柔軟で堅牢なインターフェースです。
Rokt Ecommerceのパートナーは、Web SDKと併用してEvent APIを使用することで、配置動作の不整合を検出する異常検出を支援できます。
Rokt Adsのクライアントは、Event APIを使用してRoktとコンバージョンデータを統合し、キャンペーンのパフォーマンスと最適化を向上させることができます。
認証認証 への直接リンク
コンバージョンイベントを送信したいアカウントのために、公開鍵と秘密鍵のペアを作成するには、Roktのアカウントマネージャーに連絡してください。受け取るキーは以下の通りです：
| 名前 | 値 |
|---|---|
| Rokt Public Key | rpub-*****-***** |
| Rokt Secret Key | rsec-*****-***** |
APIエンドポイントAPIエンドポイント への直接リンク
POST EventsPOST Events への直接リンク
Event APIは、クライアントがRoktプラットフォームと1つ以上のイベントを統合することを可能にします。イベントは通常、コンバージョンやトランザクションイベントを指しますが、使用は柔軟です。
Event APIには2つの主なユースケースがあります：異常検出（パートナー向け）およびコンバージョンレポート（広告主向け）。
POST /v2/events
リクエストリクエスト への直接リンク
ヘッダーヘッダー への直接リンク
| 名前 | 値 | 必須 | 説明 |
|---|---|---|---|
Content-Type | application/json | はい | N/A |
Charset | utf-8 | はい | N/A |
Rokt-Version | 2020-05-21 | はい | RoktのAPIバージョン。現在の最新バージョンは2020-05-21です。 注意: このヘッダーを空にすると、最新バージョンが適用され、後方互換性がない可能性があります。無効な値は 400 bad requestを引き起こします。 |
Authorization | Basic 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 フィールドobjectdata-fields への直接リンク
以下は、RoktがEvent APIを通じて受け入れる標準の objectData フィールドの一覧です。利用ケースに応じて、いくつかのフィールドは他のフィールドよりも関連性が高くなります。利用ケースに基づいた特定のペイロードサンプルについては、異常検出 または コンバージョンレポート を参照してください。
追加のデータフィールドを追加したい場合や特定のフィールドに異なる名前を使用したい場合は、アカウントマネージャーにお知らせください。
| 名前 | 説明 | 例 |
|---|---|---|
email | プレーンテキストで渡されるメールアドレス、小文字で末尾にスペースがないこと | john@email.com |
emailsha256 | メールアドレスのSHA-256ハッシュ。ハッシュ化前に小文字で末尾にスペースがないこと。 | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
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 | コンバージョンされた支払いのクレジットカードBIN | 123456 |
margin | コンバージョンの利益率（絶対値）- 例: $10.12の利益率の場合は10.12 | 10.12 |
transactionid | トランザクションID、ユニークな取引を識別するために使用されます。 | ABC789 |
confirmationref | 確認参照ID。ユニークな取引を識別したり、注文確認を追跡するために使用される代替識別子。 注: 提供された場合、Roktはこの識別子を使用してコンバージョンイベントを重複排除します。 | XYZ123 |
firstname | 顧客の名前 | John |
firstnamesha256 | 名前のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをすべてトリムします。 | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
lastname | 顧客の名字 | Smith |
lastnamesha256 | 名字のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをすべてトリムします。 | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
mobile | コンバージョンされた顧客の携帯電話番号 | 3053211654, +1 (323) 867-5309 |
mobilesha256 | 携帯電話番号のSHA-256ハッシュ。 注: ハッシュ化する前に、携帯電話番号はこの特定の形式にフォーマットする必要があります: 5551234567（ダッシュやスペースを含まない）。 | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
ipaddress | 顧客のIPアドレス | 172.3.51.182 |
ipaddresssha256 | IPアドレスのSHA-256ハッシュ。 | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
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 | フォーマット yyyymmdd | 19851220 |
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レスポンスを検証する際には、unprocessedRecordsにイベントが返されていないことを確認してください。unprocessedRecordsにレコードがある場合、1つ以上のイベントが正しく処理されていない可能性があります。
レスポンスレスポンス への直接リンク
| HTTP レスポンスコード | エラーコード | 説明 |
|---|---|---|
| 200 | N/A | 通常はOKですが、以下の200エラーシナリオの例を参照してください。 |
| 400 | RequestBodyReadError | リクエストボディの読み取り中にエラーが発生しました。 |
| 400 | RequestJsonUnmarshalError | Event APIがリクエストボディをアンマーシャルできませんでした。 |
| 400 | RequestValidationError | リクエストボディの内容がバリデーションチェックに失敗しました。 パラメーター要件を正しく遵守しているか確認してください。 |
| 401 | UnauthorizedError | 認証トークンが無効または不正です。 |
| 403 | Forbidden | 提供されたアクセストークンはあなたのアカウントで認可されていません。 |
| 500, 502, 503 | InternalServerError, ServiceUnavailableError | Rokt側の予期しないエラーです。指数バックオフを使用して再試行するか、Roktサポートチームに連絡してください。 |
サンプルサンプル への直接リンク
{
"data": {
"code": "RequestJsonUnmarshalError",
"message": "unable to unmarshal request body"
}
}
200 エラーシナリオ200 エラーシナリオ への直接リンク
HTTP Status 200 は通常、呼び出しが成功したことを示します。しかし、Event API はバッチ API であるため、200 レスポンスは必ずしもリクエスト全体が正しく処理されたことを意味しません。開発者は、すべてのレコードが処理されたことを確認するためにレスポンスペイロードを確認する必要があります。レスポンスペイロードには、エラーメッセージと失敗した特定のイベントオブジェクトが含まれています。
| レベル 1 | レベル 2 | レベル 3 | レベル 4 | タイプ | 説明 |
|---|---|---|---|---|---|
data | BulkResponseItemObject | ||||
unprocessedRecords | List[BulkResponseItemObject] | 処理に失敗したレコードを含むオブジェクトのリスト。 | |||
error | ErrorObject | レコードに関連するエラーを説明します。 | |||
code | String | エラーコード | |||
message | String | 詳細なエラーメッセージ | |||
record | EventObject | 失敗した元のレコードを含むフィールド。 |
{
"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)レガシー認証 (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の生成App IDとApp Secretの生成 への直接リンク
-
One Platformにサインインします。
-
左下のアカウントアイコンの下にあるProfile Settingsに移動します。
-
Generate Personal API Credentialsセクションまでスクロールダウンします。
-
アプリの名前を入力します。
-
Generateをクリックします。
-
Event APIとReporting APIの両方の資格情報がすぐに生成され、以下のようになります:
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn" -
App IDとApp Secretを安全な場所に保管してください。このセッション後、App Secretに再度アクセスすることはできません。
-
これらの資格情報はすぐに使用できます。
資格情報は機密情報として保持し、アカウントを保護するために絶対にメールで送信しないでください。たとえ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'
フィールドフィールド への直接リンク
| キー | 位置 | 説明 | 必須? | 例 |
|---|---|---|---|---|
| Authorization | header | app_id と app_secret は Basic HTTP 認証を通じて認証ヘッダーに渡す必要があり、One Platform の Profile Settings で生成できます。ヘッダーの内容は Basic base64encode(app_id:app_secret) です | はい | Basic base64encode(12345:abcde) |
| Content-Type | header | リクエストのメディアタイプは常に application/x-www-form-urlencoded でなければなりません | はい | application/x-www-form-urlencoded |
| grant_type | body | client_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-Type | application/json | はい | N/A |
Charset | utf-8 | はい | N/A |
Authorization | Bearer ${access-token} | はい | /auth/oauth2/token エンドポイントから取得したアクセストークン |
Rokt-Version | 2020-05-21 | はい | RoktのAPIバージョン。現在の最新バージョンは2020-05-21です。 注意: このヘッダーを空にすると、最新バージョンが適用され、後方互換性がない可能性があります。無効な値は 400 bad request を返します。 |