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

イベントAPI統合ガイド

RoktイベントAPIは、広告主がコンバージョンデータをサーバーから直接Roktに送信できるようにします。このサーバー間の統合により、ブラウザの制限や広告ブロッカーの影響を受けない信頼性の高い包括的なコンバージョントラッキングが可能になります。

概要概要 への直接リンク

イベントAPIとは？イベントAPIとは？ への直接リンク

イベントAPIは、サーバーサイドの統合であり、購入、サインアップ、その他のコンバージョンアクションをRoktに送信し、キャンペーンの最適化とアトリビューションを行うことができます。

サーバーサイド統合を使用する理由サーバーサイド統合を使用する理由 への直接リンク

利点説明
信頼性広告ブロッカー、ブラウザのプライバシー設定、クッキー制限の影響を受けない
カバレッジすべてのチャネルでのコンバージョンをトラッキング—ウェブ、モバイルアプリ、店舗、コールセンター
データ品質バックエンドシステムから直接、より豊かで正確なデータを送信
リアルタイムより迅速な最適化のために、イベントはほぼリアルタイムで処理される

前提条件前提条件 への直接リンク

始める前に、以下を確認してください：

  1. API資格情報 - RoktアカウントマネージャーからのAPIキーとAPIシークレット
  2. RoktクリックID（オプション、アトリビューションコンバージョン用） - Rokt広告インタラクションから取得

API資格情報の取得API資格情報の取得 への直接リンク

APIキーとAPIシークレットペアをリクエストするには、Roktアカウントマネージャーに連絡してください。これらの資格情報は、すべてのAPIリクエストで基本認証に使用されます。

RoktクリックIDの取得はオプションですが、強く推奨されます。APIリクエストにこのIDを含めると、クリックをコンバージョンしたユーザーと一致させる能力が大幅に向上します。同じクリックIDの値を両方に送信してください：

  • integration_attributes.1277.passbackconversiontrackingid
  • user_identities.other2

RoktはクリックIDなしでもアトリビューションを実行できますが、（可能な限り両方のフィールドに）含めることで、より正確な一致が得られます。

クイックスタートクイックスタート への直接リンク

コンバージョンイベントを送信する例を以下に示します：

curl -X POST https://s2s.us2.mparticle.com/v2/events \
  --user "YOUR_API_KEY:YOUR_API_SECRET" \
  --header "Content-Type: application/json" \
  --header "Charset: utf-8" \
  --data '{
    "environment": "development",
    "ip": "172.3.51.182",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email",
      "customerid": "cust_123456",
      "other2": "YOUR_ROKT_CLICK_ID"
    },
    "integration_attributes": {
      "1277": {
        "passbackconversiontrackingid": "YOUR_ROKT_CLICK_ID"
      }
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890"
    },
    "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"
          }
        }
      }
    ]
  }'

成功したリクエストはHTTP 202 Acceptedを返します。

認証認証 への直接リンク

RoktイベントAPIは、次のいずれかの方法で基本認証を使用して認証できます：

  1. HTTPクライアントが基本認証をサポートしている場合、APIキーを「ユーザー名」として、シークレットを「パスワード」として使用します。

  2. 手動でAuthorizationヘッダーを設定することができます。キーとシークレットを一緒にエンコードして含めます：

    2.1. キーとシークレットをコロン（:）で区切って連結します：

    example-api-key:example-api-secret

    2.2. 結果をUTF-8でBase64エンコードします：

    ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

    2.3. エンコードされた文字列の前に、認証方法をスペースを含めてプレフィックスします：

    Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

    2.4. 結果の文字列をHTTPリクエストのAuthorizationヘッダーとして設定します：

    Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

必須ヘッダー必須ヘッダー への直接リンク

ヘッダー値説明
Content-Typeapplication/jsonリクエストボディの形式
Charsetutf-8文字エンコーディング
AuthorizationBasic base64(api-key:api-secret)認証資格情報

APIリファレンスAPIリファレンス への直接リンク

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

POST https://s2s.us2.mparticle.com/v2/events

リクエストボディ構造リクエストボディ構造 への直接リンク

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": { ... },
  "user_attributes": { ... },
  "user_identities": { ... },
  "integration_attributes": { ... },
  "events": [ ... ]
}

フィールドリファレンスフィールドリファレンス への直接リンク

ルートレベルフィールドルートレベルフィールド への直接リンク

フィールドタイプ必須説明
environmentstringYesテスト時でも常に "production" でなければなりません。
ipstringNoユーザーのIPアドレス。ジオロケーションおよび不正検出に使用されます。

ユーザー識別子（必須）ユーザー識別子（必須） への直接リンク

Roktがイベントをユーザーにマッチさせるためには、少なくとも1つのユーザー識別子が必要です。

フィールドタイプ必須説明
user_identities.emailstring条件付きプレーンテキストのメールアドレス。小文字でトリムされている必要があります。other が提供されていない場合に必須です。
user_identities.otherstring条件付き代替識別子（例：SHA256でハッシュされたメール）。email が提供されていない場合に必須です。
user_identities.customeridstringNo内部の顧客またはユーザーID。イベント間で存在する場合、マッチングを改善します。
user_identities.other2stringNoページビュー（スクリーンビュー）イベントの場合、integration_attributes.1277.passbackconversiontrackingid（Rokt Click ID）と同じ値を使用して、イベントを正しいユーザーセッションに帰属させます。
メールフォーマット

プレーンテキストのメールを email フィールドに送信するか、SHA-256でハッシュされたメールを other フィールドに送信してください。ハッシュされたメールを送信する場合、ハッシュする前に小文字でトリムされていることを確認してください。

Click ID と other2

Rokt Click ID（例：URLパラメータやクッキーから取得したもの）がある場合、それを integration_attributes.1277.passbackconversiontrackingid と user_identities.other2 の両方に送信して、イベントが正しいユーザーセッションに帰属するようにします。これは、メールや他の識別子がない場合のページビュー（画面ビュー）イベントにおいて特に重要です。

デバイス情報デバイス情報 への直接リンク

デバイス識別子は、特にモバイルユーザーに対するマッチ率を向上させます。

フィールドタイプ必須説明
device_info.http_header_user_agentstringいいえブラウザまたはデバイスのユーザーエージェント文字列。
device_info.ios_advertising_idstringいいえiOS IDFA（広告主向け識別子）。フォーマット: UUID。
device_info.android_advertising_idstringいいえAndroid Advertising ID（AAID）。フォーマット: UUID。

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

ユーザー属性は、マッチングとパーソナライズのための追加データを提供します。Roktは、以下のユーザー属性をできるだけ多く設定することを推奨します。

フィールド型必須説明
firstnamestringいいえ顧客の名前。
firstnamesha256stringいいえ名前のSHA-256ハッシュ。ハッシュ化する前に、小文字に変換し、末尾のスペースをトリムします。
lastnamestringいいえ顧客の苗字。
lastnamesha256stringいいえ苗字のSHA-256ハッシュ。ハッシュ化する前に、小文字に変換し、末尾のスペースをトリムします。
mobilestringいいえ電話番号は1112345678または+1 (222) 345-6789の形式でフォーマットできます。
mobilesha256stringいいえ携帯電話番号のSHA-256ハッシュ。ハッシュ化する前に、携帯電話番号は5551234567（ダッシュやスペースなし）でフォーマットされている必要があります。
agestringいいえ顧客の年齢。
dobstringいいえ生年月日。yyyymmddの形式でフォーマットされています。
genderstringいいえ顧客の性別。例えば、M、Male、F、またはFemale。
citystringいいえ顧客の都市。
statestringいいえ顧客の州。
zipstringいいえ顧客の郵便番号。
titlestringいいえ顧客の敬称。例えば、Mr、Mrs、Ms。
languagestringいいえ購入に関連する言語。
valuestringいいえ顧客の価値。
predictedltvstringいいえ顧客の予測される生涯価値の合計。
ハッシュ化のためのデータ正規化

SHA-256で値をハッシュ化する前に:

  • すべてのテキストを小文字に変換
  • 先頭と末尾の空白をトリム
  • 電話番号を5551234567の形式に正規化（ダッシュ、スペース、括弧、国コードを削除）

統合属性統合属性 への直接リンク

フィールド型必須説明
integration_attributes.1277.passbackconversiontrackingidstringいいえRoktクリックID。このコンバージョンを特定のRokt広告インタラクションにリンクしてアトリビューションを行います。提供される場合、user_identities.other2も同じ値に設定します。
Attribution

Roktは、passbackconversiontrackingidを使用するかどうかに関わらず、アトリビューションを行うことができます。しかし、Click IDを含めることで、クリックをコンバージョンしたユーザーと一致させる能力が大幅に向上し、より正確なアトリビューションが可能になります。passbackconversiontrackingidとuser_identities.other2には同じ値を使用してください。

Events ArrayEvents Array への直接リンク

events配列にはコンバージョンデータが含まれています。

When to include the Events Array

コンバージョンイベントを送信する際には、events配列が必須です。

フィールドタイプ必須説明
eventsarrayはいイベントオブジェクトの配列。少なくとも1つのイベントを含む必要があります。
events[].event_typestringはい"custom_event"である必要があります。
events[].data.event_namestringはい"conversion"である必要があります。
events[].data.custom_event_typestringはい"transaction"である必要があります。
events[].data.timestamp_unixtime_msnumberはいコンバージョンが発生した時刻（Unixエポックからのミリ秒）。
events[].data.custom_attributes.conversiontypestringはいユーザーが行ったアクションの種類（例："purchase"、"signup"、"subscription"、ページビューの場合は"screen_view"）。重複排除のためにconfirmationrefと共に使用されます。
events[].data.custom_attributes.confirmationrefstringいいえ注文番号または確認番号。重複排除のためにconversiontypeと共に使用されます。
events[].data.custom_attributes.amountstringいいえ取引額を文字列として（例："99.99"）。
events[].data.custom_attributes.currencystringいいえISO 4217通貨コード（例："USD"、"EUR"、"GBP"）。
events[].data.custom_attributes.screen_namestringいいえscreen_viewイベントの場合：ページまたは画面の識別子（例：ファイル名またはパスセグメント）。
events[].data.custom_attributes.urlstringいいえscreen_viewイベントの場合：表示されたページの完全なURL。

完全な例完全な例 への直接リンク

完全なユーザーデータを伴うコンバージョン完全なユーザーデータを伴うコンバージョン への直接リンク

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": {
    "http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0"
  },
  "user_attributes": {
    "firstname": "John",
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d43f1f6c5f9fdb7c3c7a0e2d4",
    "lastname": "Doe",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1",
    "mobile": "3125551515",
    "mobilesha256": "f6d7c3a9b82d7cbb6f3d8e4a0c2f5d1b9f6c2a5f4e7d8b3c9a2f5e8d1c4b7a6",
    "age": "33",
    "dob": "19900717",
    "gender": "M",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "title": "Mr",
    "language": "en",
    "value": "52.25",
    "predictedltv": "136.23"
  },
  "user_identities": {
    "email": "john.doe@example.com",
    "customerid": "cust_123456",
    "other2": "e8335d31-2031-4bff-afec-17ffc1784697"
  },
  "integration_attributes": {
    "1277": {
      "passbackconversiontrackingid": "e8335d31-2031-4bff-afec-17ffc1784697"
    }
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "order_789012",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "purchase",
          "confirmationref": "ORD-789012",
          "amount": "149.99",
          "currency": "USD"
        }
      }
    }
  ]
}

プライバシー重視のリクエスト（ハッシュ化されたデータのみ）プライバシー重視のリクエスト（ハッシュ化されたデータのみ） への直接リンク

{
  "environment": "production",
  "user_identities": {
    "other": "8b1a9953c4611296a827abf8c47804d7e6c49c6b97d",
    "customerid": "cust_456789"
  },
  "user_attributes": {
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d9c3f1f6c5f9fdb7c3c7a0e2d4",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1"
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "evt_unique_456",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "signup"
        }
      }
    }
  ]
}

ページビュー（スクリーンビュー）イベントページビュー（スクリーンビュー）イベント への直接リンク

ページビューイベントは、リターゲティングオーディエンス戦略に使用されます。これらのイベントを統合して、Roktがサイト放棄者をターゲットにできるようにします。このパターンを使用して、ページビューまたはスクリーンビューイベントを送信します。統合のために、user_identities.other2とintegration_attributes.1277.passbackconversiontrackingidの両方に同じRokt Click IDの値を設定します（例：URLパラメータまたはクッキーから）。

{
  "environment": "production",
  "ip": "198.51.100.22",
  "device_info": {
    "http_header_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "user_identities": {
    "email": "visitor@example.com",
    "other": "SHA256-hash-of-email",
    "customerid": "cust_visit_001",
    "other2": "b4e7f891-33b2-49df-0bf4-6710ffd96604"
  },
  "integration_attributes": {
    "1277": {
      "passbackconversiontrackingid": "b4e7f891-33b2-49df-0bf4-6710ffd96604"
    }
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "timestamp_unixtime_ms": 1735765200000,
        "custom_attributes": {
          "screen_name": "premium-checkout.html",
          "url": "https://example.com/checkout/premium-checkout.html?rtid=b4e7f891-33b2-49df-0bf4-6710ffd96604",
          "conversiontype": "screen_view"
        }
      }
    }
  ]
}
ページビューのユーザー識別

ページビューイベントの場合、Rokt Click IDをuser_identities.other2とintegration_attributes.1277.passbackconversiontrackingidの両方に含めて、Rokt広告から来た同じユーザーセッションにイベントを結びつけます。

メールまたは顧客IDが利用できない場合

ページビューの場合、メールまたは顧客IDが利用できないときに、user_identities.other2を使用してクリックIDまたはセッションIDを渡すことができます。同じ値をintegration_attributes.1277.passbackconversiontrackingidに設定して、イベントが正しいユーザーセッションに帰属するようにします。

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

ステータスコード説明
202承認済みPOSTが承認されました。
400不正リクエストリクエストJSONが不正な形式であるか、フィールドが欠落しています。
401認証されていません認証ヘッダーがありません。
403禁止されています認証ヘッダーは存在しますが、無効です。
429リクエスト過多プロビジョニングされた制限を超えました。v2/events エンドポイントは、Retry-After レスポンスヘッダーを返すことがあり、その値には遅延秒数を示す非負の10進整数が含まれます。ヘッダーが存在しない場合は、指数バックオフとランダムジッターを使用してリクエストを再試行することをお勧めします。
503サービス利用不可指数バックオフパターンでリクエストを再試行することをお勧めします。
5xxサーバーエラーサーバー側のエラーが発生しました。リクエストを再試行してください。

場合によっては、サーバーがレスポンスボディに追加情報を提供することがあります。追加情報がない場合、レスポンスボディは省略され、ステータスコードとメッセージのみが返されます。

失敗したリクエストのレスポンスボディの例:

{
    "errors": [
        {
            "code": "BAD_REQUEST",
            "message": "Required event field \"event_type\" is missing or empty."
        }
    ]
}

制限制限 への直接リンク

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

リソース制限
総リクエストサイズ256 KB
秒あたりのバッチ数1秒あたり270バッチ
イベント名の長さ256文字
イベント属性名の長さ256文字
イベント属性値の長さ4096文字
バッチあたりのユーザー属性数100
ユーザー属性名の長さ256文字
ユーザー属性値の長さ4096文字

レート制限レート制限 への直接リンク

Roktはプラットフォームの安定性を確保するためにレート制限を実施しています。制限を超えると、APIはHTTP 429 Too Many Requests を返します。

Rate Limitの種類Rate Limitの種類 への直接リンク

種類説明
スピード時間枠ごとの最大リクエスト数
加速トラフィック増加の最大速度

レート制限の処理レート制限の処理 への直接リンク

429 レスポンスを受け取った場合:

  1. 推奨待機時間を確認するために Retry-After ヘッダーをチェック
  2. ジッターを伴う指数バックオフを実装:
import random

def calculate_backoff(attempt, retry_after=None, max_delay=60):
    base_delay = retry_after if retry_after else 1
    exponential_delay = min(base_delay * (2 ** attempt), max_delay)
    jitter = random.uniform(0, exponential_delay)
    return exponential_delay + jitter

プロアクティブなレート管理プロアクティブなレート管理 への直接リンク

成功したレスポンスには、現在の使用率を示す X-mp-rate-limit-percentage-used ヘッダーが含まれています。制限に達する前にリクエストレートを調整するためにこれを監視します。

X-mp-rate-limit-percentage-used: 75

Web SDKとの組み合わせWeb SDKとの組み合わせ への直接リンク

最大のカバレッジを得るために、Web SDKとEvent APIの両方を通じてコンバージョンを送信できます。Roktは、一貫した識別子を含めるとイベントを自動的に重複排除します。

重複排除を有効にするには、両方の統合で conversiontype と confirmationref に同じ値を含めます。Roktはこれら2つのフィールドの組み合わせを使用してイベントを識別し、重複排除します。

このアプローチは以下を提供します:

  • 冗長性 - どちらかの統合が失敗してもコンバージョンがキャプチャされる
  • 検証 - 両方のソースからのデータを比較して不一致を特定

テストテスト への直接リンク

開発環境開発環境 への直接リンク

本番環境に移行する前に、開発環境でのテストを設定するためにRoktのアカウントマネージャーと協力してください。

注記

environment フィールドは、テスト中であっても常に "production" に設定する必要があります。このフィールドはデータフォーマットのバージョンを示し、デプロイメントステージを示すものではありません。

テストチェックリストテストチェックリスト への直接リンク

  • 認証があなたのクレデンシャルで機能することを確認
  • テストイベントを送信し、202 Accepted レスポンスを確認
  • 無効なペイロードでエラーハンドリングをテスト
  • イベントがRoktのレポートに表示されることを確認（アカウントマネージャーと調整）
  • レート制限の処理をテスト
  • 統合がエンドツーエンドで機能することを確認するために、Roktのアカウントマネージャーに送信したいくつかのテストメールアドレスを提供

サポートサポート への直接リンク

統合に関する質問や支援が必要な場合は、Roktのアカウントマネージャーに連絡してください。適切なリソースを提供し、問題のトラブルシューティングをサポートします。

この記事は役に立ちましたか？
Last updated Aug 4, 2026