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

Pemetaan spesifikasi ECAPI

Panduan ini membantu developer yang menggunakan spesifikasi IAB Tech Lab Event and Conversion API (ECAPI) memetakan data peristiwa dan konversi mereka ke skema penyerapan peristiwa Data Manager API.

Ringkasan

ECAPI adalah standar data open source yang independen dari platform dan dirancang untuk menentukan struktur peristiwa dan konversi terkait pemasaran.

Tabel berikut memberikan gambaran umum tingkat tinggi tentang perbandingan atribut utama dan prinsip desain ECAPI dengan Data Manager API.

	ECAPI	Data Manager API
Penghapusan duplikat	Mengandalkan `id` (ID peristiwa)	Bergantung pada `transaction_id`
Perutean acara	Tujuan data ditunjukkan oleh kolom `data_set_id` di payload peristiwa.	Kolom `destinations` permintaan menentukan tujuan untuk peristiwa. Data Manager API juga mendukung perutean peristiwa ke beberapa tujuan dalam satu permintaan. Lihat panduan tujuan untuk mengetahui informasi selengkapnya.
Kolom privasi dan izin	String izin Global Privacy Platform (GPP)	Data Manager API tidak menerima atau mengurai string izin Global Privacy Platform (GPP). Kolom izin harus ditetapkan dalam objek `Consent`. Anda dapat menetapkan izin di tingkat permintaan (yang berlaku untuk semua peristiwa dalam permintaan) atau di tingkat peristiwa (yang memungkinkan Anda menentukan setelan izin yang berbeda untuk setiap peristiwa).

Pemetaan kolom struktural

Tabel pemetaan berikut menentukan cara menerjemahkan setiap kolom dari spesifikasi ECAPI ke kolom yang diterima oleh Data Manager API.

Pemetaan objek peristiwa

ECAPI (`event`)	Data Manager API (`Event`)	Catatan
`data_set_id`	`destinations[].product_destination_id` (Tingkat permintaan) `destination_references` (Tingkat peristiwa)	Dapat ditentukan pada tingkat berikut: Tingkat permintaan (Wajib): Tentukan daftar `destinations` dalam `IngestEventsRequest`. Tingkat peristiwa: Gunakan kolom `destination_references` pada objek `Event`. Tambahkan entri untuk menentukan tujuan dari daftar `destinations` yang akan menerima peristiwa. Untuk mengetahui informasi selengkapnya tentang cara menentukan `Destination` dan menentukan ID tujuan produk, lihat Mengonfigurasi tujuan dan header.
`id`	`transaction_id`	Nilai ini digunakan untuk menghapus duplikat peristiwa konversi. Pelajari lebih lanjut.
`timestamp`	`event_timestamp`	Wajib. ECAPI menggunakan format epoch Unix (integer) untuk stempel waktu. Saat memetakan ke Data Manager API, kolom `event_timestamp` harus dikonversi ke salah satu format berikut: Jika menggunakan format JSON, tetapkan ke nilai dalam format RFC 3339. Jika menggunakan buffer protokol, gunakan `Timestamp` dan tetapkan kolom `seconds` dan (opsional) `nanoseconds`. Lihat Format stempel waktu untuk mengetahui detailnya.
`event_type` / `custom_event`	`event_name`	Nama ini dapat berupa nama peristiwa yang direkomendasikan (misalnya, `purchase`) atau nama peristiwa kustom. Lihat Nama peristiwa standar untuk mengetahui detailnya.
`user_data`	`user_data`	Memetakan ke objek `UserData`, yang menerima daftar objek `UserIdentifier`.
`value`	`conversion_value`	Dipetakan langsung sebagai ganda atau float yang merepresentasikan nilai uang konversi.
`currency_code`	`currency`	Dipetakan ke kode mata uang tiga huruf huruf besar (misalnya, `USD`).
`source`	`event_source`	Ditetapkan ke nilai dari enum EventSource.
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	Item tingkat transaksi dapat dipetakan ke array `cart_data.items` dalam objek `CartData`. Data Manager API mendukung beberapa kolom Merchant Center opsional untuk produk yang ada di akun Merchant Center. Jika tujuan Anda adalah tindakan konversi Google Ads, Anda juga dapat menyertakan parameter kustom tambahan di kolom `custom_variables` sebagai daftar objek `CustomVariable`. Jika tujuan Anda adalah aliran data Google Analytics, Anda dapat menyertakan parameter peristiwa tambahan di kolom `additional_event_parameters` sebagai daftar objek `AdditionalEventParameter`.
`ext`	Tidak ada ekuivalen

Pemetaan objek data pengguna

Di Data Manager API, kolom user_data pada objek Event menerima objek UserData. Objek ini mengharapkan daftar objek UserIdentifier, yang dapat berisi ID pengguna individual seperti alamat email, nomor telepon, atau komponen alamat.

ECAPI (`user_data`)	Data Manager API (`Event`)	Catatan
`customer_identifier`	`user_id` (Google Analytics)	Untuk peristiwa Google Analytics, kolom `user_id` mewakili User-ID. Data Manager API tidak mendukung kolom ID pelanggan generik untuk tujuan lainnya.
`uids`	Tidak ada ekuivalen	Data Manager API tidak mendukung array `uids` terstruktur yang berisi jenis dan domain agen.
`customer_segments`	`user_properties`	Peta ke `UserProperties` di `Event`.
`email_address`	`user_data.user_identifiers[].email_address`	Disetel ke alamat email yang diformat dan di-hash. Anda juga dapat mengenkripsi alamat email yang di-hash.
`phone_numbers`	`user_data.user_identifiers[].phone_number`	Disetel ke nomor telepon yang diformat dan di-hash. Anda juga dapat mengenkripsi nomor telepon yang di-hash.
`utcoffset`	Tidak ada ekuivalen	Jika menggunakan format JSON, Anda dapat menentukan selisih zona waktu langsung dalam string `event_timestamp` RFC 3339. Jika menggunakan buffer protokol, Anda dapat menggunakan fungsi utilitas seperti `Timestamps.parse(String)` untuk menangani konversi zona waktu ke detik dan nano. Lihat Format stempel waktu untuk mengetahui detailnya.
`address`	`user_data.user_identifiers[].address`	Memetakan ke objek `AddressInfo`. Lihat Pemetaan objek alamat.
`gpp_string`	Tidak ada ekuivalen	Izin harus dipetakan ke objek `Consent` tingkat permintaan atau tingkat peristiwa. Lihat Ringkasan privasi dan izin.
`gpp_sid`	Tidak ada ekuivalen	Izin harus dipetakan ke objek `Consent` tingkat permintaan atau tingkat peristiwa. Lihat Ringkasan privasi dan izin.
`mmt_only`	Tidak ada ekuivalen
`click_id`	`ad_identifiers.gclid`	Petakan ke ID Klik Google (`gclid`). Lihat `AdIdentifiers` untuk mengetahui detail selengkapnya.
`impression_id`	`ad_identifiers.impression_id`	Lihat `AdIdentifiers` untuk mengetahui detail selengkapnya.
`event_ip_address`	`event_device_info.ip_address`	Lihat `DeviceInfo` untuk mengetahui kolom yang tersedia.
`event_user_agent`	`event_device_info.user_agent`	Lihat `DeviceInfo` untuk mengetahui kolom yang tersedia.
`ifa`	`ad_identifiers.mobile_device_id`	Dipetakan ke ID seluler untuk pengiklan (IDFA di iOS, AdID di Android). Lihat `AdIdentifiers` untuk mengetahui detail selengkapnya.
`landing_ip_address`	`ad_identifiers.landing_page_device_info.ip_address`	Lihat `DeviceInfo` untuk mengetahui kolom yang tersedia.
`landing_user_agent`	`ad_identifiers.landing_page_device_info.user_agent`	Lihat `DeviceInfo` untuk mengetahui kolom yang tersedia.
`age_range`	Tidak ada ekuivalen
`gender`	Tidak ada ekuivalen
`ext`	Tidak ada ekuivalen

Pemetaan objek alamat

ECAPI (`address`)	Data Manager API (`AddressInfo`)	Catatan
`first_name`	`given_name`	Memetakan ke kolom `given_name` di `AddressInfo`. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut alamat yang di-hash.
`last_name`	`family_name`	Memetakan ke kolom `family_name` di `AddressInfo`. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut alamat yang di-hash.
`street`	Tidak ada ekuivalen	Tidak didukung di Data Manager API
`city`	Tidak ada ekuivalen	Tidak didukung di Data Manager API
`state`	Tidak ada ekuivalen	Tidak didukung di Data Manager API
`country_code`	`region_code`	Jangan membuat hash. Memetakan ke kolom `region_code` di `AddressInfo`. Ikuti panduan pemformatan.
`postal_code`	`postal_code`	Jangan membuat hash. Memetakan ke kolom `postal_code` di `AddressInfo`. Ikuti panduan pemformatan.
`address_type`	Tidak ada ekuivalen	Tidak didukung di Data Manager API
`ext`	Tidak ada ekuivalen

Pemetaan objek item

ECAPI (`item`)	Data Manager API (`Item`)	Catatan
`id`	`item_id`	Wajib untuk peristiwa Google Analytics. Disetel ke ID unik standar untuk item.
Tidak ada ekuivalen	`merchant_product_id`	Wajib untuk konversi Floodlight dan konversi Google Ads dengan data keranjang. Disetel ke ID produk dalam akun Merchant Center.
`name`	`additional_item_parameters`	Memetakan sebagai `item_name` dalam daftar `additional_item_parameters`.
`price`	`unit_price`
`discount`	`additional_item_parameters` atau `custom_variables`	Petakan sebagai `discount` di `additional_item_parameters` (untuk Google Analytics) atau sebagai variabel kustom di `custom_variables` (untuk Google Ads).
`quantity`	`quantity`	Konversi nilai `float` menjadi bilangan bulat (`int64`).
`brand`	`additional_item_parameters`	Memetakan sebagai `item_brand` dalam daftar `additional_item_parameters`.
`affiliation`	`additional_item_parameters`	Memetakan sebagai `affiliation` dalam daftar `additional_item_parameters`.
`category`	`additional_item_parameters`	Memetakan sebagai `item_category` dalam daftar `additional_item_parameters`.
`cattax`	Tidak ada ekuivalen
`item_coupon`	`additional_item_parameters`	Memetakan sebagai `coupon` dalam daftar `additional_item_parameters`.
`item_list_id`	`additional_item_parameters`	Memetakan sebagai `item_list_id` dalam daftar `additional_item_parameters`.
`item_list_name`	`additional_item_parameters`	Memetakan sebagai `item_list_name` dalam daftar `additional_item_parameters`.
`item_item_variant`	`additional_item_parameters`	Memetakan sebagai `item_variant` dalam daftar `additional_item_parameters`.
`item_location_id`	`additional_item_parameters`	Peta sebagai `location_id` di `additional_item_parameters`.
`ext`	Tidak ada ekuivalen

Nama peristiwa standar

Peristiwa standar ECAPI sangat sesuai dengan konvensi penamaan Google Analytics.

Jika Anda mengirim peristiwa ke aliran data Google Analytics, kolom event_name wajib diisi.
Lihat referensi peristiwa yang direkomendasikan Google Analytics untuk kolom, parameter, dan contoh permintaan penyerapan Data Manager API terkait untuk setiap peristiwa.
Anda juga dapat mengirim Peristiwa kustom asalkan mengikuti Aturan penamaan peristiwa.

Sebagian besar peristiwa standar ECAPI (seperti purchase, add_to_cart, begin_checkout, search, dan refund) memiliki nama peristiwa yang sama dengan peristiwa yang direkomendasikan Google Analytics. Namun, ada beberapa pengecualian saat Google Analytics menggunakan bentuk kini, bukan bentuk lampau:

viewed_item dipetakan ke view_item
viewed_item_list dipetakan ke view_item_list
viewed_cart dipetakan ke view_cart

Contoh permintaan

Tab berikut menunjukkan perbandingan antara payload peristiwa konversi ECAPI dan representasinya sebagai IngestEventsRequest API Pengelola Data yang valid.

ECAPI

Berikut adalah contoh payload JSON yang sesuai dengan spesifikasi ECAPI.

{
  "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

Berikut contoh IngestEventsRequest untuk data peristiwa yang diformat, di-hash, dan dienkode. Hal ini ditujukan untuk tujuan Google Ads, seperti yang ditunjukkan oleh jenis akun GOOGLE_ADS di tujuan.

{
  "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
          }
        ]
      }
    }
  ]
}