ECAPI 仕様のマッピング

このガイドは、IAB Tech Lab Event and Conversion API（ECAPI）仕様を使用するデベロッパーが、イベントデータとコンバージョン データを Data Manager API イベント取り込みスキーマにマッピングする際に役立ちます。

概要

ECAPI は、マーケティング関連のイベントとコンバージョンの構造を定義する、プラットフォームに依存しないオープンソースのデータ標準です。

次の表に、ECAPI の主な属性と設計原則を Data Manager API と比較した概要を示します。

ECAPI Data Manager API
重複排除 id（イベント ID）が必要 必要な要素: transaction_id
イベント ルーティング イベント ペイロードの data_set_id フィールドは、データの宛先を示します。 リクエストの destinations フィールドは、イベントの宛先を定義します。

Data Manager API は、1 つのリクエストで複数の宛先にイベントをルーティングすることもサポートしています。

詳細については、宛先とヘッダーを構成するをご覧ください。
プライバシーと同意に関するフィールド Global Privacy Platform（GPP）の同意文字列 Data Manager API は、Global Privacy Platform（GPP）の同意文字列を受け入れず、解析しません。Consent オブジェクトで同意フィールドを設定します。

同意は、リクエスト レベル（リクエスト内のすべてのイベントに適用）またはイベントレベル（個々のイベントに異なる同意設定を指定可能）で設定できます。

構造フィールド マッピング

次のマッピング テーブルは、ECAPI 仕様の個々のフィールドが Data Manager API で受け入れられるフィールドにどのように変換されるかを定義しています。

イベント オブジェクトのマッピング

ECAPI（event） Data Manager API（Event） メモ
data_set_id
  • destinations[].product_destination_id（リクエスト レベル）
  • destination_references（イベント単位）
 宛先は次のレベルで定義できます。
  • リクエスト レベル（必須）: IngestEventsRequest で destinations のリストを指定します。
  • イベントレベル（省略可）: Event オブジェクトの destination_references フィールドを使用します。エントリを追加して、destinations リストのどの宛先がイベントを受信するかを指定します。

Destination を定義してプロダクトの宛先 ID を決定する方法については、宛先とヘッダーを構成するをご覧ください。
id transaction_id コンバージョン イベントの重複を除去します。Google 広告、Google アナリティクス、Floodlight のイベントを送信するガイドの Google がマルチソース データを処理する方法をご覧ください。
timestamp event_timestamp 必須。ECAPI は、タイムスタンプに Unix エポック形式（整数）を使用します。Data Manager API にマッピングする場合は、event_timestamp フィールドを次のいずれかの形式に変換します。
  • JSON 形式を使用する場合は、RFC 3339 形式の値に設定します。
  • プロトコルバッファを使用する場合は、Timestamp を使用し、seconds フィールドと（オプションで）nanoseconds フィールドを設定します。

詳細については、タイムスタンプの形式をご覧ください。
event_type / custom_event event_name 推奨イベント名（例: purchase）でもカスタム イベント名でもかまいません。詳しくは、標準イベント名をご覧ください。
user_data user_data UserData オブジェクトにマッピングされます。このオブジェクトは、UserIdentifier オブジェクトのリストを受け入れます。
value conversion_value コンバージョンの金銭的価値を表す double または float として直接マッピングします。
currency_code currency 3 文字の大文字の通貨コード（例: USD）にマッピングします。
source event_source EventSource 列挙型の値に設定します。
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 トランザクション レベルの項目を CartData オブジェクトの cart_data.items 配列にマッピングします。Data Manager API は、Merchant Center アカウントに存在する商品のいくつかのオプションの Merchant Center フィールドをサポートしています。

リンク先が Google 広告のコンバージョン アクションの場合は、custom_variables フィールドに CustomVariable オブジェクトのリストとして追加のカスタム パラメータを含めることもできます。

宛先が Google アナリティクスのデータ ストリームの場合は、additional_event_parameters フィールドに AdditionalEventParameter オブジェクトのリストとして追加のイベント パラメータを含めることができます。
ext 同等のものはありません

ユーザーデータ オブジェクトのマッピング

Data Manager API では、Event オブジェクトの user_data フィールドは UserData オブジェクトを受け入れます。これには、UserIdentifier オブジェクトのリストが必要です。このリストには、メールアドレス、電話番号、住所コンポーネントなどの個々のユーザー識別子を含めることができます。

ECAPI（user_data） Data Manager API（Event） メモ
customer_identifier user_id（Google アナリティクス） Google アナリティクス イベントの場合、user_id フィールドは User-ID を表します。Data Manager API は、他のリンク先用の一般的なお客様 ID フィールドをサポートしていません。
uids 同等のものはありません Data Manager API は、エージェント タイプとドメインを含む構造化された uids 配列をサポートしていません。
customer_segments user_properties Event の UserProperties にマッピングします。
email_address user_data.user_identifiers[].email_address フォーマットしてハッシュ化したメールアドレスに設定します。ハッシュ化されたメールアドレスを暗号化することもできます。
phone_numbers user_data.user_identifiers[].phone_number フォーマットしてハッシュ化した電話番号に設定します。ハッシュ化された電話番号を暗号化することもできます。
utcoffset 同等のものはありません JSON 形式を使用している場合は、RFC 3339 event_timestamp 文字列でタイムゾーン オフセットを直接指定できます。
プロトコル バッファを使用している場合は、Timestamps.parse(String) などのユーティリティ関数を使用して、タイムゾーンの変換を秒とナノ秒に処理できます。
詳細については、タイムスタンプの形式をご覧ください。
address user_data.user_identifiers[].address AddressInfo オブジェクトにマッピングされます。Address オブジェクトのマッピングをご覧ください。
gpp_string 同等のものはありません 同意をリクエスト レベルまたはイベントレベルの Consent オブジェクトにマッピングします。プライバシーと同意の概要をご覧ください。
gpp_sid 同等のものはありません 同意をリクエスト レベルまたはイベントレベルの Consent オブジェクトにマッピングします。プライバシーと同意の概要をご覧ください。
mmt_only 同等のものはありません
click_id ad_identifiers.gclid Google クリック ID（gclid）にマッピングします。詳しくは、AdIdentifiers をご覧ください。
impression_id ad_identifiers.impression_id 詳細については、AdIdentifiers をご覧ください。
event_ip_address event_device_info.ip_address 使用可能なフィールドについては、DeviceInfo をご覧ください。
event_user_agent event_device_info.user_agent 使用可能なフィールドについては、DeviceInfo をご覧ください。
ifa ad_identifiers.mobile_device_id 広告主向けのモバイル識別子（iOS の場合は IDFA、Android の場合は AdID）にマッピングします。詳細については、AdIdentifiers をご覧ください。
landing_ip_address ad_identifiers.landing_page_device_info.ip_address 使用可能なフィールドについては、DeviceInfo をご覧ください。
landing_user_agent ad_identifiers.landing_page_device_info.user_agent 使用可能なフィールドについては、DeviceInfo をご覧ください。
age_range 同等のものはありません
gender 同等のものはありません
ext 同等のものはありません

アドレス オブジェクトのマッピング

ECAPI（address） Data Manager API（AddressInfo） メモ
first_name given_name AddressInfo の given_name フィールドにマッピングされます。フォーマットとハッシュ化のガイドラインに沿って対応してください。アドレスのハッシュ化された属性を暗号化することもできます。
last_name family_name AddressInfo の family_name フィールドにマッピングされます。フォーマットとハッシュ化のガイドラインに沿って対応してください。アドレスのハッシュ化された属性を暗号化することもできます。
street 同等のものはありません Data Manager API ではサポートされていません。
city 同等のものはありません Data Manager API ではサポートされていません。
state 同等のものはありません Data Manager API ではサポートされていません。
country_code region_code ハッシュ化しないでください。AddressInfo の region_code フィールドにマッピングされます。フォーマットに関するガイドラインに沿って作成してください。
postal_code postal_code ハッシュ化しないでください。AddressInfo の postal_code フィールドにマッピングされます。フォーマットに関するガイドラインに沿って作成してください。
address_type 同等のものはありません Data Manager API ではサポートされていません。
ext 同等のものはありません

アイテム オブジェクトのマッピング

ECAPI（item） Data Manager API（Item） メモ
id item_id Google アナリティクス イベントでは必須です。商品アイテムの標準の固有識別子に設定します。
同等のものはありません merchant_product_id Floodlight コンバージョンとカートデータを含む Google 広告コンバージョンの場合は必須です。Merchant Center アカウント内の商品 ID に設定します。
name additional_item_parameters additional_item_parameters リストの item_name としてマッピングします。
price unit_price
discount additional_item_parameters または custom_variables additional_item_parameters（Google アナリティクスの場合）では discount、custom_variables（Google 広告の場合）ではカスタム変数としてマッピングします。
quantity quantity float 値を整数（int64）に変換します。
brand additional_item_parameters additional_item_parameters リストの item_brand としてマッピングします。
affiliation additional_item_parameters additional_item_parameters リストの affiliation としてマッピングします。
category additional_item_parameters additional_item_parameters リストの item_category としてマッピングします。
cattax 同等のものはありません
item_coupon additional_item_parameters additional_item_parameters リストの coupon としてマッピングします。
item_list_id additional_item_parameters additional_item_parameters リストの item_list_id としてマッピングします。
item_list_name additional_item_parameters additional_item_parameters リストの item_list_name としてマッピングします。
item_item_variant additional_item_parameters additional_item_parameters リストの item_variant としてマッピングします。
item_location_id additional_item_parameters additional_item_parameters の location_id としてマッピングします。
ext 同等のものはありません

標準イベント名

ECAPI 標準イベントは、Google アナリティクスの命名規則に大きく準拠しています。

ほとんどの ECAPI 標準イベント（purchase、add_to_cart、begin_checkout、search、refund など）は、Google アナリティクスの推奨イベントと同じイベント名です。ただし、Google アナリティクスで過去形ではなく現在形が使用される例外がいくつかあります。

  • viewed_item は view_item にマッピングされます。

  • viewed_item_list は view_item_list にマッピングされます。

  • viewed_cart は view_cart にマッピングされます。

リクエストの例

次のタブでは、ECAPI コンバージョン イベントのペイロードと、有効な Data Manager API IngestEventsRequest としての表現を比較しています。

ECAPI

ECAPI 仕様に準拠した JSON ペイロードの例を次に示します。

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_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"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

フォーマット、ハッシュ、エンコードされたイベントデータの IngestEventsRequest の例を次に示します。宛先の GOOGLE_ADS アカウント タイプは、リクエストが Google 広告の宛先をターゲットにしていることを示します。

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "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"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}