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

Event API 統合ガイド

広告主は、サーバー間統合を設定して、コンバージョンおよびアトリビューションデータをバックエンドサーバーから直接RoktにEvent APIを介して送信できます。

Event APIを通じてRoktにコンバージョンデータを送信することには、いくつかの利点があります:

  • 速度: Event APIはほぼリアルタイムでのデータ転送を可能にし、Roktの最適化ツールの可能性を最大化します。
  • カバレッジ: Event APIはすべてのチャネルとデバイスからデータを送信でき、より広範なカバレッジを実現します。
  • 信頼性: SDKとは異なり、Event APIは広告ブロッカーのようなウェブ技術による干渉を受けません。また、エラーハンドリングをサポートしており、不要なデータ損失を防ぐのに役立ちます。

認証認証 への直接リンク

専任のRoktアカウント担当者が、Event APIに認証するために使用できるAPIキーとAPIシークレットを提供します。

HTTPクライアントによっては、キーとシークレットを使用してAPIに認証する方法が2つあります:

  1. クライアントでキーとシークレットをユーザー名とパスワードとして設定する、または
  2. 認証ヘッダーにキーとシークレットを渡す。

ユーザー名とパスワードユーザー名とパスワード への直接リンク

HTTPクライアントがベーシック認証をサポートしている場合、APIキーをユーザー名として、APIシークレットをパスワードとして設定してください。

ベーシック認証ヘッダーベーシック認証ヘッダー への直接リンク

HTTPリクエストのベーシック認証ヘッダーをEvent APIに設定し、キーとシークレットを使用することもできます:

  1. キーとシークレットをコロン (:) で連結します

    example-api-key:example-api-secret

  2. Base64/UTF-8を使用して、連結したキーとシークレットをエンコードします。次のようになります:

    ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

  3. この文字列の前に認証方法 (Basic) をスペースで区切って付けます。

  4. この文字列をリクエストの認証ヘッダーとして設定します:

    Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

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

Event APIはPOSTリクエストを以下に送信することを受け付けます:

https://s2s.{pod}.mparticle.com/v2/events

ここで、{pod}はRoktアカウント担当者から共有されたデータロケーションポッドに置き換えます。

データローカライゼーションデータローカライゼーション への直接リンク

Roktは、ポッドと呼ばれる分離されたローカライズされたリージョンでデータを保存および処理します。専任のRoktアカウント担当者が、あなたのアカウントに適したポッド識別子を提供します。提供されたポッド識別子に基づいて、以下の表に従って対応するEvent API URLを使用してください:

リージョンポッドEvent API URL
アメリカ合衆国US1https://s2s.us1.mparticle.com/v2
アメリカ合衆国US2https://s2s.us2.mparticle.com/v2
ヨーロッパEU1https://s2s.eu1.mparticle.com/v2
オーストラリアAU1https://s2s.au1.mparticle.com/v2

ペイロードの作成ペイロードの作成 への直接リンク

Roktは、コンバージョンを正常にトラッキングし、キャンペーンと関連付けるために、以下のフィールドを送信する必要があります:

設定フィールド設定フィールド への直接リンク

フィールド名データ型説明
environmentstringdevelopmentまたはproductionのいずれか。データがテストデータかライブデータかを示します。

ユーザーIDユーザーID への直接リンク

フィールド名データ型説明
emailstringユーザーのメールアドレス。
otherstringユーザーのハッシュ化されたメールアドレス。
注記

ユーザーの生のハッシュ化されていないメールアドレスを email フィールドで、またはハッシュ化されたメールアドレスを other フィールドで必ず含めてください。これらの識別子のうち少なくとも1つをEvent APIへのペイロードに含める必要があります。

ユーザー属性ユーザー属性 への直接リンク

フィールド名データ型説明
firstnamestringユーザーの名。
lastnamestringユーザーの姓。
mobilestringユーザーの電話番号。3053211654 または +1 (323) 867-5309 の形式でフォーマットされます。
ipaddressstringコンバージョンしたユーザーのIPアドレス。

アトリビューションデータの品質と効果を向上させるために、できるだけ多くのユーザー属性を含めるべきです。

イベントデータイベントデータ への直接リンク

フィールド名データ型説明
event_typestring必ず custom_event に設定してください。
event_namestringイベント名は常に conversion に設定する必要があります。conversion_type フィールドを使用して、purchase や subscription などの変換タイプに関する追加情報を含めることができます。
amountdecimalすべてのアイテムの合計価格。たとえば、すべてのアイテムの合計価格が $20 の場合、amount を 20.00 に設定します。
currencystring変換の通貨コード。例: USD または CAD。
quantityinteger変換内のアイテムの数。
conversiontypestring発生した変換のタイプ。
productnamestring変換中に購入されたアイテムの名前。
skustringアイテムのSKU。複数のアイテムが存在する場合、SKUを提供しないでください。
paymenttypestring使用された支払いの種類。例: visa.
margindecimalコンバージョンまたはトランザクションの総利益率をパーセンテージで示します。例えば、$10のマージンを示すには、marginを10に設定します。
transactionidstringコンバージョンのトランザクションID。
confirmationrefstring確認参照ID。これは代替の識別子です。注: 提供された場合、Roktはこのフィールドを使用してコンバージョンイベントを重複排除します。

リクエストの本文には、次の形状のJSONオブジェクト内にこれらのフィールドを含める必要があります:

例のペイロード:例のペイロード: への直接リンク

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "events": [
      {
        "event_type": "custom_event",
        "data": {
           "event_name": "conversion",
           "custom_attributes": {
              "amount": 100.00,
              "currency": "USD",
              "quantity": 1,
              "conversiontype": "purchase",
              "productname": "Maroon 5 t-shirt, Warriors vs. Raptors",
              "sku": "230847",
              "paymenttype": "VISA",
              "margin": 10.0,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}

Roktへのペイロードの送信Roktへのペイロードの送信 への直接リンク

Roktにペイロードを送信するには、https://s2s.{pod}.mparticle.com/v2/events に POST リクエストを送信します。{pod} は、Roktのアカウント担当者から提供されたポッド識別子に置き換えてください。

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

<Tabs className="unique-tabs" defaultValue="curl" values={[ {label: 'curl', value: 'curl'}, {label: 'HTTP', value: 'HTTP'}, ]}>

curl --location 'https://s2s.mparticle.com/v2/events' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key-secret' \
--data-raw '{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "events": [
      {
        "event_type": "custom_event",
        "data": {
           "event_name": "conversion",
           "custom_attributes": {
              "amount": 100.00,
              "currency": "USD",
              "quantity": 1,
              "conversiontype": "purchase",
              "productname": "Maroon 5 t-shirt, Warriors vs. Raptors",
              "sku": "230847",
              "paymenttype": "VISA",
              "margin": 10,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}'
 
POST /v2/events HTTP/1.1
Host: s2s.mparticle.com
Content-Type: application/json
Accept: application/json
Authorization: key-secret
Content-Length: 920

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "events": [
      {
        "event_type": "custom_event",
        "data": {
           "event_name": "conversion",
           "custom_attributes": {
              "amount": 100.00,
              "currency": "USD",
              "quantity": 1,
              "conversiontype": "purchase",
              "productname": "Maroon 5 t-shirt, Warriors vs. Raptors",
              "sku": "230847",
              "paymenttype": "VISA",
              "margin": 10,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}

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

成功したリクエストは空の 202 Accepted レスポンスを受け取ります。

発生する可能性のあるエラーの概要については、以下のエラーハンドリングを参照してください。

エラーハンドリングエラーハンドリング への直接リンク

ステータスコード説明
400Bad RequestリクエストのJSONボディが不正または必要なフィールドが欠落しています。
401Unauthorized認証ヘッダーが欠落しています。
403Forbidden認証ヘッダーは存在しますが、無効です。
429Too Many Requestsレート制限が超過しました。レスポンスには、再試行するまでの秒数を示す非負の10進整数を含む Retry-After ヘッダーが含まれています。Retry-After ヘッダーが存在しない場合は、指数バックオフとランダムジッターを使用してリクエストを再試行してください。
503サービス利用不可リクエストを指数バックオフパターンで再試行してください。
5xxサーバーエラー内部エラー、リクエストを再試行してください。

制限制限 への直接リンク

以下は、Event API のレートとサイズの制限です:

リソース制限
総リクエストサイズ256kb
秒あたりのバッチ数270 バッチ/秒
イベント名の長さ256 文字
イベント属性名の長さ256 文字
イベント属性値の長さ4096 文字
バッチあたりのユーザー属性数100
ユーザー属性名の長さ256 文字
ユーザー属性値の長さ4096 文字
この記事は役に立ちましたか？
Last updated Oct 29, 2025