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.

Dữ liệu sự kiện là một nguồn dữ liệu bổ sung cho lượt chuyển đổi qua thẻ, giúp 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ể của bạn.

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

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

  1. Chuẩn bị một Destination để nhận dữ liệu sự kiện.
  2. Chuẩn bị dữ liệu sự kiện để gửi.
  3. Tạo một yêu cầu IngestionService cho các sự kiện.
  4. Gửi yêu cầu bằng Google APIs Explorer.
  5. 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ị cho một điểm đến

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

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • Đặt accountId của operatingAccount thành mã tài khoản Google Ads sẽ nhận dữ liệu sự kiện. product của operatingAccount phải là GOOGLE_ADS.

  • Đặt productDestinationId thành mã nhận dạng của hành động chuyển đổi cho các sự kiện. Hành động chuyển đổi phải là hành động chuyển đổi trên Google Ads có type được đặt thành WEBPAGE.

    Hướng dẫn này cho biết cách tạo một yêu cầu gửi mọi sự kiện đến cùng một hành động chuyển đổi. Nếu bạn muốn gửi sự kiện cho nhiều hành động chuyển đổi trong cùng một yêu cầu, hãy xem 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ỉ.

Dưới đây là dữ liệu của sự kiện đầu tiên:

Sự kiện 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045

Sau đây là dữ liệu của sự kiện thứ hai:

Sự kiện 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
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

Đị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 của sự kiện đầu tiên sau khi định dạng:

Sự kiện 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045

Sau đây là dữ liệu của sự kiện thứ hai sau khi định dạng:

Sự kiện 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
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

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 của sự kiện đầu tiên sau khi định dạng, băm và mã hoá bằng phương thức mã hoá thập lục phân:

Sự kiện 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045

Sau đây là dữ liệu của sự kiện thứ hai sau khi được định dạng, băm và mã hoá bằng cách sử dụng phương thức mã hoá hex:

Sự kiện 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4
given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

Chuyển đổi dữ liệu thành 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 các trường bắt buộc sau:

  • event_timestamp: Thời gian diễn ra sự kiện.
  • transaction_id: Giá trị nhận dạng duy nhất cho sự kiện.
  • event_source: Nguồn của sự kiện. Nếu được chỉ định, thì giá trị này phải là WEB.
  • ad_identifiers hoặc user_data: Sự kiện phải có mã nhận dạng quảng cáo hoặc dữ liệu người dùng. Hãy gửi cả hai nếu bạn có cả hai cho sự kiện.

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

Sau đây là một Event mẫu cho dữ liệu đã định dạng, băm và mã hoá từ sự kiện thứ hai:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
            }
         }
      ]
   }
}

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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. Cập nhật phần giữ chỗ trong nội dung, chẳng hạn như OPERATING_ACCOUNT_ID và CONVERSION_ACTION_1_ID bằng các giá trị cho tài khoản và đích đến của bạn.
  2. Đặ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.
  3. Xin lưu ý rằng yêu cầu này không sử dụng phương thức mã hoá.

Gửi yêu cầu

  1. 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.
  2. Chuyển đến trang events.ingest.
  3. Nhấp vào nút API ở bên phải, rồi nhấp vào nút Dùng thử! trong phần mở rộng.
  4. Dán nội dung yêu cầu đã sao chép vào hộp Nội dung yêu cầu.
  5. 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"
}

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ụ: email_address 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 email_address 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 duy nhất. Sau đây là danh sách destinations đã sửa đổi cho yêu cầu:

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

Đặt destination_references 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 destination_references 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": [
      "conversion_action_1"
   ]
}

Trường destination_references 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 destination_references 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.

Các bước tiếp theo