Tentang peristiwa pengguna untuk aplikasi kustom

Halaman ini menjelaskan peristiwa pengguna untuk aplikasi penelusuran dan rekomendasi kustom, termasuk jenis peristiwa pengguna, persyaratan, dan contoh untuk jenis peristiwa pengguna.

Meskipun peristiwa pengguna tidak diperlukan untuk aplikasi kustom, peristiwa ini sangat direkomendasikan.

Google merekomendasikan untuk mengupload peristiwa setidaknya setiap hari untuk menjaga kualitas data yang baik. Selama impor peristiwa historis, pastikan distribusi data condong ke stempel waktu terbaru. Jumlah peristiwa pada hari stempel waktu terakhir harus sama dengan atau lebih besar dari jumlah peristiwa harian rata-rata.

Untuk mendapatkan bantuan terkait perekaman peristiwa pengguna, lihat [Merekam peristiwa pengguna real-time][record-events]. Untuk mengimpor peristiwa pengguna sebelumnya secara massal, lihat [Mengimpor peristiwa pengguna historis][import-user-events].

Jenis peristiwa pengguna

Anda dapat merekam jenis peristiwa pengguna berikut saat pengguna akhir menjelajahi atau menelusuri situs Anda:

Nama peristiwa pengguna Tindakan pengguna
view-item-list Melihat panel atau daftar dokumen yang diurutkan.
view-item Melihat detail dokumen.
view-home-page Melihat halaman beranda.
search Menelusuri aplikasi.

Untuk mengetahui detail tentang objek peristiwa pengguna, lihat [dokumentasi referensi API UserEvent][user-event].

Contoh dan skema jenis peristiwa pengguna

Bagian ini menyediakan format data untuk setiap jenis peristiwa yang didukung oleh aplikasi kustom. Contoh untuk Pixel JavaScript disediakan. Untuk BigQuery, skema tabel lengkap untuk setiap jenis disediakan.

Untuk semua jenis peristiwa pengguna, userId bersifat opsional.

Perhatikan bahwa:

  • Kolom tagIds hanya diperlukan jika Anda menjalankan eksperimen A/B.

  • Kolom attributionToken bersifat opsional; kolom ini digunakan untuk mengukur performa. Peristiwa search dan view-item yang dihasilkan dari klik rekomendasi harus memiliki token atribusi untuk menautkan kembali peristiwa ke rekomendasi yang menghasilkannya.

Untuk mengetahui detail selengkapnya tentang objek peristiwa pengguna, lihat [dokumentasi referensi API UserEvent][user-event].

view-item

Berikut menunjukkan format data peristiwa pengguna view-item.

Persyaratan pengoptimalan penelusuran untuk peristiwa lihat item

Agar penelusuran mengoptimalkan pengalaman penelusuran secara otomatis berdasarkan tren pengguna secara keseluruhan, upload data berikut.

Acara harus diupload setidaknya setiap hari dengan jeda maksimum 24 jam.

Metrik peristiwa Volume/frekuensi peristiwa Deskripsi
Volume peristiwa view-item Item tampilan 250 ribu

Minimal 250.000 item tampilan diperlukan untuk mengoptimalkan pengalaman penelusuran berdasarkan peristiwa yang diproses.

Objek lihat item minimum yang diperlukan

Contoh berikut hanya menampilkan kolom wajib di format peristiwa pengguna view-item.

Objek documents berisi ID dokumen (id) dan nama resourcenya (name).

  • Saat menyerap atau mencatat peristiwa pengguna di tingkat penyimpanan data, Anda dapat memberikan ID dokumen (id) atau nama resource (name).
  • Saat menyerap atau merekam peristiwa di tingkat lokasi, Anda harus memberikan nama resource dokumen (name) karena menunjukkan jalur lengkap dokumen dan merujuk ke penyimpanan data tempat dokumen berada. Anda dapat memberikan ID dokumen sebagai informasi tambahan opsional.

Pixel JavaScript

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

BigQuery

Ini adalah skema JSON lengkap untuk jenis peristiwa pengguna ini. Tentukan skema ini saat membuat tabel untuk jenis peristiwa pengguna ini di BigQuery.

Mode untuk kolom wajib diisi ditetapkan ke REQUIRED atau REPEATED. Mode untuk kolom opsional ditetapkan ke NULLABLE.

Perhatikan bahwa eventTime diperlukan untuk mengimpor peristiwa dengan BigQuery. eventTime adalah string dengan format Stempel Waktu. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-home-page

Berikut ini menunjukkan format peristiwa pengguna view-home-page.

Objek view-home-page minimum yang diperlukan

Contoh berikut hanya menampilkan kolom wajib di format peristiwa pengguna view-home-page.

Objek documents berisi ID dokumen (id) dan nama resourcenya (name).

  • Saat menyerap atau mencatat peristiwa pengguna di tingkat penyimpanan data, Anda dapat memberikan ID dokumen (id) atau nama resource (name).
  • Saat menyerap atau merekam peristiwa di tingkat lokasi, Anda harus memberikan nama resource dokumen (name) karena menunjukkan jalur lengkap dokumen dan merujuk ke penyimpanan data tempat dokumen berada. Anda dapat memberikan ID dokumen sebagai informasi tambahan opsional.

Pixel JavaScript

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

BigQuery

Ini adalah skema JSON lengkap untuk jenis peristiwa pengguna ini. Tentukan skema ini saat membuat tabel untuk jenis peristiwa pengguna ini di BigQuery.

Mode untuk kolom wajib diisi ditetapkan ke REQUIRED atau REPEATED. Mode untuk kolom opsional ditetapkan ke NULLABLE.

Perhatikan bahwa eventTime diperlukan untuk mengimpor peristiwa dengan BigQuery. eventTime adalah string dengan format Stempel Waktu. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

Berikut ini menunjukkan format peristiwa pengguna search.

Persyaratan pengoptimalan penelusuran untuk acara penelusuran

Untuk mengizinkan penelusuran mengoptimalkan pengalaman penelusuran secara otomatis berdasarkan tren pengguna secara keseluruhan, upload data berikut.

Acara harus diupload setidaknya setiap hari dengan jeda maksimum 24 jam.

Metrik peristiwa Volume/frekuensi peristiwa Deskripsi
Volume peristiwa search 100 ribu penelusuran

Minimal 100.000 penelusuran diperlukan untuk mengoptimalkan pengalaman penelusuran berdasarkan peristiwa yang diproses.

Objek penelusuran minimum yang diperlukan

Contoh berikut hanya menampilkan kolom wajib diisi dari format peristiwa pengguna search.

Setidaknya salah satu kolom searchQuery atau pageCategory harus diisi:

  • Berikan searchQuery untuk peristiwa penelusuran saat pengguna memasukkan kueri teks.

  • Berikan pageCategory saat pengguna membuka item yang diminati dengan menjelajah, yaitu dengan mengklik kategori, bukan dengan memasukkan kueri teks.

attributionToken ditampilkan dengan kueri penelusuran atau hasil penjelajahan.

Objek documents berisi ID dokumen (id) dan nama resourcenya (name).

  • Saat menyerap atau mencatat peristiwa pengguna di tingkat penyimpanan data, Anda dapat memberikan ID dokumen (id) atau nama resource (name).
  • Saat menyerap atau merekam peristiwa di tingkat lokasi, Anda harus memberikan nama resource dokumen (name) karena menunjukkan jalur lengkap dokumen dan merujuk ke penyimpanan data tempat dokumen berada. Anda dapat memberikan ID dokumen sebagai informasi tambahan opsional.

Pixel JavaScript

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "pageInfo": {
    "pageCategory": "CATEGORY_1 > CATEGORY_2",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

BigQuery

Ini adalah skema JSON lengkap untuk jenis peristiwa pengguna ini. Tentukan skema ini saat membuat tabel untuk jenis peristiwa pengguna ini di BigQuery.

Mode untuk kolom wajib diisi ditetapkan ke REQUIRED atau REPEATED. Mode untuk kolom opsional ditetapkan ke NULLABLE.

Perhatikan bahwa eventTime diperlukan untuk mengimpor peristiwa dengan BigQuery. eventTime adalah string dengan format Stempel Waktu. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Tentang informasi pengguna

userPseudoId mewakili ID pengguna unik dan diperlukan saat Anda merekam peristiwa pengguna.

Informasi pengguna ([UserInfo][user-info]) yang disertakan saat Anda mencatat peristiwa pengguna berisi nilai userPseudoId dan, jika tersedia, nilai userId. userId bersifat opsional dan dapat digunakan sebagai ID unik dan persisten untuk pengguna di berbagai perangkat setiap kali pengguna login ke situs Anda. Saat Anda merekam userId untuk pengguna, aplikasi penelusuran dan rekomendasi Anda dapat menghasilkan hasil yang lebih dipersonalisasi untuk satu pengguna di beberapa perangkat, seperti perangkat seluler dan browser web.

Tentang stempel waktu

Saat merekam peristiwa pengguna, pastikan untuk menyertakan stempel waktu yang akurat tentang kapan peristiwa terjadi. Stempel waktu yang akurat memastikan bahwa peristiwa Anda disimpan dalam urutan yang benar. Stempel waktu direkam secara otomatis untuk peristiwa yang dikumpulkan menggunakan JavaScript Pixel. Saat mengimpor peristiwa, Anda harus memberikan stempel waktu di kolom [eventTime][event-time] dalam format yang ditentukan oleh RFC 3339.

Langkah berikutnya

  • Pelajari cara [merekam peristiwa pengguna][record-events].

[rec-type-reqs]: /generative-ai-app-builder/docs/about-media-recommendations-types [record-events]: /generative-ai-app-builder/docs/record-user-events [event-time]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents#UserEvent.FIELDS.event_time [user-event]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents [user-info]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents#userinfo

[import-user-events]: /generative-ai-app-builder/docs/import-user-events [record-events]: /generative-ai-app-builder/docs/record-user-events