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（イベント レベル）
 宛先は次のレベルで定義できます。
  • リクエスト レベル(必須): destinations のリストを IngestEventsRequestで指定します。
  • イベント レベル（省略可）: destination_references フィールドを Event オブジェクトに使用します。エントリを追加して、 destinations リストのどの宛先にイベントを送信するかを指定します。

`Destination`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
 トランザクション レベルのアイテムを cart_data.items配列にCartData オブジェクトにマッピングします。Data Manager API は、Merchant Center アカウントに存在する商品に対して、Merchant Center のいくつかの省略可能なフィールドをサポートしています。

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

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

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

Data Manager API では、user_data フィールドは Event オブジェクト 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 オブジェクトにマッピングされます。住所オブジェクトのマッピングをご覧ください。
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 で discount として（Google アナリティクスの場合）、または 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
          }
        ]
      }
    }
  ]
}