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

イベントAPI

概要​

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

Rokt Ecommerce のパートナーは、Web SDKと共にイベントAPIを使用して、異常検知 を行い、配置動作の不整合を特定するのに役立てることができます。

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

認証​

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

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

API エンドポイント​

POST イベント​

イベントAPIはクライアントが1つまたは複数のイベントをRoktプラットフォームと統合するために使用します。イベントは通常、コンバージョンまたは取引イベントを指しますが、用途は柔軟です。

イベント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はい文字列; 最大64文字Rokt アカウント ID
eventsはいList[EventObject]; 1回の呼び出しで最大100アイテム取り込まれるイベントのリスト
clientEventIdはい文字列; 最大36文字イベントを一意に識別するために使用される識別子
eventTypeはい文字列; 最大128文字イベントの種類
eventTimeはい文字列イベントの時間はUTCおよびRFC 3339でなければなりません。タイムスタンプが18ヶ月以上前またはイベントAPIが受信する時点から5分以上先のイベントを含むリクエストは拒否されます。この範囲外のタイムスタンプを持つイベントは処理されません。
metaDataいいえList[metaData]イベントに関する非重要情報を提供します
nameはい文字列; 最大256文字フィールド名; 接頭辞 rokt.（大文字小文字を区別しない）はRoktの使用のみに保持されます
valueはい文字列; 最大65536文字フィールド値; バイナリ値の場合はBase64でエンコードします
objectDataいいえList[objectData]イベントの状況に関する詳細を含んでいます
nameはい文字列; 最大256文字接頭辞 rokt.（大文字小文字を区別しない）はRoktの使用のみに保持されます
valueはい文字列; 最大65536文字フィールド値; バイナリ値の場合はBase64でエンコードします
標準 objectData フィールド​

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

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

名前説明例の値
emailテキスト形式で渡されたメールアドレス、小文字かつ末尾にスペースがないjohn@email.com
emailsha256メールアドレスのSHA-256ハッシュ。ハッシュ化する前に小文字かつ末尾にスペースがないもの。fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingidコンバージョンイベントを元のクリックにマッチするために使用されるRokt生成のID。別の統合 が必要です。1bc29b36f623ba82aaf6724fd3b16718
amount取引金額（小数点を許可）100.25
currency通貨コードUSD
quantity特定のコンバージョン内の商品の数量（整数）4
conversiontype異なるコンバージョンイベントを区別するために使用します。
Note: デフォルトのコンバージョンイベントタイプが提供される場合にのみ適用されます。		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
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
dobyyyymmdd形式19851220
age顧客の年齢33
language購入に関連する言語en, en-US
unitno住所に関連するユニット番号Unit A
address1住所の1行目123 Sesame St
address2住所の2行目（アパート番号、階など）Alphabet Boulevard
zipcode顧客の郵便番号90210, SW1W 0DT
city顧客の市区町村San Francisco
state顧客の州CA, California, NY, New York
country顧客の国US, United States, AU, Australia
customervalue顧客の価値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トラブルシューティングのために、リクエストに関連付けられた一意の識別子。
本文​

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

サンプル​

以下のコードサンプルは、イベント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)​

注記

これは、既存のユーザーと特定のカスタマーデータプラットフォーム (CDP) (具体的にはCensus、Hightouch、mParticle、Segment、およびTealium) にオンボーディングしているユーザーのみを対象としています。 イベントAPIの新規ユーザーおよび他のすべての統合は、より簡単な認証エクスペリエンスのために /v2/events を使用してください。

イベントAPIは、クライアント統合にOAuth 2.0アプローチを活用しています。詳細については OAuth 2.0 クレデンシャルフロー を参照してください。RoktイベントAPIにアクセスするには、RoktアプリIDとアプリシークレットが必要です。

これと同じ手順で RoktレポートAPI のクレデンシャルを生成できます。

RoktイベントAPIのいずれかのエンドポイントを呼び出すにはアクセストークンが必要です。アクセストークンは、Roktがクライアントアプリを識別し、各クライアントアプリがアクセスしているデータのタイプを確認し、悪意のあるアプリがアクセス権のないデータにアクセスするのを防ぐことを可能にします。

アプリIDとアプリシークレットの生成​

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

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

img

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

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

  3. Generate ボタンをクリックします。

  4. イベントAPIとレポートAPIの両方のクレデンシャルが直ちに生成され、以下のようになります：

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

  5. アプリIDとアプリシークレットを安全な場所に保存します。このセッション後にアプリシークレットにアクセスすることはできません。

  6. すぐにこれらのクレデンシャルを使用することができます。

アカウントを保護するためにクレデンシャルを機密扱いとし、メールで送信しないでください。たとえお問い合わせがRoktから来たように見えても、これらを組織外部の人と共有しないでください。Roktを正当に代表する者があなたにアプリシークレットを尋ねることは決してありません。

呼び出すタイミング​

このエンドポイントを呼び出すことで、1時間の間、Event APIと対話するためのアクセストークンを生成します。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) です。YesBasic base64encocde(12345:abcde)
Content-Typeheaderリクエストのメディアタイプは常にapplication/x-www-form-urlencodedでなければなりませんYesapplication/x-www-form-urlencoded
grant_typebodyclient_credentialsでなければなりませんYesclient_credentials

レスポンス​

例​

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

リクエスト​

リクエストはすべての点で/v2/events のPOSTと同一ですが、ヘッダーが以下の形式を取ります:

ヘッダー​
名前値必須説明
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 をもたらします。
この記事は役に立ちましたか？