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

コンバージョンAPI

非推奨のお知らせ

以下に記載されているコンバージョンAPIは現在非推奨となっており、新しい更新や機能強化は行われません。すべてのクライアントに対して、信頼性の向上、データ構造の強化、コンバージョントラッキングとオーディエンス管理の拡張機能を提供するイベントAPI統合ガイドへの移行を強くお勧めします。

なぜ変更するのか？ イベントとオーディエンスAPI統合は、コンバージョンとオーディエンスデータを送信するための最新化された統一インターフェースを提供し、以下を可能にします：

  • ユーザーアイデンティティと属性の取り扱いが改善されたデータ構造の強化
  • デバイス情報とモバイル広告IDのサポート向上
  • エラーハンドリングとレート制限機能の改善
  • コンバージョンイベントとオーディエンスデータのための統一インターフェース
  • 将来のデータタイプと統合パターンに対するスケーラブルなサポート

移行サポート 移行を支援するために、イベントAPI統合ガイドを参照してください。これには以下が含まれます：

  • リクエスト/レスポンス例を含む完全なAPIリファレンス
  • コンバージョンAPIから新しい統合へのフィールドマッピング
  • 認証とセキュリティのベストプラクティス
  • エラーハンドリングとレート制限のガイダンス
  • テストと検証手順

コンバージョンAPIは、既存のイベントAPIに似た方法でRoktにコンバージョンデータを送信するための構造化された方法を提供します。 任意のキーと値のペアではなく、定義されたフィールドセットを使用し、データ形式を検証し、問題に関する詳細なフィードバックを提供し、全体のリクエストを拒否することはありません。

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

POST https://api.rokt.com/v1/conversions

完全なAPIリファレンスについては、Swaggerドキュメントを参照してください。

認証認証 への直接リンク

コンバージョンイベントを送信したいアカウントのために、公開鍵と秘密鍵のペアを作成するには、Roktのアカウントマネージャーに連絡してください。これらの鍵はそれぞれrpub-とrsec-の形式を取ります。

名前値
Rokt 公開鍵rpub-********-****-****-****-************
Rokt 秘密鍵rsec-********-****-****-****-************

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

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

名前値説明
Content-Typeapplication/json必ずapplication/jsonであること。
AuthorizationBasic base64(rpub-...:rsec-...)標準的な基本認証ヘッダーであり、資格情報の値はrpub-とrsec-をコロンで結合したもののbase64エンコーディングである。

本文本文 への直接リンク

リクエスト本文は以下のフィールドを持つJSONとして提供されるべきです：

フィールド型最大長説明
accountId*文字列64Rokt アカウントID
testブール—trueに設定すると、リクエストはイベントを処理または取り込むことなく検証されます。統合テストに使用してください。
events*リスト[オブジェクト]100 アイテムコンバージョンイベントの配列。少なくとも1つのイベントを含める必要があります。

events 配列内の各オブジェクトには次のフィールドを含めることができます：

フィールド型最大長説明
conversionId文字列255コンバージョンの一意の識別子。リクエスト内で重複する値は、後続のイベントが拒否される原因となります。
conversionType*文字列255コンバージョンの種類（例：購入、サインアップ、サブスクリプション）。
eventTime*文字列—コンバージョンイベントが発生した時間（RFC3339形式）。未来または12か月以上前のものは不可。
roktId文字列255Roktユーザー識別子。
email文字列255ユーザーのメールアドレス（ハッシュ値との一貫性のために小文字推奨）。
emailsha256文字列64ユーザーのメールアドレスのSHA256ハッシュ（64文字の16進文字列）。
rclid文字列64RoktクリックID（SHA256ハッシュ、64文字の16進文字列）。
mobile文字列255ユーザーの携帯電話番号。
mobilesha256文字列64ユーザーの携帯電話番号のSHA256ハッシュ（64文字の16進文字列）。
firstName文字列255ユーザーの名。
lastName文字列255ユーザーの姓。
billingZipcode文字列255ユーザーの請求先郵便番号。
firstNamesha256文字列64ユーザーの名のSHA256ハッシュ（64文字の16進文字列）。
lastNamesha256String64ユーザーの姓のSHA256ハッシュ（64文字の16進文字列）。
billingZipcodesha256String64ユーザーの請求先郵便番号/郵便番号のSHA256ハッシュ（64文字の16進文字列）。
ipAddressString255ユーザーのIPアドレス。
userAgentString1024ブラウザからのユーザーエージェント文字列。
valueNumber—トランザクションの値（0から1000000）。
ltvNumber—顧客のライフタイムバリュー（0から1000000）。
predictedLTVNumber—予測される顧客のライフタイムバリュー（0から1000000）。
currencyString255通貨コード（ISO 4217）。
quantityInteger—商品の数量（最低0）。整数でなければなりません。
productNameString255製品名。
skuString255在庫管理単位識別子。
paymentTypeString255支払い方法のタイプ。
marginNumber—利益率（0から1000000）。
transactionIdString100ユニークなトランザクション識別子。
confirmationRefString100確認参照番号。重複排除に使用されます。
customAttributesObject—追加データのためのカスタムキーと値のペア。
• 最大10キー
• キーは英数字でなければなりません（スペース、アンダースコア、または特殊文字は不可）
• キーはイベントスキーマのフィールド名と競合してはなりません
• キーの長さは最大255文字
• 文字列の値は最大1024文字
識別子の検証

各コンバージョンイベントは、適切なマッチングと帰属を可能にするために、次の識別子の組み合わせの少なくとも1つを含める必要があります：

  • いずれか: roktId, email, emailsha256, rclid, mobile, mobilesha256
  • すべて: firstName, lastName, billingZipcode
  • すべて: firstNamesha256, lastNamesha256, billingZipcodesha256
  • すべて: ipAddress, userAgent

これらの要件を満たさないイベントは検証に失敗します。

サンプルサンプル への直接リンク

必須フィールドのみの最小例:

{
  "accountId": "12345",
  "events": [
    {
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "user@example.com"
    }
  ]
}

複数イベントの例:

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_001",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:00:00Z",
      "email": "alice@example.com"
    },
    {
      "conversionId": "evt_002",
      "conversionType": "signup",
      "eventTime": "2024-12-11T10:15:30Z",
      "email": "bob@example.com"
    },
    {
      "conversionId": "evt_003",
      "conversionType": "purchase",
      "eventTime": "2024-12-11T10:30:45Z",
      "email": "carol@example.com"
    }
  ]
}

利用可能なすべてのフィールドを含む完全な例:

{
  "accountId": "12345",
  "events": [
    {
      "conversionId": "evt_123456",
      "conversionType": "purchase",
      "eventTime": "2024-09-11T10:00:00Z",
      "roktId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "emailsha256": "d8a928b2043db77e340b523547bf16cb4aa483f0645fe0a290ed1f20aab76257",
      "rclid": "550e8400e29b41d4a716446655440001550e8400e29b41d4a716446655440001",
      "mobile": "+16175494599",
      "mobilesha256": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "firstName": "John",
      "lastName": "Doe",
      "billingZipcode": "12345",
      "firstNamesha256": "f1e2d3c4b5a698765432109876543210fedcba9876543210fedcba9876543210",
      "lastNamesha256": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "billingZipcodesha256": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
      "ipAddress": "192.168.0.1",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "value": 99.99,
      "ltv": 499.99,
      "predictedLTV": 299.99,
      "currency": "USD",
      "quantity": 1,
      "productName": "Premium Widget",
      "sku": "WIDGET-001",
      "paymentType": "credit_card",
      "margin": 24.99,
      "transactionId": "txn_789012",
      "confirmationRef": "conf_456789",
      "customAttributes": {
        "source": "website",
        "campaignId": "summer2024",
        "isNewCustomer": true,
        "sessionId": "abc123def456",
        "couponCode": "SAVE20",
        "discountPercent": 15,
        "taxRate": 0.0825
      }
    }
  ]
}

応答応答 への直接リンク

APIはリクエストを2段階で検証します:

  1. リクエスト検証: 認証、JSON形式、必須フィールドをチェック
  2. イベント検証: リクエスト検証が通過した場合に個々のイベントを処理

ステータスコードステータスコード への直接リンク

HTTP応答コード説明
200コンバージョンイベントが正常に処理されました（全体または部分的）。
400不正なリクエスト - 検証エラーまたはすべてのイベントが失敗しました。
401認証されていない - 無効または欠落している認証トークン。
403禁止 - このアカウントに対してトークンが認可されていません。
413リクエストエンティティが大きすぎる - リクエストボディが1MBの制限を超えています。
429リクエストが多すぎます - レート制限を超えています。
500内部サーバーエラー。
503サービス利用不可。

リクエスト検証エラーリクエスト検証エラー への直接リンク

応答にはdataオブジェクトが含まれます:

フィールドタイプ説明
codeStringエラーコード（例: EventsRequiredError, AccountIDRequiredError, InvalidJSONError）。
messageString詳細なエラーメッセージ。

イベント処理結果イベント処理結果 への直接リンク

少なくとも1つのイベントが有効な場合は200（成功/部分的）、イベントがすべて無効な場合は400（失敗）を返します。

すべての応答には次のフィールドを持つdataオブジェクトが含まれます:

フィールドタイプ説明
codeString応答ステータスコード（成功、部分的、または失敗）。
processedCountNumber正常に処理されたイベントの数。
invalidCountNumber検証に失敗したイベントの数。
errorsList[Object]イベント処理からのエラーの配列。各オブジェクトは以下のエラー/警告スキーマに従います。
warningsList[Object]イベント処理からの警告の配列。各オブジェクトは以下のエラー/警告スキーマに従います。

応答のwarningsには、全体のコンバージョンイベントを拒否するほど深刻ではないが失敗したチェックが含まれます。これらはinvalidCountに影響を与えません。

errorsおよびwarnings配列内の各エラーおよび警告オブジェクトには、対応するリクエストイベントで提供された場合、conversionIdフィールドが含まれます。これにより、どの特定のイベントが問題を引き起こしたかを特定するのに役立ちます。

エラー/警告オブジェクトスキーマ:

フィールドタイプ説明
conversionIdStringイベントに存在する場合のコンバージョンID。
eventIndexNumberリクエスト配列内のイベントの位置（0から始まる）。
fieldStringエラーまたは警告を引き起こしたフィールド名。
messageStringエラーまたは警告メッセージ。

サンプルサンプル への直接リンク

リクエスト検証エラー:

{
  "data": {
    "code": "InvalidAccountIDError",
    "message": "Account ID is invalid"
  }
}

成功（すべてのイベントが有効）:

{
  "data": {
    "code": "Success",
    "processedCount": 1,
    "invalidCount": 0
  }
}

部分的（いくつかのイベントが有効）:

{
  "data": {
    "code": "Partial",
    "processedCount": 1,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 1,
        "field": "conversionType",
        "message": "conversionType is required"
      },
      {
        "eventIndex": 1,
        "field": "eventTime",
        "message": "eventTime is required"
      }
    ]
  }
}

失敗（すべてのイベントが無効）:

{
  "data": {
    "code": "Failure",
    "processedCount": 0,
    "invalidCount": 1,
    "errors": [
      {
        "eventIndex": 0,
        "field": "eventTime",
        "message": "must be a valid RFC3339 timestamp"
      }
    ]
  }
}
この記事は役に立ちましたか？
Last updated Aug 4, 2026