Hướng dẫn này giúp các nhà phát triển sử dụng quy cách IAB Tech Lab Event and Conversion API (ECAPI) liên kết dữ liệu sự kiện và lượt chuyển đổi của họ với giản đồ tiếp nhận sự kiện Data Manager API.
Tổng quan
ECAPI là một tiêu chuẩn dữ liệu nguồn mở, độc lập với nền tảng, được thiết kế để xác định cách các sự kiện và lượt chuyển đổi liên quan đến hoạt động tiếp thị được cấu trúc.
Bảng sau đây cung cấp thông tin tổng quan về cách các thuộc tính và nguyên tắc thiết kế chính của ECAPI so với Data Manager API.
| ECAPI | Data Manager API | |
|---|---|---|
| Loại bỏ trùng lặp | Dựa vào id (mã sự kiện) |
Dựa vào transaction_id |
| Định tuyến sự kiện | Đích đến của dữ liệu được biểu thị bằng trường data_set_id trong tải trọng sự kiện. |
Trường destinations của yêu cầu xác định(các) đích đến cho các sự kiện.
Data Manager API cũng hỗ trợ định tuyến các sự kiện đến nhiều đích đến trong một yêu cầu. Xem hướng dẫn về vị trí xuất hiện để biết thêm thông tin. |
| Các trường về quyền riêng tư và sự đồng ý | Chuỗi về sự đồng ý theo Nền tảng quyền riêng tư trên toàn cầu (GPP) |
Data Manager API không chấp nhận hoặc phân tích các chuỗi đồng ý theo Nền tảng quyền riêng tư trên toàn cầu (GPP). Bạn phải đặt các trường về sự đồng ý trong đối tượng Consent.
Bạn có thể đặt sự đồng ý ở cấp yêu cầu (áp dụng cho tất cả sự kiện trong yêu cầu) hoặc ở cấp sự kiện (cho phép bạn chỉ định các chế độ cài đặt về sự đồng ý khác nhau cho từng sự kiện). |
Liên kết trường kết cấu
Các bảng liên kết sau đây xác định cách các trường riêng lẻ trong quy cách ECAPI chuyển thành các trường mà Data Manager API chấp nhận.
Liên kết đối tượng sự kiện
ECAPI (event) |
Data Manager API (Event) |
Ghi chú |
|---|---|---|
data_set_id |
|
Có thể được xác định ở các cấp sau:
Để biết thêm thông tin về cách xác định Destination và xác định mã nhận dạng vị trí xuất hiện của sản phẩm, hãy xem phần Định cấu hình vị trí xuất hiện và tiêu đề.
|
id |
transaction_id |
Giá trị này được dùng để loại bỏ các sự kiện chuyển đổi trùng lặp. Tìm hiểu thêm. |
timestamp |
event_timestamp |
Bắt buộc. ECAPI sử dụng định dạng thời gian bắt đầu của hệ thống Unix (số nguyên) cho dấu thời gian.
Khi ánh xạ đến Data Manager API, trường event_timestamp phải được chuyển đổi thành một trong các định dạng sau:
Hãy xem phần Định dạng dấu thời gian để biết thông tin chi tiết. |
event_type/custom_event |
event_name |
Đây có thể là tên sự kiện được đề xuất (ví dụ: purchase) hoặc tên sự kiện tuỳ chỉnh. Hãy xem bài viết Tên sự kiện chuẩn để biết thông tin chi tiết. |
user_data |
user_data |
Ánh xạ đến đối tượng UserData, chấp nhận danh sách các đối tượng UserIdentifier. |
value |
conversion_value |
Ánh xạ trực tiếp dưới dạng số thực hoặc số thực dấu phẩy động biểu thị giá trị bằng tiền của lượt chuyển đổi. |
currency_code |
currency |
Liên kết đến mã đơn vị tiền tệ gồm 3 chữ cái viết hoa (ví dụ: USD). |
source |
event_source |
Đặt thành một giá trị từ enum EventSource. |
properties |
|
Bạn có thể liên kết các mặt hàng ở cấp giao dịch với mảng cart_data.items trong đối tượng CartData. Data Manager API hỗ trợ một số trường Merchant Center không bắt buộc đối với các sản phẩm có trong tài khoản Merchant Center.
Nếu đích đến là một hành động chuyển đổi trên Google Ads, bạn cũng có thể thêm các tham số tuỳ chỉnh khác vào trường custom_variables dưới dạng danh sách các đối tượng CustomVariable.
Nếu đích đến là một luồng dữ liệu Google Analytics, bạn có thể thêm các thông số sự kiện bổ sung vào trường additional_event_parameters dưới dạng danh sách các đối tượng AdditionalEventParameter.
|
ext |
Không có phiên bản mới |
Liên kết đối tượng dữ liệu người dùng
Trong Data Manager API, trường user_data trên đối tượng Event chấp nhận đối tượng UserData. Thao tác này dự kiến sẽ nhận được một danh sách các đối tượng UserIdentifier. Danh sách này có thể chứa các giá trị nhận dạng người dùng riêng lẻ, chẳng hạn như địa chỉ email, số điện thoại hoặc thành phần địa chỉ.
ECAPI (user_data) |
Data Manager API (Event) |
Ghi chú |
|---|---|---|
customer_identifier |
user_id (Google Analytics) |
Đối với các sự kiện Google Analytics, trường user_id đại diện cho User-ID. Data Manager API không hỗ trợ các trường mã nhận dạng chung của khách hàng cho những đích đến khác. |
uids |
Không có phiên bản mới | Data Manager API không hỗ trợ mảng uids có cấu trúc chứa các loại và miền của tác nhân. |
customer_segments |
user_properties |
Bản đồ đến UserProperties trên Event. |
email_address |
user_data.user_identifiers[].email_address |
Đặt thành địa chỉ email đã định dạng và băm. Bạn cũng có thể mã hoá địa chỉ email đã băm. |
phone_numbers |
user_data.user_identifiers[].phone_number |
Đặt thành số điện thoại đã định dạng và băm. Bạn cũng có thể mã hoá số điện thoại đã băm. |
utcoffset |
Không có phiên bản mới |
Nếu đang sử dụng định dạng JSON, bạn có thể chỉ định độ lệch múi giờ ngay trong chuỗi event_timestamp RFC 3339.
Nếu đang sử dụng vùng đệm giao thức, bạn có thể dùng các hàm tiện ích như Timestamps.parse(String) để xử lý việc chuyển đổi múi giờ sang giây và nano giây.
Hãy xem phần Định dạng dấu thời gian để biết thông tin chi tiết. |
address |
user_data.user_identifiers[].address |
Ánh xạ đến một đối tượng AddressInfo. Xem phần Ánh xạ đối tượng Địa chỉ. |
gpp_string |
Không có phiên bản mới | Bạn phải liên kết sự đồng ý với đối tượng Consent ở cấp yêu cầu hoặc cấp sự kiện. Xem Thông tin tổng quan về quyền riêng tư và sự đồng ý. |
gpp_sid |
Không có phiên bản mới | Bạn phải liên kết sự đồng ý với đối tượng Consent ở cấp yêu cầu hoặc cấp sự kiện. Xem Thông tin tổng quan về quyền riêng tư và sự đồng ý. |
mmt_only |
Không có phiên bản mới | |
click_id |
ad_identifiers.gclid |
Liên kết với mã lượt nhấp của Google (gclid). Hãy xem AdIdentifiers để biết thêm thông tin chi tiết. |
impression_id |
ad_identifiers.impression_id |
Hãy xem AdIdentifiers để biết thêm thông tin chi tiết. |
event_ip_address |
event_device_info.ip_address |
Hãy xem DeviceInfo để biết các trường có sẵn. |
event_user_agent |
event_device_info.user_agent |
Hãy xem DeviceInfo để biết các trường có sẵn. |
ifa |
ad_identifiers.mobile_device_id |
Ánh xạ đến mã nhận dạng trên thiết bị di động cho nhà quảng cáo (IDFA trên iOS, AdID trên Android). Hãy xem AdIdentifiers để biết thêm thông tin. |
landing_ip_address |
ad_identifiers.landing_page_device_info.ip_address |
Hãy xem DeviceInfo để biết các trường có sẵn. |
landing_user_agent |
ad_identifiers.landing_page_device_info.user_agent |
Hãy xem DeviceInfo để biết các trường có sẵn. |
age_range |
Không có phiên bản mới | |
gender |
Không có phiên bản mới | |
ext |
Không có phiên bản mới |
Ánh xạ đối tượng địa chỉ
ECAPI (address) |
Data Manager API (AddressInfo) |
Ghi chú |
|---|---|---|
first_name |
given_name |
Liên kết với trường given_name trong AddressInfo. Tuân thủ nguyên tắc định dạng và băm. Bạn cũng có thể mã hoá các thuộc tính đã băm của một địa chỉ. |
last_name |
family_name |
Liên kết với trường family_name trong AddressInfo. Tuân thủ nguyên tắc định dạng và băm. Bạn cũng có thể mã hoá các thuộc tính đã băm của một địa chỉ. |
street |
Không có phiên bản mới | Không được hỗ trợ trong Data Manager API |
city |
Không có phiên bản mới | Không được hỗ trợ trong Data Manager API |
state |
Không có phiên bản mới | Không được hỗ trợ trong Data Manager API |
country_code |
region_code |
Không băm. Liên kết với trường region_code trong AddressInfo. Tuân thủ nguyên tắc định dạng. |
postal_code |
postal_code |
Không băm. Liên kết với trường postal_code trong AddressInfo. Tuân thủ nguyên tắc định dạng. |
address_type |
Không có phiên bản mới | Không được hỗ trợ trong Data Manager API |
ext |
Không có phiên bản mới |
Ánh xạ đối tượng mặt hàng
ECAPI (item) |
Data Manager API (Item) |
Ghi chú |
|---|---|---|
id |
item_id |
Bắt buộc đối với sự kiện Google Analytics. Đặt thành giá trị nhận dạng chuẩn, duy nhất cho mặt hàng. |
| Không có phiên bản mới | merchant_product_id |
Bắt buộc đối với lượt chuyển đổi Floodlight và lượt chuyển đổi trên Google Ads có dữ liệu giỏ hàng. Đặt thành mã nhận dạng sản phẩm trong tài khoản Merchant Center. |
name |
additional_item_parameters |
Bản đồ dưới dạng item_name trong danh sách additional_item_parameters. |
price |
unit_price |
|
discount |
additional_item_parameters hoặc custom_variables |
Liên kết dưới dạng discount trong additional_item_parameters (đối với Google Analytics) hoặc dưới dạng biến tuỳ chỉnh trong custom_variables (đối với Google Ads). |
quantity |
quantity |
Chuyển đổi giá trị float thành số nguyên (int64). |
brand |
additional_item_parameters |
Bản đồ dưới dạng item_brand trong danh sách additional_item_parameters. |
affiliation |
additional_item_parameters |
Bản đồ dưới dạng affiliation trong danh sách additional_item_parameters. |
category |
additional_item_parameters |
Bản đồ dưới dạng item_category trong danh sách additional_item_parameters. |
cattax |
Không có phiên bản mới | |
item_coupon |
additional_item_parameters |
Bản đồ dưới dạng coupon trong danh sách additional_item_parameters. |
item_list_id |
additional_item_parameters |
Bản đồ dưới dạng item_list_id trong danh sách additional_item_parameters. |
item_list_name |
additional_item_parameters |
Bản đồ dưới dạng item_list_name trong danh sách additional_item_parameters. |
item_item_variant |
additional_item_parameters |
Bản đồ dưới dạng item_variant trong danh sách additional_item_parameters. |
item_location_id |
additional_item_parameters |
Bản đồ location_id ở additional_item_parameters. |
ext |
Không có phiên bản mới |
Tên sự kiện tiêu chuẩn
Sự kiện chuẩn ECAPI tuân thủ chặt chẽ quy ước đặt tên của Google Analytics.
- Nếu bạn đang gửi sự kiện đến một luồng dữ liệu Google Analytics, thì trường
event_namelà bắt buộc. - Hãy xem tài liệu tham khảo về các sự kiện được đề xuất của Google Analytics để biết các trường, thông số được liên kết và yêu cầu mẫu về việc nhận Data Manager API cho từng sự kiện.
- Bạn cũng có thể gửi Sự kiện tuỳ chỉnh miễn là các sự kiện đó tuân thủ Quy tắc đặt tên sự kiện.
Hầu hết sự kiện tiêu chuẩn ECAPI (chẳng hạn như purchase, add_to_cart, begin_checkout, search và refund) đều có cùng tên sự kiện với các sự kiện được Google Analytics đề xuất. Tuy nhiên, có một số trường hợp ngoại lệ khi Google Analytics sử dụng thì hiện tại thay vì thì quá khứ:
viewed_itemánh xạ đếnview_itemviewed_item_listánh xạ đếnview_item_listviewed_cartánh xạ đếnview_cart
Ví dụ về yêu cầu
Các thẻ sau đây cho thấy sự so sánh giữa tải trọng sự kiện chuyển đổi ECAPI và cách biểu thị tải trọng đó dưới dạng Data Manager API hợp lệ IngestEventsRequest.
ECAPI
Dưới đây là một tải trọng JSON mẫu tuân thủ quy cách 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
Sau đây là một IngestEventsRequest mẫu cho dữ liệu sự kiện đã được định dạng, băm và mã hoá. Đây là đích đến của Google Ads, như được chỉ ra bằng loại tài khoản GOOGLE_ADS trong đích đến.
{
"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
}
]
}
}
]
}