Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ECAPI 仕様のマッピング

このガイドは、IAB Tech Lab のイベントとコンバージョン 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`	この値は、コンバージョンイベントの重複除去に使用されます。詳細
`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`	`UserIdentifier` オブジェクトのリストを受け入れる `UserData` オブジェクトにマッピングされます。
`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 オブジェクトのリストを想定しています。このリストには、メールアドレス、電話番号、住所コンポーネントなどの個々のユーザー ID を含めることができます。

ECAPI（`user_data`）	Data Manager API（`Event`）	メモ
`customer_identifier`	`user_id`（Google アナリティクス）	Google アナリティクスイベントの場合、`user_id` フィールドは User-ID を表します。Data Manager API は、他の送信先の汎用顧客 ID フィールドをサポートしていません。
`uids`	同等のものはありません	データマネージャー 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`	広告主向けのモバイル広告 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`	同等のものはありません

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

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`	同等のものはありません

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

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 アナリティクスの命名規則に大きく準拠しています。

イベントを Google アナリティクスのデータストリームに送信する場合は、event_name フィールドが必須になります。
各イベントの関連フィールド、パラメータ、Data Manager API の取り込みリクエストのサンプルについては、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
          }
        ]
      }
    }
  ]
}