Trang này được dịch bởi Cloud Translation API.

Gửi sự kiện

Bạn có thể xem hướng dẫn bắt đầu nhanh này để làm quen với việc gửi dữ liệu sự kiện.

Sử dụng Data Manager API cho một trong hai trường hợp sau:

Gửi lượt chuyển đổi của thẻ Google Ads hoặc sự kiện chính của Google Analytics dưới dạng một nguồn dữ liệu bổ sung cho lượt chuyển đổi của thẻ, để tối đa hoá tín hiệu tương tác với quảng cáo, đồng thời củng cố dữ liệu và hiệu suất tổng thể.

Tính năng này chỉ dành cho những tài khoản có trong danh sách cho phép. Điền vào biểu mẫu nếu bạn muốn thêm tài khoản Google Ads hoặc tài sản Google Analytics.

Lưu ý: Dữ liệu từ nguồn dữ liệu bổ sung mà bạn kết nối sẽ không được chuyển vào chiến lược đặt giá thầu dựa trên lượt chuyển đổi trong thời gian dùng thử 14 ngày. Điều này không áp dụng cho nguồn dữ liệu thẻ Google hiện có của bạn.
Gửi dữ liệu sự kiện cho lượt chuyển đổi ngoại tuyến hoặc lượt chuyển đổi nâng cao cho khách hàng tiềm năng trên Google Ads.

Chọn phiên bản hướng dẫn mà bạn muốn xem:

Trong hướng dẫn bắt đầu nhanh này, bạn sẽ hoàn tất các bước sau:

Chuẩn bị một Destination để nhận dữ liệu sự kiện.
Chuẩn bị dữ liệu sự kiện để gửi.
Tạo một yêu cầu IngestionService cho các sự kiện.
Gửi yêu cầu bằng Google APIs Explorer.
Tìm hiểu về các phản hồi thành công và không thành công.

Chuẩn bị đích đến

Trước khi có thể gửi dữ liệu, bạn cần chuẩn bị ít nhất một Destination cho dữ liệu. Sau đây là một Destination mẫu để bạn sử dụng:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Dưới đây là các trường của Destination:

operatingAccount

Tài khoản nhận các sự kiện.

Đối với các sự kiện được gửi dưới dạng một nguồn dữ liệu bổ sung, tài khoản hoạt động có thể là tài khoản Google Ads hoặc tài sản Google Analytics. Đặt accountType thành GOOGLE_ADS hoặc GOOGLE_ANALYTICS_PROPERTY, rồi đặt accountId thành mã khách hàng Google Ads hoặc mã tài sản Google Analytics. Nếu accountType là GOOGLE_ANALYTICS_PROPERTY, thì thông tin đăng nhập của yêu cầu phải dành cho người dùng Google Analytics có vai trò Người chỉnh sửa hoặc Quản trị viên đối với tài sản.

Đối với lượt chuyển đổi ngoại tuyến và lượt chuyển đổi nâng cao cho khách hàng tiềm năng, tài khoản hoạt động phải là tài khoản Google Ads, vì vậy, hãy đặt accountType thành GOOGLE_ADS và đặt accountId thành mã khách hàng Google Ads.

loginAccount

Tài khoản mà người dùng có thông tin đăng nhập có quyền truy cập.

Nếu thông tin xác thực OAuth của bạn là dành cho người dùng có quyền truy cập vào tài khoản người quản lý Google Ads có operatingAccount là một trong các tài khoản phụ, thì bạn bắt buộc phải có loginAccount. Đặt accountId của loginAccount thành mã nhận dạng của tài khoản người quản lý và đặt accountType của loginAccount thành GOOGLE_ADS.

Nếu thông tin đăng nhập OAuth của bạn là dành cho người dùng có quyền truy cập trực tiếp vào operatingAccount, thì bạn không cần đặt loginAccount và thông tin này sẽ mặc định là operatingAccount. Tuy nhiên, bạn nên đặt loginAccount thành cùng một accountId và accountType như operatingAccount. Điều này giúp tránh các vấn đề nếu nhóm tài khoản mà người dùng có thể truy cập thay đổi.

productDestinationId

Mã nhận dạng của thực thể trong operatingAccount nhận các sự kiện.

Đối với các sự kiện được gửi dưới dạng một nguồn dữ liệu bổ sung, productDestinationId phải là mã nhận dạng của một lượt chuyển đổi trên Google Ads có type được đặt thành WEBPAGE hoặc mã đo lường của một luồng dữ liệu web trên Google Analytics. Bạn không thể gửi sự kiện dưới dạng một nguồn dữ liệu bổ sung đến luồng ứng dụng iOS hoặc ứng dụng Android của Google Analytics.

Đối với lượt chuyển đổi ngoại tuyến hoặc lượt chuyển đổi nâng cao cho khách hàng tiềm năng, productDestinationId phải là mã nhận dạng của một hành động chuyển đổi trên Google Ads có type được đặt thành UPLOAD_CLICKS.

Ví dụ trong hướng dẫn này cho thấy cách tạo một yêu cầu gửi mọi sự kiện đến cùng một đích đến. Nếu bạn muốn gửi sự kiện cho nhiều đích đến trong cùng một yêu cầu, hãy xem bài viết gửi sự kiện cho nhiều đích đến.

Chuẩn bị dữ liệu sự kiện

Hãy xem xét dữ liệu sự kiện sau. Mỗi bảng tương ứng với một sự kiện chuyển đổi. Mỗi sự kiện chuyển đổi đều có dấu thời gian của sự kiện, hành động chuyển đổi và giá trị lượt chuyển đổi.

Mỗi sự kiện có thể có giá trị nhận dạng quảng cáo, chẳng hạn như gclid, hoặc giá trị nhận dạng người dùng, chẳng hạn như địa chỉ email, số điện thoại và thông tin địa chỉ. Một sự kiện cũng có thể có:

Thông tin về người dùng được đánh giá tại thời điểm diễn ra sự kiện, chẳng hạn như giá trị của khách hàng hoặc liệu họ là khách hàng mới, khách hàng cũ hay khách hàng tương tác lại.
Dữ liệu giỏ hàng.
Thông số sự kiện hoặc thuộc tính người dùng bổ sung cho một đích đến, chẳng hạn như client_id hoặc user_id cho Google Analytics.

Sau đây là dữ liệu sự kiện:

Sự kiện 1

Sự kiện 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Sự kiện 2

Sự kiện số 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

Định dạng dữ liệu

Định dạng các trường theo quy định trong hướng dẫn định dạng. Sau đây là dữ liệu sự kiện sau khi định dạng:

Sự kiện 1

Sự kiện 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Sự kiện 2

Sự kiện số 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

Băm và mã hoá dữ liệu

Ngoài ra, địa chỉ email, tên và họ được định dạng phải được băm bằng thuật toán SHA-256 và được mã hoá bằng phương thức mã hoá hex hoặc Base64. Dưới đây là dữ liệu sự kiện sau khi định dạng, băm và mã hoá bằng cách sử dụng mã hoá thập lục phân:

Sự kiện 1

Sự kiện 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Sự kiện 2

Sự kiện số 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Mặt hàng trong giỏ hàng
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

Chuyển đổi dữ liệu thành các đối tượng `Event`

Chuyển đổi dữ liệu đã băm và được định dạng của mỗi sự kiện thành một Event. Điền thông tin vào các trường sau đây như hướng dẫn:

Đặt eventTimestamp thành thời gian xảy ra sự kiện.

Các sự kiện cho Google Analytics phải có eventTimestamp trong vòng 72 giờ qua.

Đặt các trường bắt buộc cho trường hợp sử dụng của bạn.

Trường hợp sử dụng	Giá trị nhận dạng	`transactionId`	`eventSource`
Lượt chuyển đổi ngoại tuyến hoặc lượt chuyển đổi nâng cao cho khách hàng tiềm năng	Bắt buộc. Đặt ít nhất một trong những thông tin sau: `adIdentifiers` với ít nhất một trong các giá trị `gclid`, `gbraid`, `wbraid` hoặc `sessionAttributes` được đặt `userData`	Không bắt buộc	Bắt buộc. Đặt thành một trong các giá trị enum cho `EventSource`.
Sự kiện được gửi dưới dạng một nguồn dữ liệu bổ sung đến một đích đến trên Google Ads	Bắt buộc. Đặt ít nhất một trong những thông tin sau: `adIdentifiers` với ít nhất một trong các giá trị `gclid`, `gbraid` hoặc `wbraid` được đặt `userData`	Bắt buộc	Không bắt buộc. Nếu được đặt, phải là `WEB`.
Sự kiện được gửi dưới dạng một nguồn dữ liệu bổ sung đến một đích đến Google Analytics	Bắt buộc. Đặt ít nhất một trong những thông tin sau: `clientId` `adIdentifiers` với `gclid` lượt tập `userData`	Bắt buộc	Không bắt buộc. Nếu được đặt, phải là `WEB`.

Điền sẵn mọi trường khác mà bạn có giá trị cho sự kiện. Tham khảo tài liệu tham khảo Event để biết danh sách đầy đủ các trường có sẵn.

Lưu ý: Google Ads và Google Analytics không hỗ trợ tính năng so khớp địa chỉ IP cho người dùng cuối ở Khu vực kinh tế Châu Âu (EEA), Vương quốc Anh (UK) hoặc Thuỵ Sĩ (CH). Thêm logic để loại trừ có điều kiện việc chia sẻ địa chỉ IP của người dùng ở những khu vực này và đảm bảo rằng bạn cung cấp cho người dùng thông tin rõ ràng và đầy đủ về dữ liệu mà bạn thu thập trên các trang web, ứng dụng và tài sản khác của mình, đồng thời nhận được sự đồng ý khi luật pháp hoặc bất kỳ chính sách nào hiện hành của Google yêu cầu. Hãy xem trang Giới thiệu về tính năng nhập lượt chuyển đổi ngoại tuyến để biết thêm thông tin chi tiết.

Thêm thông tin Google Analytics

Nếu đích đến của một sự kiện được gửi dưới dạng nguồn dữ liệu bổ sung bao gồm một tài sản Google Analytics, hãy điền sẵn các trường sau như được chỉ ra:

eventName

Bắt buộc. Tên của sự kiện Google Analytics.

transactionId

Bắt buộc . Giá trị nhận dạng duy nhất của sự kiện.

Ít nhất một giá trị nhận dạng

Bạn phải đặt ít nhất một trong các trường sau:

clientId: Giá trị nhận dạng duy nhất cho một phiên bản người dùng của ứng dụng web. Xem phần Gửi sự kiện đến Measurement Protocol.
adIdentifiers.gclid: Mã lượt nhấp của Google.
userData: Giá trị nhận dạng cho người dùng, chẳng hạn như địa chỉ email, số điện thoại hoặc thông tin địa chỉ.

destinationReferences

Bắt buộc nếu danh sách destinations ở cấp yêu cầu chứa nhiều hơn một Destination Google Analytics. Thêm một mục vào destinationReferences để chỉ định đích đến nào trong Google Analytics sẽ nhận sự kiện. Hãy xem bài viết gửi sự kiện đến nhiều đích đến để biết thêm thông tin về các đích đến tham chiếu.

Nếu bạn không đặt destinationReferences hoặc có nhiều mục đề cập đến đích đến Google Analytics, thì Data Manager API sẽ từ chối sự kiện này kèm theo lỗi MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

Không bắt buộc. User-ID cho người dùng.

additionalEventParameters

Không bắt buộc, nhưng nên dùng. Điền vào danh sách này bằng mọi thông số sự kiện Google Analytics chưa được ghi nhận trong các trường Event khác. Các tham số này có thể bao gồm các tham số bổ sung được đề xuất từ sự kiện purchase hoặc các tham số khác mà bạn muốn thu thập. Sử dụng tên tham số Google Analytics cho parameterName của EventParameter.

Ví dụ: nếu bạn có thuế liên kết với một giao dịch, hãy thêm một mục vào additionalEventParameters với parameterName được đặt thành tax và value được đặt thành chi phí thuế.

Bạn không nên thêm các mục cho thông số sự kiện transactionId, currency hoặc value Google Analytics. Thay vào đó, hãy điền transactionId, currency và conversionValue của Event, các thuộc tính này sẽ được ưu tiên hơn mọi mục trong additionalEventParameters.

Thêm dữ liệu giỏ hàng cho sự kiện mua hàng

Điền thông tin về các mặt hàng đã mua vào trường cartData của Event. Đối với mỗi mặt hàng đã mua, hãy thêm một đối tượng Item vào danh sách items của CartData và điền sẵn các trường sau như được chỉ định:

itemId

Bắt buộc. Giá trị nhận dạng riêng biệt của mặt hàng.

unitPrice

Bắt buộc. Giá đơn vị chưa bao gồm thuế, phí vận chuyển và các khoản chiết khấu ở phạm vi sự kiện (cấp giao dịch).

Nếu mặt hàng có chiết khấu theo mặt hàng, hãy sử dụng giá theo đơn vị chiết khấu. Ví dụ: nếu một mặt hàng có đơn giá là 27.67 và chiết khấu theo đơn vị là 6.66, thì hãy đặt unitPrice thành 21.01.

quantity

Bắt buộc. Số lượng đơn vị đã mua cho mặt hàng cụ thể này.

additionalItemParameters

Điền vào danh sách này bằng mọi tham số ở phạm vi mặt hàng không được ghi lại trong các trường Item khác. Sử dụng tên thông số mặt hàng Google Analytics cho parameterName của ItemParameter.

Ví dụ: nếu bạn có thương hiệu và danh mục cho một mặt hàng, hãy thêm một mục vào additionalItemParameters của mặt hàng với parameterName được đặt thành item_brand và value được đặt thành tên thương hiệu, đồng thời thêm một mục khác với parameterName được đặt thành item_category và value được đặt thành danh mục của mặt hàng.

Bạn không nên thêm mục nhập cho các thông số mặt hàng quantity, price hoặc item_id Google Analytics. Thay vào đó, hãy điền sẵn itemId, unitPrice và quantity của Item. Các thuộc tính này sẽ được ưu tiên hơn mọi mục trong additionalItemParameters.

Sau đây là một Event mẫu cho dữ liệu đã được định dạng, băm và mã hoá từ sự kiện thứ hai, cùng với dữ liệu bổ sung cho Google Analytics:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

Tạo nội dung yêu cầu

Kết hợp Destination và Events cho nội dung yêu cầu:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

Cập nhật phần giữ chỗ trong nội dung, chẳng hạn như OPERATING_ACCOUNT_ID và PRODUCT_DESTINATION_ID bằng các giá trị cho tài khoản và đích đến của bạn.
Đặt validateOnly thành true để xác thực yêu cầu mà không áp dụng các thay đổi. Khi bạn đã sẵn sàng áp dụng các thay đổi, hãy đặt validateOnly thành false.
Xin lưu ý rằng ví dụ này không sử dụng hoạt động mã hoá.

Gửi yêu cầu

Sao chép nội dung yêu cầu bằng nút sao chép ở trên cùng bên phải của mẫu.
Nhấp vào nút API trên thanh công cụ.
Dán nội dung yêu cầu đã sao chép vào hộp Nội dung yêu cầu.
Nhấp vào nút Thực thi, hoàn tất lời nhắc uỷ quyền và xem xét phản hồi.

Phản hồi thành công

Yêu cầu thành công sẽ trả về một phản hồi có chứa một đối tượng requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Ghi lại requestId được trả về để bạn có thể truy xuất thông tin chẩn đoán khi mỗi đích đến trong yêu cầu được xử lý.

Phản hồi thất bại

Yêu cầu không thành công sẽ dẫn đến mã trạng thái phản hồi lỗi, chẳng hạn như 400 Bad Request và phản hồi có thông tin chi tiết về lỗi.

Ví dụ: emailAddress chứa một chuỗi văn bản thuần tuý thay vì một giá trị được mã hoá hex sẽ tạo ra phản hồi sau:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Một emailAddress không được băm và chỉ được mã hoá theo hệ thập lục phân sẽ tạo ra phản hồi sau:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Gửi sự kiện cho nhiều đích đến

Nếu dữ liệu của bạn chứa các sự kiện cho nhiều đích đến, thì bạn có thể gửi các sự kiện đó trong cùng một yêu cầu bằng cách sử dụng thông tin tham chiếu về đích đến.

Ví dụ: nếu bạn có một sự kiện cho mã hành động chuyển đổi 123456789 và một sự kiện khác cho mã hành động chuyển đổi 777111122, hãy gửi cả hai sự kiện trong một yêu cầu bằng cách đặt reference của mỗi Destination. reference do người dùng xác định. Yêu cầu duy nhất là mỗi Destination phải có một reference riêng biệt. Sau đây là danh sách destinations đã sửa đổi cho yêu cầu:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

Đặt destinationReferences của mỗi Event để gửi đến một hoặc nhiều đích đến cụ thể. Ví dụ: sau đây là một Event chỉ dành cho Destination đầu tiên, nên danh sách destinationReferences của Event này chỉ chứa reference của Destination đầu tiên:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

Trường destinationReferences là một danh sách, vì vậy bạn có thể chỉ định nhiều đích đến cho một sự kiện. Nếu bạn không đặt destinationReferences của một Event, thì Data Manager API sẽ gửi sự kiện đến tất cả các đích đến trong yêu cầu.

Nếu một sự kiện có nhiều đích đến, Data Manager API sẽ gửi các trường liên quan đến từng đích đến. Ví dụ: nếu một sự kiện có đích đến là Google Ads và đích đến là Google Analytics, thì API sẽ bao gồm các trường Google Analytics như clientId hoặc eventName khi gửi sự kiện đến đích đến Google Analytics, đồng thời bao gồm các trường Google Ads như customVariables khi gửi sự kiện đến đích đến Google Ads.

Các bước tiếp theo

Định cấu hình quy trình xác thực và thiết lập môi trường bằng một thư viện ứng dụng.
Tìm hiểu về các yêu cầu về định dạng, băm và mã hoá đối với từng loại dữ liệu.
Tìm hiểu cách mã hoá dữ liệu người dùng.
Tìm hiểu cách truy xuất thông tin chẩn đoán cho các yêu cầu của bạn.
Tìm hiểu về các phương pháp hay nhất.
Tìm hiểu về hạn mức và cuota.

Tổng quan về sự kiện

Gửi sự kiện Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Chuẩn bị đích đến

Chuẩn bị dữ liệu sự kiện

Sự kiện 1

Sự kiện 2

Định dạng dữ liệu

Sự kiện 1

Sự kiện 2

Băm và mã hoá dữ liệu

Sự kiện 1

Sự kiện 2

Chuyển đổi dữ liệu thành các đối tượng Event

Thêm thông tin Google Analytics

Thêm dữ liệu giỏ hàng cho sự kiện mua hàng

Tạo nội dung yêu cầu

Gửi yêu cầu

Phản hồi thành công

Phản hồi thất bại

Gửi sự kiện cho nhiều đích đến

Các bước tiếp theo

Gửi sự kiện

Chuyển đổi dữ liệu thành các đối tượng `Event`