Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

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 yang 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)	Mengandalkan `transaction_id`
Perutean peristiwa	Kolom `data_set_id` dalam payload peristiwa menunjukkan tujuan data.	Kolom `destinations` permintaan menentukan tujuan untuk peristiwa. Data Manager API juga mendukung perutean peristiwa ke beberapa tujuan dalam satu permintaan. Lihat Mengonfigurasi tujuan dan header 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). Tetapkan kolom izin 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 menjadi 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)	Anda dapat menentukan tujuan di tingkat berikut: Tingkat permintaan (Wajib): Tentukan daftar `destinations` dalam `IngestEventsRequest`. Tingkat peristiwa (Opsional): Gunakan kolom `destination_references` pada objek `Event`. Tambahkan entri untuk menentukan tujuan mana dari daftar `destinations` yang harus menerima peristiwa. Untuk mengetahui informasi selengkapnya tentang cara menentukan `Destination` dan menentukan ID tujuan produk, lihat Mengonfigurasi tujuan dan header.
`id`	`transaction_id`	Menghapus duplikat peristiwa konversi. Lihat Cara Google menangani data multi-sumber dalam panduan Mengirim peristiwa untuk Google Ads, Google Analytics, dan Floodlight.
`timestamp`	`event_timestamp`	Wajib. ECAPI menggunakan format epoch Unix (bilangan bulat) untuk stempel waktu. Saat memetakan ke Data Manager API, konversikan kolom `event_timestamp` ke salah satu format berikut: Jika menggunakan format JSON, tetapkan ke nilai dalam format RFC 3339. Jika menggunakan buffering 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`	Dipetakan ke objek `UserData`, yang menerima daftar objek `UserIdentifier`.
`value`	`conversion_value`	Petakan langsung sebagai double atau float yang mewakili nilai uang konversi.
`currency_code`	`currency`	Petakan ke kode mata uang tiga huruf dalam huruf besar (misalnya, `USD`).
`source`	`event_source`	Tetapkan ke nilai dari enum EventSource.
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	Petakan item tingkat transaksi 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 tujuannya 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. Ini memerlukan 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 umum untuk tujuan lain.
`uids`	Tidak ada ekuivalen	Data Manager API tidak mendukung array `uids` terstruktur yang berisi jenis dan domain agen.
`customer_segments`	`user_properties`	Petakan ke `UserProperties` di `Event`.
`email_address`	`user_data.user_identifiers[].email_address`	Tetapkan 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`	Tetapkan 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`	Dipetakan ke objek `AddressInfo`. Lihat Pemetaan objek alamat.
`gpp_string`	Tidak ada ekuivalen	Petakan izin ke objek `Consent` tingkat permintaan atau tingkat peristiwa. Lihat Ringkasan privasi dan izin.
`gpp_sid`	Tidak ada ekuivalen	Petakan izin 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`	Dipetakan ke kolom `given_name` di `AddressInfo`. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut yang di-hash dari sebuah alamat.
`last_name`	`family_name`	Dipetakan ke kolom `family_name` di `AddressInfo`. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut yang di-hash dari sebuah alamat.
`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 lakukan hashing. Memetakan ke kolom `region_code` di `AddressInfo`. Ikuti panduan pemformatan.
`postal_code`	`postal_code`	Jangan lakukan hashing. 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. Tetapkan 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`	Konversikan nilai `float` menjadi bilangan bulat (`int64`).
`brand`	`additional_item_parameters`	Petakan sebagai `item_brand` dalam daftar `additional_item_parameters`.
`affiliation`	`additional_item_parameters`	Petakan sebagai `affiliation` dalam daftar `additional_item_parameters`.
`category`	`additional_item_parameters`	Petakan sebagai `item_category` dalam daftar `additional_item_parameters`.
`cattax`	Tidak ada ekuivalen
`item_coupon`	`additional_item_parameters`	Petakan sebagai `coupon` dalam daftar `additional_item_parameters`.
`item_list_id`	`additional_item_parameters`	Petakan sebagai `item_list_id` dalam daftar `additional_item_parameters`.
`item_list_name`	`additional_item_parameters`	Petakan sebagai `item_list_name` dalam daftar `additional_item_parameters`.
`item_item_variant`	`additional_item_parameters`	Petakan 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 present tense, bukan past tense:

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 Data Manager API 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 adalah contoh IngestEventsRequest untuk data peristiwa yang diformat, di-hash, dan dienkode. Jenis akun GOOGLE_ADS di tujuan menunjukkan bahwa permintaan menargetkan tujuan Google Ads:

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