Merekam peristiwa pengguna real-time

Halaman ini menjelaskan cara merekam peristiwa pengguna real-time. Vertex AI Search untuk retail menggunakan peristiwa pengguna real-time untuk menghasilkan rekomendasi dan hasil penelusuran. Mencatat sebanyak mungkin jenis peristiwa pengguna dengan informasi produk valid akan meningkatkan kualitas hasil Anda.

Prosedur perekaman di halaman ini berlaku untuk rekomendasi dan penelusuran. Setelah Anda merekam data, kedua layanan tersebut dapat menggunakan peristiwa tersebut, sehingga Anda tidak perlu mengupload data yang sama dua kali jika menggunakan kedua layanan tersebut.

Untuk mengetahui detail tentang peristiwa pengguna, termasuk jenis peristiwa pengguna dan contoh JSON untuk semua jenis, lihat Tentang peristiwa pengguna.

Anda dapat merekam peristiwa pengguna dengan beberapa cara:

Anda dapat menemukan contoh perekaman peristiwa pengguna jenis detail-page-view untuk semua metode ini di bawah. Untuk jenis peristiwa lainnya, lihat Tentang peristiwa pengguna.

Anda juga dapat mengimpor peristiwa pengguna historis. Diperlukan waktu yang cukup lama untuk mencatat data peristiwa pengguna yang memadai guna melatih model Anda. Anda dapat mempercepat pelatihan model awal dengan mengimpor data peristiwa pengguna dari peristiwa sebelumnya secara massal. Lihat Mengimpor peristiwa pengguna historis.

Jika peristiwa pengguna yang Anda rekam adalah pertama kalinya pengguna berinteraksi dengan produk berdasarkan rekomendasi atau hasil penelusuran yang diberikan sebelumnya, menyertakan token atribusi akan mengaktifkan metrik performa. Menyertakan token atribusi diperlukan agar Vertex AI Search untuk retail dapat berfungsi. Untuk mengetahui informasi tentang cara menggunakan token atribusi, lihat Token atribusi.

ID pengunjung diperlukan saat merekam peristiwa pengguna. Untuk informasi tentang ID pengunjung dan ID pengguna, lihat Tentang informasi pengguna.

Merekam peristiwa pengguna dengan pemberian tag sisi server

Pemberian tag sisi server memungkinkan Anda men-deploy satu penampung sisi server dengan banyak klien downstream. Hal ini akan membuat satu sumber tepercaya di sisi klien, dengan banyak konsumen sisi server. Arsitektur ini memindahkan beban dari web ke server, sehingga cocok bagi pengguna yang ingin memaksimalkan performa situs mereka.

Keuntungan lain dari pemberian tag sisi server adalah satu tag sisi server juga dapat mendukung banyak klien upstream, misalnya, web dan seluler. Pelajari cara menyiapkan pemberian tag sisi server.

Vertex AI Search untuk retail menyediakan tag sisi server native-nya sendiri.

Tag sisi server Cloud Retail memerlukan dan menerima parameter yang serupa dengan tag web Cloud Retail, seperti:

  • Nomor project
  • Kunci API (untuk autentikasi)
  • Penggantian untuk kolom utama seperti visitorId dan searchQuery

Perbedaan utama antara versi server dan versi web tag Cloud Retail adalah Anda tidak dapat menentukan sumber data. Sumber data untuk tag server adalah aliran data yang dikirim dari tag Google dalam skema GA4.

Menyiapkan tag Retail Cloud

Tutorial menulis peristiwa pengguna

Tutorial ini menunjukkan cara merekam peristiwa pengguna menggunakan metode userEvents.write.

Untuk mengikuti panduan langkah demi langkah tugas ini langsung di Cloud Shell Editor, klik Pandu saya:

Pandu saya

Sebelum memulai

Sebelum merekam peristiwa pengguna, Anda harus memiliki:

  • Project Google Cloud dibuat, dengan autentikasi disiapkan.

  • Kunci API yang valid (untuk Piksel JavaScript atau Tag Manager), atau akun layanan yang valid dengan Peran Editor Retail yang ditetapkan jika menggunakan API untuk menulis langsung.

    Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

Praktik terbaik untuk merekam peristiwa pengguna

Vertex AI Search untuk retail memerlukan data berkualitas tinggi untuk menghasilkan hasil berkualitas tinggi. Jika data Anda tidak lengkap atau salah, kualitas hasil akan menurun.

Saat merekam peristiwa pengguna, pastikan Anda menerapkan praktik terbaik berikut:

  • Jika Anda merekam peristiwa pengguna sebelum atau saat mengimpor katalog, gabungkan kembali peristiwa apa pun yang direkam sebelum impor katalog selesai.

    Anda dapat mengimpor katalog sebelum, sesudah, atau bersamaan dengan merekam peristiwa pengguna. Melakukan tugas ini secara paralel dapat menghemat waktu jika katalog besar dan ada banyak peristiwa pengguna. Setelah impor katalog selesai, Anda harus menggunakan API untuk bergabung kembali dengan peristiwa yang diupload sebelum impor selesai.

    Vertex AI Search untuk retail mencoba menggabungkan peristiwa pengguna yang direkam dengan metadata dari katalog produk saat peristiwa pengguna dibuat. Hanya peristiwa yang berhasil bergabung yang digunakan untuk pelatihan, jadi pastikan untuk bergabung kembali ke peristiwa apa pun yang direkam sebelum katalog diimpor sepenuhnya. Jika peristiwa mengacu pada item yang tidak ada dalam katalog, peristiwa tersebut akan dihapus atau tidak dikaitkan dengan produk yang benar. Demikian pula, jika Anda mengimpor peristiwa pengguna dari masa lalu, katalog harus menyertakan produk apa pun yang dirujuknya; Anda dapat menandai produk lama sebagai OUT_OF_STOCK, bukan menghapusnya dari katalog.

  • Pastikan katalog Anda selalu yang terbaru.

    Saat Anda merekam peristiwa pengguna, produk yang disertakan dalam peristiwa pengguna akan terhubung dengan katalog Anda saat ini. Jika Anda merekam peristiwa untuk produk yang tidak ada dalam katalog saat ini, peristiwa tersebut tidak dapat digunakan untuk melatih model. Hal ini disebut peristiwa "tidak bergabung". Jika Anda mencatat peristiwa sebelum katalog diimpor sepenuhnya, Anda harus menggabungkan kembali peristiwa yang dicatat selama impor. Adanya beberapa peristiwa yang tidak bergabung adalah hal yang wajar. Namun, jika persentase peristiwa yang tidak tergabung mencapai 5% atau lebih dari total peristiwa pengguna, pastikan katalog Anda sudah yang terbaru, gabungkan kembali peristiwa yang dicatat sebelum katalog diperbarui sepenuhnya, dan selidiki alasan peristiwa yang tidak tergabung dibuat.

    Anda dapat melihat peristiwa yang tidak bergabung menggunakan pemfilteran peristiwa. Pelajari lebih lanjut.

  • Berikan informasi sebanyak mungkin dengan peristiwa pengguna Anda.

    Setiap jenis peristiwa pengguna memiliki informasi yang berbeda yang diperlukan dan diterima. Untuk informasi selengkapnya, lihat Tentang peristiwa pengguna.

  • Siapkan pemberitahuan Cloud Monitoring agar Anda mengetahui apakah proses perekaman peristiwa pengguna mengalami pemadaman.

  • Untuk impor peristiwa pengguna massal, batasi ukuran data yang Anda impor.

    Pengimporan peristiwa pengguna massal dapat memerlukan waktu hingga 24 jam.

    Ukuran setiap file harus 2 GB atau lebih kecil. Anda dapat menyertakan maksimal 100 file dalam satu permintaan impor. Salah satu pendekatannya adalah mengimpor peristiwa pengguna saja per hari sekaligus.

  • Setelah impor massal, tinjau pelaporan error untuk memastikan data Anda diimpor dengan benar.

  • Saat mengimpor data peristiwa pengguna, sertakan stempel waktu yang akurat untuk setiap peristiwa pengguna dan hindari mengimpor peristiwa pengguna berurutan dengan stempel waktu yang sama.

    Berikan stempel waktu di kolom eventTime dalam format yang ditentukan oleh RFC 3339.

  • Jika Anda telah mengimpor peristiwa pengguna yang salah, hubungi kontak Vertex AI Search for Retail Anda tentang cara memperbaiki masalah tersebut.

  • Jika memungkinkan, pertahankan data peristiwa pengguna Anda secara berkelanjutan.

    Kesenjangan dalam data peristiwa pengguna dapat mengurangi kualitas model.

  • Gunakan bentuk ID unik yang aman untuk menjaga kerahasiaan pengguna di Vertex AI Search untuk retail dan melindungi privasi pengguna Anda. Anda bertanggung jawab untuk menyamarkan PII (informasi identitas pribadi), seperti alamat email atau rumah, dari data Anda.

Merekam peristiwa pengguna dengan piksel JavaScript

Contoh berikut mencatat UserEvent detail-page-view menggunakan piksel JavaScript.

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

Jika Anda mengimpor peristiwa pengguna dengan Google Analytics 360, tetapkan visitorID ke client ID Google Analytics. Perhatikan bahwa client ID Google Analytics hanya merupakan bagian dari nama cookie _ga lengkap (misalnya, client ID 123456789.123456789 adalah bagian dari cookie _ga GA1.3.123456789.123456789).

Berikut adalah contoh singkat yang menunjukkan format untuk menetapkan client ID dalam peristiwa pengguna. Ganti "G-XXXXX" dengan ID pelacakan Google Analytics Anda.

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

Merekam peristiwa pengguna dengan metode userEvents.write

Anda dapat menggunakan metode userEvents.write untuk mengirim peristiwa pengguna langsung ke API dari server backend.

Untuk merekam peristiwa pengguna, kirim permintaan POST ke metode userEvents.write dan berikan isi permintaan yang sesuai.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Mencatat peristiwa pengguna dengan Google Analytics 4

Anda dapat mencatat data peristiwa pengguna Google Analytics 4 ke Vertex AI Search untuk retail.

Memeriksa sumber data Anda

Pastikan data peristiwa pengguna yang ingin Anda impor telah diformat dengan benar.

Untuk tabel kolom Google Analytics 4 yang digunakan Vertex AI Search untuk retail dan kolom Vertex AI Search untuk retail yang dipetakan, lihat Kolom peristiwa pengguna Google Analytics 4.

Untuk semua parameter peristiwa Google Analytics, lihat dokumentasi referensi Peristiwa Google Analytics.

Pastikan bahwa:

  1. Jika Anda mengimpor peristiwa pembelian, yang diperlukan oleh beberapa model Vertex AI Search untuk retail, pelaporan peristiwa Anda akan menyertakan kode mata uang. Lihat parameter peristiwa purchase di dokumentasi Google Analytics.

  2. Jika Anda berencana mengimpor peristiwa search, pelaporan peristiwa Anda akan menyertakan kueri penelusuran.

    Mengimpor peristiwa search didukung, tetapi peristiwa search tidak dipetakan dari Google Analytics 4 dengan cara yang sama seperti jenis peristiwa lainnya karena Google Analytics 4 tidak mendukung secara native jenis peristiwa search Vertex AI Search untuk retail. Selama impor, peristiwa search dibuat dari Google Analytics 4 dengan menggabungkan informasi dari parameter peristiwa view_item_list dan search_term.

    Lihat parameter peristiwa search di dokumentasi Google Analytics.

Merekam peristiwa Google Analytics 4

Catat peristiwa pengguna dengan menyertakan data JSON mentah yang dienkode URL untuk peristiwa dalam panggilan Anda ke metode userEvents.collect.

Untuk parameter prebuilt_rule, gunakan nilai ga4_bq.

Untuk keterbacaan, contoh berikut tentang penggunaan panggilan userEvents.collect pertama-tama menetapkan GA4_EVENT sebagai variabel yang berisi data JSON mentah untuk contoh peristiwa. Panggilan userEvents.collect dalam contoh kemudian mengenkode data peristiwa menggunakan variabel GA4_EVENT.

  1. Untuk mempermudah encoding URL nanti, Anda dapat menetapkan GA4_EVENT sebagai variabel yang berisi data peristiwa. Contoh ini menunjukkan peristiwa add-to-cart.

    GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

  2. Lakukan panggilan userEvents.collect yang menyertakan data JSON mentah yang dienkode URL dari peristiwa pengguna:

    curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

Merekam peristiwa pengguna dengan Google Tag Manager

Tag Manager menyediakan cara untuk mengelola dan menguji beberapa tag tanpa banyak perubahan kode sisi server di situs Anda.

Beberapa keputusan yang Anda buat selama penyiapan bergantung pada apakah Anda menggunakan Google Analytics dan Google Analytics E-commerce. E-commerce Google Analytics dapat diterapkan menggunakan Google Analytics 4 atau Enhanced E-commerce. Tag Retail Cloud mendukung keduanya.

Google Analytics atau Google Analytics E-commerce tidak diperlukan; jika tidak menggunakannya, Anda dapat mengonfigurasi Variabel - E-commerce saat membuat tag Cloud Retail, atau mengisi kode lapisan data situs secara manual setelah membuat tag.

E-commerce Google Analytics adalah konfigurasi tambahan untuk Google Analytics yang meneruskan judul, ID, harga, detail transaksi, dan data e-commerce terstruktur lainnya ke Google Analytics. Vertex AI Search untuk retail dapat otomatis menggunakan lapisan data E-commerce Google Analytics, jadi jika Anda sudah menyiapkannya, konfigurasi akan lebih mudah. Jika Anda tidak mengonfigurasi E-commerce Google Analytics untuk Google Analytics, tetapi ingin menggunakannya, lihat detail selengkapnya dan petunjuk penyiapan di panduan developer GA4.

Gunakan prosedur satu kali ini untuk menyiapkan tag Cloud Retail di Tag Manager untuk merekam peristiwa pengguna.

Membuat variabel ID pengunjung

Nilai visitorId digunakan untuk melacak pengguna. visitorId biasanya merupakan ID sesi dan diperlukan untuk semua peristiwa. Siapkan variabel yang menetapkan ID sesi sebagai visitorId.

Jika menggunakan Google Analytics, Anda dapat menggunakan ID pengunjung Google Analytics. Untuk mengonfigurasinya, gunakan prosedur berikut untuk mengganti nilai ID pengunjung untuk tag Retail Cloud. Tindakan ini memetakan cookie pihak pertama "_ga" ke variabel Tag Manager yang disebut "GA visitorId". Anda dapat melakukan hal yang sama untuk cookie ID sesi apa pun; cookie tersebut tidak harus berasal dari Google Analytics.

Prosedur ini mengasumsikan bahwa Anda menggunakan Google Analytics. Jika tidak, Anda dapat menggunakan cookie atau variabel lain, atau mendapatkan ID pengunjung dari lapisan data cloud_retail.

Untuk menetapkan nilai visitorID ke variabel untuk tag Retail Cloud:

  1. Di Tag Manager, buka tab Variabel, lalu klik Baru untuk membuat variabel buatan pengguna baru.

  2. Beri nama variabel di bagian atas dialog, seperti "GA visitorId".

  3. Masukkan setelan variabel Anda.

    Anda dapat menggunakan client ID atau ID cookie untuk ditetapkan sebagai sumber ID pengunjung. Selalu gunakan sumber ID pengunjung yang konsisten saat menyerap peristiwa pengguna historis dan real-time.

    ID Klien

    Di Google Analytics 4, variabel ini dipetakan ke kolom user_pseudo_id di skema BigQuery Export Google Analytics 4.

    1. Tetapkan Jenis Variabel ke JavaScript Kustom.

    2. Masukkan skrip berikut di kolom JavaScript Kustom.

      Ganti "G-XXXXX" dengan ID pelacakan Google Analytics Anda. Untuk menemukan ID pelacakan Anda, lihat Apa yang terjadi dengan ID Pelacakan saya?.

      function() {
 var tracker = ga.getByName('G-XXXXXX');
 return tracker.get('clientID');
}

    3. Klik Simpan untuk menyimpan variabel.

    1. Pilih Cookie Pihak Pertama sebagai jenis variabel.

    2. Di kolom Cookie Name, masukkan _ga.

    3. Klik Format Value, pilih Convert undefined to.., lalu masukkan "" (string kosong).

    4. Klik Simpan untuk menyimpan variabel.

      Tindakan ini memetakan cookie pihak pertama "_ga" ke variabel Tag Manager yang disebut "GA visitorId".

Selanjutnya, buat tag Retail Cloud di Tag Manager. Tag ini akan menggunakan variabel ID pengunjung yang baru saja Anda buat.

Membuat tag Google Tag Manager

Siapkan tag di Tag Manager untuk mengirim informasi peristiwa pengguna ke Vertex AI Search untuk retail.

  1. Login ke Tag Manager dan pilih penampung untuk situs Anda.

  2. Buka tab Tags dan klik New untuk menambahkan tag baru.

  3. Beri nama tag di bagian atas panel (placeholder-nya adalah Untitled Variable), seperti "Vertex AI Search for retail".

  4. Klik Konfigurasi Tag, lalu pilih tag Retail Cloud untuk membuka panel konfigurasi tag.

  5. Masukkan kunci API Anda.

    Gunakan kunci yang Anda buat saat menyiapkan Vertex AI Search untuk retail.

    Kunci API Anda tersedia dari halaman APIs & Services > Credentials di Konsol Google Cloud.

  6. Masukkan nomor project project Google Cloud tempat Vertex AI Search untuk retail diaktifkan.

    Nomor project tersedia dari dasbor konsol Google Cloud Anda.

  7. Untuk kolom Sumber Data Peristiwa Pengguna:

    • Lapisan Data (direkomendasikan): Pilih apakah penerapan Anda akan berupa salah satu dari hal berikut:

      • Anda telah menerapkan E-commerce Google Analytics melalui Tag Manager. Gunakan kembali lapisan data sebagai sumber data peristiwa, bukan mengisi lapisan data baru. Tindakan ini menggunakan skema Google Analytics 4 jika ada. Jika tidak, variabel ini akan menggunakan Enhanced E-commerce UA. Dengan sumber data ini, Anda hanya dapat merekam peristiwa add-to-cart, purchase-complete, detail-page-view, dan search. Peristiwa search dicatat menggunakan tayangan iklan e-commerce yang digabungkan dengan kueri penelusuran (lihat Membuat variabel kueri penelusuran).

      • Anda menggunakan E-commerce Google Analytics, dan dapat mengisi kode lapisan data secara manual. Lihat Panduan Developer Tag Manager.

    • Variabel - Cloud Retail: Pilih untuk mengisi variabel Tag Manager dengan kolom yang diperlukan untuk Vertex AI Search untuk retail. Anda dapat memilih opsi ini jika tidak menggunakan Google Analytics E-commerce, atau jika Google Analytics E-commerce tidak memiliki data yang diperlukan untuk Vertex AI Search untuk retail. Jika Anda beralih ke sumber ini dari opsi Lapisan Data lama - Cloud Retail, buat juga Variabel Lapisan Data dengan kunci cloud_retail dan kaitkan dengan opsi Variabel - Cloud Retail ini.

    • Variabel - E-commerce: Pilih jika Anda tidak menggunakan E-commerce Google Analytics di lapisan data, dan tidak dapat mengisi kode lapisan data secara manual.

      Di kolom Baca Data E-commerce dari Variabel Pengguna yang muncul, pilih variabel. Hal ini memungkinkan Vertex AI Search untuk retail membaca data peristiwa pengguna E-commerce Google Analytics dari variabel kustom yang Anda buat.

      Variabel harus sesuai dengan format yang didokumentasikan dalam Panduan Developer GA4. Untuk membuat variabel dalam format yang benar, Anda dapat menggunakan Enhanced E-commerce Object Builder, template variabel kustom dari galeri template komunitas Tag Manager. Template komunitas tidak dikelola oleh Google. Untuk menggunakan template ini, lihat halaman galeri Enhanced E-commerce Object Builder untuk dokumentasi dan referensi lainnya.

  8. Klik tombol + Overwrite a value on the UserEvent message.

  9. Untuk Pemilih Kolom, pilih visitorId sebagai kolom, dan untuk Nilai Kolom, pilih variabel ID pengunjung baru yang Anda buat di Membuat variabel ID pengunjung.

  10. Klik Simpan.

    Tag Retail Cloud Anda telah dibuat.

Opsi sumber data lama

Sebelumnya, Lapisan Data - E-commerce dan Lapisan Data - Retail Cloud tersedia sebagai opsi sumber data. Opsi lama ini tidak tersedia di tag baru. Jika Anda mengalihkan tag yang ada ke sumber data baru, lihat pratinjaunya dengan Tag Manager untuk memverifikasinya sebelum penempatan. Saat beralih:

  • Jika menggunakan Lapisan Data - E-commerce, Anda dapat beralih ke Lapisan Data. Tindakan ini menggunakan skema Google Analytics 4 jika ada. Jika tidak, variabel ini akan menggunakan Enhanced E-commerce UA.

  • Jika Anda menggunakan Lapisan Data - Retail Cloud, beralihlah ke opsi Variabel - Retail Cloud. Buat Variabel Lapisan Data dengan kunci cloud_retail dan kaitkan dengan opsi Variabel - Cloud Retail.

Berikutnya:

Membuat variabel kueri penelusuran

Jika menggunakan penelusuran, Anda dapat membuat variabel di Tag Manager untuk kueri penelusuran dan melampirkan ke tag Cloud Retail. Hal ini memungkinkan Vertex AI Search untuk retail mendapatkan kueri penelusuran dari Analytics.

Jenis variabel yang Anda buat bergantung pada sumber data peristiwa pengguna.

  • Variabel - E-commerce, atau lapisan data dengan skema E-commerce Google Analytics: Buat variabel URL atau elemen DOM di Tag Manager dan lampirkan ke tag Cloud Retail Anda. Selain itu, aktifkan opsi agar tag Anda menggunakan tayangan iklan E-commerce Google Analytics untuk membuat peristiwa penelusuran.
  • Variabel - Cloud Retail, atau lapisan data yang diisi secara manual: Buat variabel URL atau elemen DOM di Tag Manager dan lampirkan ke tag Cloud Retail Anda. Untuk menentukan apakah jenis peristiwa pengguna adalah search, Anda juga harus:
    • Buat variabel jenis konstan untuk jenis peristiwa penelusuran dan lampirkan ke tag Anda.
    • Tetapkan jenis peristiwa penelusuran di lapisan data atau variabel Retail Cloud Anda.

Membuat dan melampirkan variabel Tag Manager untuk kueri penelusuran

Jika menggunakan penelusuran, Anda dapat membuat URL, elemen DOM, atau variabel JavaScript kustom yang akan diisi dengan kueri penelusuran yang dimasukkan di situs Anda.

Sebagai alternatif untuk prosedur ini, Anda dapat mengonfigurasi lapisan data untuk memberikan informasi kueri penelusuran. Namun, Anda dapat memilih untuk menggunakan variabel Tag Manager jika tidak memiliki akses ke lapisan data, atau memilih untuk tidak mengonfigurasi lapisan data.

Anda dapat membuat variabel jenis URL, variabel jenis elemen DOM, atau variabel JavaScript (halaman) kustom. Mana yang Anda buat dan cara mengonfigurasinya, bergantung pada penerapan situs Anda:

  • Variabel URL mendapatkan kueri penelusuran dari URL hasil penelusuran situs Anda. Gunakan variabel ini jika situs Anda menyertakan string kueri di URL hasil penelusurannya.
  • Variabel elemen DOM mendapatkan informasi kueri penelusuran dari Document Object Model (DOM) situs Anda. Anda tidak perlu mengedit DOM untuk menggunakan variabel ini. Namun, Anda harus dapat membaca dan memahami DOM untuk mengonfigurasi variabel ini dengan benar.
  • Variabel JavaScript Kustom menampilkan data yang diformat oleh fungsi JavaScript. Hal ini berguna jika Anda memiliki data yang ada yang ingin diformat dalam skema Retail Cloud atau E-commerce.

Pertama, buat variabel Tag Manager dari jenis URL, elemen DOM, atau JavaScript Kustom:

  1. Di Tag Manager, buka tab Variabel, lalu klik Baru untuk membuat variabel buatan pengguna baru.

  2. Beri nama variabel di bagian atas dialog, seperti "search_variable".

  3. Masukkan setelan variabel Anda:

    Jenis URL

    1. Tetapkan Jenis Variabel ke URL.

    2. Tetapkan Component Type ke Query.

    3. Jika Anda menentukan kunci kueri, tetapkan ke kunci yang mendahului kueri penelusuran di URL Anda.

      Misalnya, jika URL-nya adalah http://example.com/?q=shoes, kunci kuerinya adalah q. Dalam contoh ini, nilai variabel akan ditetapkan ke shoes.

    Jenis elemen DOM

    1. Tetapkan Jenis Variabel ke Elemen DOM.

    2. Tetapkan Metode Pemilihan dan masukkan ID elemen atau pemilih elemen kueri penelusuran.

      Setelan ini bergantung pada apakah situs Anda menggunakan ID elemen atau pemilih CSS untuk mengidentifikasi kueri penelusuran.

    3. Jika Anda menentukan atribut, tetapkan ke atribut yang berisi istilah kueri penelusuran.

      Misalnya, jika kueri penelusuran di DOM Anda adalah <id="search" value="shoes">, atributnya adalah value. Dalam contoh ini, nilai variabel Anda akan ditetapkan ke shoes.

    Jenis JavaScript kustom

    1. Tetapkan Jenis Variabel ke JavaScript Kustom.

    2. Ganti variabel dalam kode berikut dan tempelkan ke dalam panel JavaScript Kustom.

    3. Di panel JavaScript Kustom, tambahkan kode JavaScript yang menampilkan peristiwa penelusuran di Skema Retail.

      Kode contoh berikut mengubah data dalam variabel Ecommerce Items yang ada menjadi array productDetails yang digunakan oleh skema Vertex AI Search untuk retail dan menampilkan peristiwa lengkap. Untuk menggunakan kode ini, ganti Ecommerce Items, Search Query, dan Search Filter dengan variabel dalam penerapan Tag Manager Anda.

      function () {

  var retail;
  var items = [];

  for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
    var item = {'product':
                {
                  'id': {{Ecommerce Items}}[i].item_id
                }
               };

    items.push(item);
  }

  retail = {
    'eventType': 'search',
    'searchQuery': '{{Search Query}}',
    'filter': '{{Search Filter}}',
    'productDetails': items
  }

  return retail;
}

  4. Klik Simpan untuk menyimpan variabel.

Selanjutnya, lampirkan variabel ke tag Retail Cloud Anda:

  1. Di halaman Tag Manager, Tag, klik tag Retail Cloud untuk mengeditnya.

  2. Jika sumber data peristiwa pengguna tag Anda adalah Variabel - E-commerce atau Anda menggunakan lapisan data dengan skema E-commerce Google Analytics, centang kotak Gunakan tayangan Enhanced E-commerce untuk membuat peristiwa penelusuran.

    Hal ini memungkinkan Vertex AI Search untuk retail menentukan apakah jenis peristiwa pengguna adalah search berdasarkan data penelusuran yang diperoleh dari tag ini.

  3. Di bagian Data Peristiwa Pengguna, klik tombol + Timpa nilai pada pesan UserEvent.

  4. Pilih searchQuery dari Field Selector dan tetapkan variabel kueri penelusuran Anda sebagai Field Value.

  5. Simpan tag Anda.

Berikutnya:

Membuat dan melampirkan variabel konstan

Anda dapat menggunakan prosedur ini jika memilih Variabel - Retail Cloud atau lapisan data yang diisi secara manual sebagai sumber peristiwa pengguna untuk tag Retail Cloud Anda.

Membuat variabel jenis konstan untuk peristiwa penelusuran dan menetapkannya sebagai penggantian peristiwa pengguna di tag Cloud Retail memungkinkan Vertex AI Search untuk retail menentukan apakah jenis peristiwa pengguna adalah search.

Sebagai alternatif untuk prosedur ini, Anda dapat menentukan jenis peristiwa pengguna search melalui lapisan data atau variabel Cloud Retail yang Anda gunakan sebagai sumber peristiwa tag. Jika tidak, gunakan langkah-langkah berikut untuk menetapkan jenis peristiwa.

Pertama, buat variabel jenis konstan:

  1. Di Tag Manager, buka tab Variabel, lalu klik Baru untuk membuat variabel buatan pengguna baru.

  2. Beri nama variabel di bagian atas dialog, seperti "search_constant".

  3. Tetapkan Jenis Variabel ke Konstanta.

  4. Masukkan search di kolom Value

  5. Klik Simpan untuk menyimpan variabel.

Selanjutnya, lampirkan variabel ke tag Retail Cloud Anda:

  1. Di halaman Tag Manager, Tag, klik tag Retail Cloud untuk mengeditnya.

  2. Di bagian Data Peristiwa Pengguna, klik tombol + Timpa nilai pada pesan UserEvent.

  3. Pilih eventType dari Field Selector dan tetapkan variabel kueri penelusuran Anda sebagai Field Value.

  4. Simpan tag Anda.

Selanjutnya, buat pemicu peristiwa untuk tag Anda.

Membuat pemicu peristiwa untuk tag Tag Manager

Buat pemicu untuk semua jenis peristiwa pengguna yang akan digunakan oleh model Vertex AI Search untuk retail.

Tag Tag Manager harus memiliki pemicu yang mengontrol kapan tag harus "diaktifkan" di situs. Pemicu memproses peristiwa yang terjadi (seperti pengguna melihat halaman beranda atau menambahkan item ke keranjang) dan meminta tag Anda untuk mengirim informasi peristiwa pengguna tersebut ke Vertex AI Search untuk retail.

Tag Manager menyediakan beberapa pemicu standar. Misalnya, Window Loaded adalah pemicu untuk peristiwa detail-page-view. Untuk mengetahui detail tentang setiap jenis, lihat Jenis pemicu dalam dokumentasi Tag Manager.

Anda biasanya akan menetapkan tag untuk dipicu saat pengguna melihat halaman apa pun yang memiliki peristiwa yang diperlukan untuk Vertex AI Search untuk retail (seperti halaman beranda, halaman detail produk, halaman keranjang, atau halaman checkout selesai). Dalam kasus ini, tag harus diaktifkan setelah halaman dimuat, sehingga cookie tersedia dan semua variabel lapisan data diisi. Untuk melakukannya, tetapkan pemicu agar diaktifkan saat Window Loaded atau DOM Ready.

Anda mungkin perlu mengaktifkan tag saat tindakan dilakukan, bukan saat muat halaman (misalnya, jika pengguna menambahkan item ke keranjang tidak memaksa halaman untuk dimuat ulang). Dalam kasus ini, Anda dapat mengonfigurasi tindakan klik tersebut di situs untuk mengirim update secara bersamaan ke lapisan data dan mengaitkan pemicu dengan tindakan tersebut.

Misalnya, jika membuat pemicu untuk peristiwa add-to-cart, Anda dapat memilih jenis pemicu ke Click - Just Links dan menyetelnya untuk diaktifkan pada ID klik (dalam contoh ini, addtocart). Kemudian, Anda akan mengonfigurasi link addtocart di situs untuk juga memperbarui lapisan data dengan nilai baru saat diklik:

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

Untuk beberapa peristiwa pengguna, Anda harus membuat pemicu kustom. Umumnya, Anda membuat pemicu kustom di Tag Manager menggunakan nama peristiwa pengguna. Jika tidak dapat mengubah kode frontend, Anda dapat membuat pemicu kustom menggunakan makro JavaScript. Untuk informasi selengkapnya tentang pemicu kustom, lihat Pemicu peristiwa kustom.

Gunakan prosedur berikut untuk membuat pemicu di Tag Manager:

Membuat pemicu baru untuk tag Tag Manager

Jika Anda tidak menggunakan E-commerce Google Analytics, buat pemicu peristiwa baru untuk setiap peristiwa pengguna yang diperlukan model Vertex AI Search untuk retail. Kemudian, kaitkan pemicu baru dengan tag Cloud Retail yang Anda buat di Tag Manager.

Sebelum memulai langkah-langkah berikut, pastikan Anda telah membuat tag Cloud Retail di Tag Manager. Lihat Membuat tag Tag Manager.

Pertama, buat pemicu. Ulangi prosedur ini untuk semua peristiwa pengguna yang diperlukan oleh model Vertex AI Search untuk retail:

  1. Di halaman Tag Manager, Pemicu, klik Baru > Konfigurasi Pemicu.

  2. Pilih jenis pemicu yang berlaku untuk peristiwa pengguna yang pemicunya Anda buat.

  3. Simpan pemicu Anda.

Selanjutnya, kaitkan pemicu baru dengan tag Retail Cloud Anda. Ini adalah prosedur satu kali:

  1. Di halaman Tag Manager, Tag, klik tag Retail Cloud untuk mengeditnya.

  2. Klik Pemicuan, pilih pemicu baru, lalu klik Tambahkan.

  3. Simpan tag Anda.

Selanjutnya, lihat pratinjau tag Anda, dan siapkan pemantauan error perekaman peristiwa serta masalah lainnya untuk memastikan data terus berhasil diterima.

Jika Anda menggunakan lapisan data cloud_retail sebagai sumber peristiwa pengguna, pastikan juga untuk menyiapkan lapisan data.

Menggunakan kembali pemicu E-commerce Google Analytics

Jika Anda telah menerapkan E-commerce Google Analytics melalui Tag Manager, gunakan kembali pemicu peristiwa dari E-commerce Google Analytics untuk Vertex AI Search untuk retail.

Dengan sumber data ini, Anda hanya dapat merekam peristiwa add-to-cart, purchase-complete, detail-page-view, dan search. Peristiwa search dicatat menggunakan tayangan iklan e-commerce yang digabungkan dengan kueri penelusuran (lihat Membuat variabel kueri penelusuran).

Tabel berikut menunjukkan cara peristiwa E-commerce dan Enhanced E-commerce Google Analytics dipetakan ke Vertex AI Search untuk peristiwa retail.

Google Analytics 4 Enhanced E-commerce Vertex AI Search untuk retail
add_to_cart add add-to-cart
purchase purchase purchase-complete
view_item detail detail-page-view
view_item_list atau view_search_results impressions search (jika digabungkan dengan kolom searchQuery)

Sebelum memulai langkah-langkah ini, pastikan Anda telah:

  • Siapkan tag di Tag Manager dengan jenis tag Google Analytics - Peristiwa GA4, dan aktifkan Enhanced E-commerce atau GA4 di tag tersebut. Lihat dokumentasi Tag Manager, dan Panduan Developer GA4 untuk mengetahui detailnya.
  • Mengonfigurasi tag Enhanced E-commerce atau GA4 di Tag Manager untuk dipicu pada peristiwa pengguna yang ingin Anda catat untuk Vertex AI Search untuk retail.
  • Membuat tag Retail Cloud di Tag Manager, dengan 'Lapisan Data' atau 'Variabel - E-commerce' sebagai sumber data peristiwa pengguna (lihat Membuat tag Tag Manager.

Untuk menggunakan kembali pemicu E-commerce Google Analytics:

  1. Di halaman Tag Manager, Tag, klik tag E-commerce Google Analytics (jenis Google Analytics - Peristiwa GA4) untuk mengeditnya.

  2. Di bagian Setelan Lanjutan > Pengurutan Tag, pilih Aktifkan tag setelah <Nama tag Enhanced E-commerce atau GA4> diaktifkan.

  3. Pilih tag Retail Cloud Anda sebagai Tag Pembersihan.

    Pilih Jangan aktifkan <Nama tag Cloud Retail> jika <Nama tag Enhanced E-commerce atau GA4> gagal atau dijeda.

  4. Simpan tag Anda.

Selanjutnya, lihat pratinjau tag Anda, dan siapkan pemantauan error perekaman peristiwa serta masalah lainnya untuk memastikan data terus berhasil diterima.

Jika Anda menggunakan lapisan data cloud_retail sebagai sumber peristiwa pengguna, pastikan juga untuk menyiapkan lapisan data.

Menggunakan lapisan data cloud_retail dengan Tag Manager

Jika Anda membuat tag Cloud Retail di Tag Manager untuk menggunakan lapisan data cloud_retail sebagai sumber peristiwa pengguna, siapkan variabel dataLayer di HTML sumber seperti yang dijelaskan dalam Panduan Developer Tag Manager.

Tentang lapisan data

Sebagian besar tag Tag Manager memerlukan data yang berubah bergantung pada pengguna atau halaman (seperti ID pengguna atau ID produk). Untuk tag Cloud Retail, data tersebut harus ditampilkan secara terstruktur melalui lapisan data agar Tag Manager dapat menggunakannya.

Lapisan data adalah objek JavaScript yang biasanya ditambahkan ke halaman menggunakan kode sisi server, atau di frontend menggunakan HTML atau template. Jika dikonfigurasi dengan lapisan data, halaman akan berisi beberapa kode seperti berikut:

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

Kode ini membuat objek dataLayer dan menetapkan struktur cloud_retail ke objek tersebut sebagai elemen array.

Kolom wajib diisi di lapisan data cloud_retail

Tentang peristiwa pengguna mencantumkan semua kolom dan contoh yang diperlukan untuk jenis peristiwa yang harus diteruskan ke lapisan data cloud_retail.

Kode atau template sisi server Anda harus memiliki tag skrip yang benar di setiap halaman tempat Anda ingin mengirim peristiwa. Setelah objek dataLayer diisi dengan benar di setiap halaman, Anda akan dapat menguji tag Cloud Retail.

Beberapa kolom seperti visitorId diperlukan untuk pesan UserEvent, tetapi mungkin tidak tersedia saat mengisi lapisan data. Misalnya, visitorId mungkin berasal dari cookie pengguna, atau experimentIds dari framework eksperimen A/B. Dalam hal ini, gunakan variabel untuk menimpa kolom di tag Tag Manager.

Anda dapat menimpa kolom berikut:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Untuk mengetahui cara menimpa kolom UserEvent di Tag Manager, lihat artikel Menetapkan kolom visitorID di Tag Manager, yang menjelaskan cara menimpa nilai kolom visitorId dengan variabel buatan pengguna.

Contoh berikut menunjukkan lapisan data yang perlu disertakan di halaman Anda untuk UserEvent detail-page-view menggunakan Tag Manager:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Melihat pratinjau tag Tag Manager

Mode Pratinjau Tag Manager memungkinkan Anda menguji tag baru sebelum memublikasikannya ke situs aktif.

Untuk mengetahui detail selengkapnya tentang Mode Pratinjau, lihat dokumentasi Tag Manager untuk Mode Pratinjau.

Gunakan prosedur berikut untuk mengonfirmasi bahwa tag Anda diaktifkan dengan benar.

  1. Di halaman ringkasan Tag Manager, klik Pratinjau.

    Mode Pratinjau Tag Manager akan terbuka di tab browser baru.

  2. Masukkan informasi situs Anda, lalu klik Mulai untuk memulai Tag Assistant.

    Di tab browser saat ini, Tag Assistant akan dimulai, dan situs Anda akan terbuka di tab baru.

  3. Di situs Anda, buka halaman tempat tag Cloud Retail akan dipicu.

  4. Pastikan Tag Assistant mencantumkan tag Retail Cloud di tab Tag di bagian Tag Diaktifkan.

  5. Di Tag Assistant, buka tab Lapisan Data dan pastikan nilai yang benar dari lapisan data cloud_retail atau e-commerce ditampilkan.

Memeriksa error tag

Jika beberapa kolom salah atau tidak ada saat Anda melihat pratinjau tag, tag tersebut biasanya juga akan menampilkan error, kecuali jika tag tersebut tidak diaktifkan sama sekali.

Anda dapat memeriksa halaman Monitoring di konsol Penelusuran untuk Retail untuk menemukan error. Halaman ini mencatat sebagian besar error kecuali error sintaksis, yang biasanya hanya muncul dalam hasil permintaan.

Anda dapat menggunakan langkah-langkah berikut untuk menggunakan Chrome DevTools guna memeriksa error yang dihasilkan, termasuk error sintaksis.

  1. Aktifkan Mode Pratinjau di Tag Manager untuk situs Anda di browser Chrome dan buka halaman tempat tag Cloud Retail akan dipicu.

  2. Dengan Mode Pratinjau terbuka, buka DevTools dan klik tab Network.

  3. Muat ulang halaman.

  4. Di DevTools, telusuri userEvent.

    Tab Jaringan menampilkan peristiwa userEvent:collect dan kode statusnya.

    • Respons 200 menunjukkan bahwa tag Anda dalam kondisi baik.
    • Respons lainnya, seperti error 400 dan menandai peristiwa dengan warna merah, menunjukkan bahwa proses debug diperlukan.

  5. Klik dua kali nama peristiwa untuk menjalankan permintaan dan menampilkan respons lengkap dengan informasi error lainnya.

    Misalnya, Anda mungkin melihat error 400 yang berisi pesan, "'visitorId' wajib diisi, dan tidak boleh kosong", yang menunjukkan bahwa visitorId tidak ditetapkan dengan benar.

  6. Jika tidak ada userEvent yang diaktifkan, periksa tab Console DevTools untuk menemukan error sintaksis di lapisan data.

Memantau kondisi impor

Merekam peristiwa pengguna dengan sukses penting untuk mendapatkan hasil berkualitas tinggi. Anda harus memantau tingkat error perekaman peristiwa dan mengambil tindakan jika diperlukan. Untuk informasi selengkapnya, lihat Menyiapkan pemberitahuan untuk masalah upload data.

Melihat peristiwa yang direkam

Lihat metrik integrasi peristiwa di tab Peristiwa di halaman Data konsol Penelusuran untuk Retail. Halaman ini menampilkan semua peristiwa yang ditulis atau diimpor pada tahun lalu. Metrik dapat memerlukan waktu hingga 24 jam untuk muncul setelah penyerapan data berhasil.

Buka halaman Data

Langkah selanjutnya