Mengirim peristiwa

Anda dapat mempelajari panduan memulai ini untuk memahami cara mengirim data peristiwa.

Data peristiwa adalah sumber data tambahan untuk konversi tag Anda, untuk memaksimalkan sinyal interaksi iklan dan memperkuat data serta performa secara keseluruhan.

Pilih versi panduan yang ingin Anda lihat:

Dalam panduan memulai ini, Anda akan menyelesaikan langkah-langkah berikut:

  1. Siapkan Destination untuk menerima data peristiwa.
  2. Siapkan data peristiwa untuk dikirim.
  3. Buat permintaan IngestionService untuk peristiwa.
  4. Kirim permintaan dengan Google APIs Explorer.
  5. Memahami respons berhasil dan gagal.

Menyiapkan tujuan

Sebelum dapat mengirim data, Anda harus menyiapkan tujuan untuk mengirim data ke sana. Berikut contoh Destination yang dapat Anda gunakan:

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • Tetapkan accountId dari operatingAccount ke ID akun Google Ads yang akan menerima data peristiwa. product dari operatingAccount harus GOOGLE_ADS.

  • Tetapkan productDestinationId ke ID tindakan konversi untuk peristiwa. Tindakan konversi harus berupa tindakan konversi Google Ads dengan type ditetapkan ke WEBPAGE.

    Panduan ini menunjukkan cara membuat permintaan yang mengirim setiap peristiwa ke tindakan konversi yang sama. Jika Anda ingin mengirim peristiwa untuk beberapa tindakan konversi dalam permintaan yang sama, lihat beberapa tujuan.

Menyiapkan data peristiwa

Pertimbangkan data peristiwa berikut. Setiap tabel sesuai dengan satu peristiwa konversi. Setiap peristiwa konversi memiliki stempel waktu peristiwa, tindakan konversi, dan nilai konversi.

Setiap peristiwa mungkin memiliki ID iklan, seperti gclid, atau ID pengguna, seperti alamat email, nomor telepon, dan informasi alamat.

Berikut data peristiwa pertama:

Acara #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
last_name Smith-Jones
region_code us
postal_code 94045

Berikut data acara kedua:

Acara #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ë
last_name pérez
region_code PT
postal_code 1229-076

Memformat data

Format kolom sesuai dengan yang ditentukan dalam panduan pemformatan. Berikut data peristiwa pertama setelah pemformatan:

Acara #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
last_name smith-jones
region_code US
postal_code 94045

Berikut adalah data acara kedua setelah diformat:

Acara #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ë
last_name pérez
region_code PT
postal_code 1229-076

Melakukan hash dan mengenkode data

Selain itu, alamat email, nama depan, dan nama belakang yang diformat harus di-hash menggunakan algoritma SHA-256 dan dienkode menggunakan encoding hex atau Base64. Berikut data peristiwa pertama setelah diformat, di-hash, dan dienkode menggunakan encoding hex:

Acara #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
last_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045

Berikut adalah data peristiwa kedua setelah diformat, di-hash, dan dienkode menggunakan encoding hex:

Acara #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
last_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

Konversi data ke Event

Konversi data yang diformat dan di-hash dari setiap peristiwa menjadi Event. Isi kolom wajib diisi berikut:

  • timestamp: Waktu terjadinya peristiwa.
  • transaction_id: ID unik untuk peristiwa.
  • event_source: Sumber peristiwa. Jika ditentukan, nilainya harus EVENT_SOURCE_WEB.
  • ad_identifiers atau user_data: Peristiwa harus memiliki ID iklan atau data pengguna. Kirim keduanya jika Anda memilikinya untuk acara tersebut.

Lihat dokumentasi referensi Event untuk mengetahui daftar lengkap kolom yang tersedia. Isi kolom apa pun yang memiliki nilai untuk peristiwa tersebut.

Berikut contoh Event untuk data yang diformat, di-hash, dan dienkode dari peristiwa kedua:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

Buat isi permintaan

Gabungkan Destination dan Events untuk isi permintaan:

{
  "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",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. Perbarui placeholder di isi, seperti OPERATING_ACCOUNT_ID dan CONVERSION_ACTION_1_ID dengan nilai untuk akun dan tujuan Anda.
  2. Tetapkan validateOnly ke true untuk memvalidasi permintaan tanpa menerapkan perubahan. Jika Anda sudah siap untuk menerapkan perubahan, tetapkan validateOnly ke false.
  3. Perhatikan bahwa permintaan ini tidak menggunakan enkripsi.

Kirim permintaan

  1. Salin isi permintaan menggunakan tombol salin di kanan atas contoh.
  2. Buka halaman events.ingest.
  3. Klik tombol API di sebelah kanan, lalu tombol Coba di bagian yang diperluas.
  4. Tempelkan isi permintaan yang disalin ke dalam kotak Isi permintaan.
  5. Klik tombol Execute, selesaikan perintah otorisasi, dan tinjau responsnya.

Respons keberhasilan

Permintaan yang berhasil akan menampilkan respons dengan objek yang berisi requestId.

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

Respons kegagalan

Permintaan yang gagal akan menghasilkan kode status respons error seperti 400 Bad Request, dan respons dengan detail error.

Misalnya, email_address yang berisi string teks biasa, bukan nilai yang dienkode hex, akan menghasilkan respons berikut:

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

email_address yang tidak di-hash dan hanya dienkode hex menghasilkan respons berikut:

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

Mengirim peristiwa untuk beberapa tujuan

Jika data Anda berisi peristiwa untuk tujuan yang berbeda, Anda dapat mengirimkannya dalam permintaan yang sama menggunakan referensi tujuan.

Misalnya, jika Anda memiliki peristiwa untuk ID tindakan konversi 123456789 dan peristiwa lain untuk ID tindakan konversi 777111122, kirim kedua peristiwa dalam satu permintaan dengan menetapkan reference dari setiap Destination. reference ditentukan oleh pengguna—satu-satunya persyaratan adalah setiap Destination harus memiliki reference unik. Berikut daftar destinations yang diubah untuk permintaan:

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

Tetapkan destination_references setiap Event untuk mengirimkannya ke satu atau beberapa tujuan tertentu. Misalnya, berikut adalah Event yang hanya untuk Destination pertama, sehingga daftar destination_references-nya hanya berisi reference dari Destination pertama:

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

Kolom destination_references adalah daftar, sehingga Anda dapat menentukan beberapa tujuan untuk suatu peristiwa. Jika Anda tidak menetapkan destination_references dari Event, Data Manager API akan mengirim peristiwa ke semua tujuan dalam permintaan.

Langkah berikutnya