イベントとオーディエンスAPI統合ガイド

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

概要

イベントAPIとは？

イベントAPIは、サーバーサイドの統合であり、以下を可能にします：

• コンバージョンイベントの送信 - 購入、サインアップ、その他のコンバージョンアクションをRoktに報告し、キャンペーンの最適化とアトリビューションを行う
• オーディエンスデータの同期 - Roktキャンペーンでのターゲティングまたは抑制のためにユーザーセグメントをアップロードする

サーバーサイド統合を使用する理由

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

---

前提条件

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

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

API認証情報の取得

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

RoktクリックIDの取得（オプションだが推奨）

RoktクリックIDの取得はオプションですが、強く推奨されます。APIリクエストでpassbackconversiontrackingidとして含めると、このIDはクリックをコンバージョンしたユーザーにマッチさせる能力を大幅に向上させます。

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"
    },
    "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は、基本認証を使用して2つの方法のいずれかで認証できます：

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-Type	application/json	リクエストボディの形式
Charset	utf-8	文字エンコーディング
Authorization	Basic base64(api-key:api-secret)	認証資格情報

---

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": [ ... ]
}

---

フィールドリファレンス

ルートレベルフィールド

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

ユーザーID（必須）

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

フィールド	タイプ	必須	説明
user_identities.email	string	条件付き	プレーンテキストのメールアドレス。小文字でトリムされている必要があります。other が提供されていない場合は必須です。
user_identities.other	string	条件付き	代替識別子（例：SHA256でハッシュ化されたメール）。email が提供されていない場合は必須です。

メール形式

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

デバイス情報

デバイス識別子は、特にモバイルユーザーに対して一致率を向上させます。

フィールド	タイプ	必須	説明
device_info.http_header_user_agent	string	No	ブラウザまたはデバイスのユーザーエージェント文字列。
device_info.ios_advertising_id	string	No	iOS IDFA (広告識別子)。形式: UUID。
device_info.android_advertising_id	string	No	Android 広告ID (AAID)。形式: UUID。

ユーザー属性

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

フィールド	タイプ	必須	説明
firstname	string	No	顧客の名。
firstnamesha256	string	No	名のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをトリムしてください。
lastname	string	No	顧客の姓。
lastnamesha256	string	No	姓のSHA-256ハッシュ。ハッシュ化する前に、小文字にし、末尾のスペースをトリムしてください。
mobile	string	No	電話番号は1112345678または+1 (222) 345-6789の形式でフォーマットできます。
mobilesha256	string	No	携帯番号のSHA-256ハッシュ。ハッシュ化する前に、携帯番号は5551234567（ダッシュやスペースなし）形式でフォーマットしてください。
age	string	No	顧客の年齢。
dob	string	No	生年月日。形式はyyyymmdd。
gender	string	No	顧客の性別。例えば、M、Male、F、またはFemale。
city	string	No	顧客の市。
state	string	No	顧客の州。
zip	string	No	顧客の郵便番号。
title	string	No	顧客の称号。例えば、Mr、Mrs、Ms。
language	string	No	購入に関連する言語。
value	string	No	顧客の価値。
predictedltv	string	No	顧客の予測生涯価値の合計。

ハッシュ化のためのデータ正規化

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

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

統合属性

フィールド	タイプ	必須	説明
integration_attributes.1277.passbackconversiontrackingid	string	No	RoktクリックID。このコンバージョンを特定のRokt広告インタラクションにリンクしてアトリビューションを行います。

Attribution

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

Events Array (イベント配列)

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

When to include the Events Array (イベント配列を含めるタイミング)

コンバージョンイベントを送信する場合、events配列は必須です。オーディエンスデータのみを送信する場合、events配列は完全に省略できます。

フィールド	型	必須	説明
events	array	Yes	イベントオブジェクトの配列。少なくとも1つのイベントを含める必要があります。
events[].event_type	string	Yes	"custom_event"である必要があります。
events[].data.event_name	string	Yes	"conversion"である必要があります。
events[].data.custom_event_type	string	Yes	"transaction"である必要があります。
events[].data.timestamp_unixtime_ms	number	Yes	コンバージョンが発生した時刻（Unixエポックからのミリ秒）。
events[].data.custom_attributes.conversiontype	string	Yes	ユーザーが実行したアクションの種類（例: "purchase", "signup", "subscription"）。重複排除のためにconfirmationrefと共に使用されます。
events[].data.custom_attributes.confirmationref	string	No	注文または確認番号。conversiontypeと共にイベントを重複排除するために使用されます。
events[].data.custom_attributes.amount	string	No	取引額を文字列として（例: "99.99"）。
events[].data.custom_attributes.currency	string	No	ISO 4217通貨コード（例: "USD", "EUR", "GBP"）。

---

Audience Data (オーディエンスデータ)

ターゲティングまたは抑制のためにオーディエンスセグメントデータを送信するには、user_attributesにオーディエンス属性を追加します。

When to send Audience Data (オーディエンスデータを送信するタイミング)

オーディエンスデータのみを送信する場合、user_identitiesとuser_attributesオブジェクトのみを含める必要があります。オーディエンスのみのリクエストにはevents配列は必要ありません。

命名規則: すべてのオーディエンス属性はaudience_で始まる必要があります。Roktに送信したい各オーディエンスに対して1つの属性を含めます。

フィールド	型	必須	説明
audience_{audience_name}	boolean	No	ユーザーをこのオーディエンスに追加するにはtrue、削除するにはfalseを設定します。

オーディエンス属性の例:

フィールド	型	必須	説明
audience_all_users: true	boolean	No	ユーザーを「すべてのユーザー」オーディエンスリストに追加します。
audience_all_users: false	boolean	No	ユーザーを「すべてのユーザー」オーディエンスリストから削除します。
audience_premium_users: true	boolean	No	ユーザーを「プレミアムユーザー」オーディエンスリストに追加します。
audience_retargeting_list: false	boolean	No	ユーザーをリターゲティングオーディエンスリストから削除します。

例: オーディエンスのみのリクエスト

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": "production",
    "user_identities": {
      "email": "customer@example.com"
    },
    "user_attributes": {
      "audience_premium_users": true,
      "audience_retargeting_list": false
    }
  }'

---

完全な例

###Full User Dataでのコンバージョン

{
  "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"
  },
  "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"
  },
  "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"
        }
      }
    }
  ]
}

---

##エラーハンドリング

ステータス	コード	説明
202	Accepted	POSTが受け入れられました。
400	Bad Request	リクエストJSONが不正な形式であるか、フィールドが欠落しています。
401	Unauthorized	認証ヘッダーが欠落しています。
403	Forbidden	認証ヘッダーは存在しますが、無効です。
429	Too Many Requests	プロビジョニングされた制限を超えました。v2/events エンドポイントは、非負の10進整数を含む秒数を示す Retry-After レスポンスヘッダーを返すことがあります。ヘッダーが存在しない場合、指数バックオフとランダムジッターを使用してリクエストを再試行することをお勧めします。
503	Service Unavailable	指数バックオフパターンでリクエストを再試行することをお勧めします。
5xx	Server Error	サーバー側のエラーが発生しました。リクエストを再試行してください。

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

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

{
    "errors": [
        {
            "code": "BAD_REQUEST",
            "message": "必須のイベントフィールド \"event_type\" が欠落しているか空です。"
        }
    ]
}

---

制限

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

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

---

レート制限

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

###レート制限の種類

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

レート制限の処理

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とEvent APIの両方を通じてコンバージョンを送信できます。Roktは、一貫した識別子を含めるとイベントを自動的に重複排除します。

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

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

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

---

テスト

開発環境

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

注記

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

テストチェックリスト

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

---

##サポート

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