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` を定義してプロダクトの宛先 ID を特定する方法について詳しくは、 宛先とヘッダーを構成するをご覧ください。Destination
id transaction_id この値は、コンバージョン イベントの重複排除に使用されます。詳細
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 広告主向けのモバイル広告 ID（iOS の場合は IDFA、Android の場合は広告 ID）にマッピングします。詳しくは、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 for のサンプルを次に示します。これは、宛先の 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
          }
        ]
      }
    }
  ]
}