Mối liên kết quy cách ECAPI

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ở, không phụ thuộc vào nền tảng, giúp xác định cấu trúc của các sự kiện và lượt chuyển đổi liên quan đến hoạt động tiếp thị.

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 Trường data_set_id trong tải trọng sự kiện cho biết đích đến của dữ liệu. Trường destinations của yêu cầu xác định đí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.

Hãy xem bài viết Định cấu hình đích đến và tiêu đề để 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ú pháp chuỗi đồng ý của Nền tảng quyền riêng tư trên toàn cầu (GPP). Đặt các trường về sự đồng ý trong đối tượng Consent.

Bạn có thể đặt trạng thái đồ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 ý cho từng sự kiện).

Liên kết trường cấu trúc

Các bảng liên kết sau đây xác định cách các trường riêng lẻ trong thông số kỹ thuật của ECAPI chuyển thành các trường được 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
  • destinations[].product_destination_id (Cấp yêu cầu)
  • destination_references (Cấp sự kiện)
 Bạn có thể xác định đích đến ở các cấp sau:
  • Cấp yêu cầu (Bắt buộc): Chỉ định danh sách destinations trong IngestEventsRequest.
  • Cấp sự kiện (Không bắt buộc): Sử dụng trường destination_references trên đối tượng Event. Thêm một mục để chỉ định đích đến nào trong danh sách destinations sẽ nhận được sự kiện.

Để biết thêm thông tin về cách xác định Destination và xác định mã đích đến của sản phẩm, hãy xem bài viết Định cấu hình đích đến và tiêu đề.
id transaction_id Loại bỏ các sự kiện chuyển đổi trùng lặp. Xem bài viết Cách Google xử lý dữ liệu từ nhiều nguồn trong hướng dẫn Gửi sự kiện cho Google Ads, Google Analytics và Floodlight.
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 liên kết với Data Manager API, hãy chuyển đổi trường event_timestamp sang một trong các định dạng sau:
  • Nếu bạn sử dụng định dạng JSON, hãy đặt thành một giá trị ở định dạng RFC 3339.
  • Nếu sử dụng vùng đệm giao thức, hãy dùng Timestamp và đặt các trường seconds và nanoseconds (không bắt buộc).

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 phần Tên sự kiện chuẩn để biết thông tin chi tiết.
user_data user_data Liên kết với đối tượng UserData, chấp nhận danh sách đối tượng UserIdentifier.
value conversion_value Liên kết trực tiếp dưới dạng số thực có độ chính xác gấp đôi hoặc số thực có độ chính xác đơn đại diện cho giá trị bằng tiền của lượt chuyển đổi.
currency_code currency Ánh xạ đến mã 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ị trong enum EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Liên kết các mục ở 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 không bắt buộc của Merchant Center cho 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 khác 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 trong Google Analytics, trường user_id đại diện cho một Mã nhận dạng người dùng. Data Manager API không hỗ trợ các trường mã khách hàng chung 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 Ánh xạ tới 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 đã được đị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ờ trực tiếp trong chuỗi RFC 3339 event_timestamp.
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ờ thành 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 Liên kết với một đối tượng AddressInfo. Xem phần Liên kết đối tượng Địa chỉ.
gpp_string Không có phiên bản mới Ánh xạ 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 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 bài viết 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 Liên kết với giá trị 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 chi tiết.
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 đến 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 đến 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

Liên kết đố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 các sự kiện Google Analytics. Đặt thành giá trị nhận dạng riêng biệt, chuẩn 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ã sản phẩm trong tài khoản Merchant Center.
name additional_item_parameters Bản đồ là 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 đồ là 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 chuẩn

Sự kiện chuẩn của ECAPI rất phù hợp với quy ước đặt tên của Google Analytics.

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ệ mà Google Analytics sử dụng thì hiện tại thay vì thì quá khứ:

  • viewed_item liên kết với view_item

  • viewed_item_list liên kết với view_item_list

  • viewed_cart ánh xạ đến view_cart

Ví dụ về yêu cầu

Các thẻ sau đây cho thấy thông tin so sánh giữa tải trọng sự kiện chuyển đổi ECAPI và nội dung biểu thị của tải trọng đó dưới dạng một IngestEventsRequest hợp lệ của API Trình quản lý dữ liệu:

ECAPI

Dưới đây là tải trọng JSON mẫu tuân thủ thông số kỹ thuật của 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

Dưới đây là một IngestEventsRequest mẫu cho dữ liệu sự kiện đã được định dạng, băm và mã hoá. Loại tài khoản GOOGLE_ADS trong đích đến cho biết rằng yêu cầu nhắm đến một đích đến trên 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
          }
        ]
      }
    }
  ]
}