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

イベントAPI

概要​

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

Rokt Ecommerceのパートナーは、Web SDKと組み合わせてイベントAPIを使用して異常検出を行い、配置の振る舞いの不一致を検出するのに役立てることができます。

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

認証​

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

同じ手順でRokt Reporting APIの資格情報を生成することもできます。

RoktイベントAPIの任意のエンドポイントを呼び出すには、アクセストークンが必要です。アクセストークンにより、Roktはクライアントアプリを識別し、各クライアントアプリがアクセスしているデータの種類を把握し、悪意のあるアプリがアクセス権限のないデータにアクセスするのを防ぎます。

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

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

  2. アカウントアイコンの下部左側にあるプロファイル設定に移動します。

img

  1. 個人用API資格情報の生成セクションまでスクロールします。

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

  3. 生成をクリックします。

  4. イベントAPIとレポートAPIの両方の資格情報がすぐに生成され、次のような形式になります：

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

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

  6. これらの資格情報をすぐに使用することができます。

アカウントを保護するために、資格情報は機密に保つ必要があります。メールで送信しないでください。組織外で共有しないでください。Roktからの問い合わせであっても、正当なRoktの代表者はアプリシークレットを求めることはありません。

いつ呼び出すべきか​

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

リクエスト​

サンプル​

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'

フィールド​

KeyInDescriptionRequired?Example
Authorizationheaderapp_idとapp_secretはBasic HTTP認証を通じてAuthorizationヘッダーに渡す必要があります。これらはOne Platformのプロファイル設定で生成できます。ヘッダーの内容は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"
}

API エンドポイント​

POST イベント​

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

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

POST /v1/events

リクエスト​

ヘッダー​
名前値必須説明
Content-Typeapplication/jsonYesN/A
Charsetutf-8YesN/A
AuthorizationBearer ${access-token}Yes/auth/oauth2/tokenエンドポイントから取得したアクセストークン
Rokt-Version2020-05-21YesRoktのAPIバージョン。現在の最新バージョンは2020-05-21です。
注意: このヘッダーを空にすると、最新バージョンが適用され、互換性のないバージョンになる可能性があります。無効な値は400 bad requestを返します。
Idempotency-Key${uuid-v4}Yesクライアントからの一意の識別子。イベントの安全な再試行を許可するために使用されます。同じidempotency-keyを持つ後続のリクエストはHTTP 409を返します。キーは3時間後に削除されることができます。キーが期限切れになった後に同じキーが再利用されると、新しいリクエストが受け入れられます。

パラメータ​

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

レベル1レベル2レベル3必須タイプ説明
accountIdYes文字列; 最大64文字RoktアカウントID
eventsYesList[EventObject]; 1回の呼び出しで最大100個のアイテムインジェストするイベントのリスト
clientEventIdYes文字列; 最大36文字イベントを一意に識別するための識別子
eventTypeYes文字列; 最大128文字イベントのタイプ
eventTimeYes文字列イベントの時刻はUTCとRFC 3339形式である必要があります。イベントAPIが受け取った時点から18ヶ月以上前または5分以上未来のタイムスタンプを持つイベントを含むリクエストは拒否されます。この範囲外のタイムスタンプを持つイベントは処理されません。
metaDataNoList[metaData]イベントについての非ビジネスクリティカルな情報を提供します
nameYes文字列; 最大256文字フィールド名; rokt.の接頭辞（大文字小文字を区別しない）はRokt専用です
valueYes文字列; 最大65536文字フィールドの値; バイナリ値はBase64でエンコードします
objectDataNoList[objectData]イベントの文脈に関する詳細を含みます
nameYes文字列; 最大256文字rokt.の接頭辞（大文字小文字を区別しない）はRokt専用です
valueYes文字列; 最大65536文字フィールドの値; バイナリ値はBase64でエンコードします
標準の objectData フィールド​

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

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

NameDescriptionExample value
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
transactionid一意のトランザクションを識別するために使用されるトランザクションID。
注意: 提供された場合、Roktはこの識別子を使用してチャネル間での変換イベントの重複を排除します。		ABC789
confirmationref確認参照ID。一意のトランザクションを識別したり、注文の確認を追跡するために使用される代替識別子。
注意: 提供された場合、Roktはこの識別子を使用して変換イベントの重複を排除し、transactionidは利用できません。		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デバイスのタイプデスクトップ, モバイル, タブレット
osデバイスのオペレーティングシステムiOS
osversionオペレーティングシステムのバージョン8.1
browserブラウザSafari
browserversionブラウザのバージョン11.1
title顧客の敬称氏, 夫人, さん, 未婚
gender顧客の性別男性, 男, 女性, 女
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
サンプル​

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

POST /v1/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"
                }
            ]
        }
    ]
}

レスポンス​

NameDescription
X-Rokt-Trace-Idリクエストに関連する一意の識別子で、トラブルシューティングの目的で使用されます。
ボディ​

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

サンプル​

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

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

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

レスポンス​

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

200エラーシナリオ​

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

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