REST Resource: projects.locations.dataStores.userEvents

Resource: UserEvent

UserEvent merekam semua informasi metadata yang perlu diketahui Discovery Engine API tentang cara pengguna akhir berinteraksi dengan situs Anda.

Representasi JSON 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
Kolom
eventType

string

Wajib. Jenis peristiwa pengguna. Nilai yang diperbolehkan adalah:

Nilai umum:

  • search: Menelusuri Dokumen.
  • view-item: Tampilan halaman mendetail Dokumen.
  • view-item-list: Tampilan panel atau daftar Dokumen yang diurutkan.
  • view-home-page: Tampilan halaman beranda.
  • view-category-page: Tampilan halaman kategori, misalnya Beranda > Pria > Jeans

Nilai terkait retail:

  • add-to-cart: Menambahkan item ke keranjang, misalnya dalam belanja online Retail
  • purchase: Membeli item

Nilai terkait media:

  • media-play: Mulai/lanjutkan menonton video, memutar lagu, dll.
  • media-complete: Menyelesaikan atau berhenti di tengah-tengah video, lagu, dll.

Nilai konversi kustom:

  • conversion: Peristiwa konversi yang ditentukan pelanggan.
conversionType

string

Opsional. Jenis konversi.

Wajib jika UserEvent.event_type adalah conversion. Ini adalah nama konversi yang ditentukan pelanggan dalam huruf kecil atau angka yang dipisahkan dengan "-", seperti "tonton", "kunjungan-baik", dll.

Jangan tetapkan kolom jika UserEvent.event_type bukan conversion. Hal ini mencampurkan peristiwa konversi kustom dengan peristiwa yang telah ditentukan sebelumnya seperti search, view-item, dll.
userPseudoId

string

Wajib. ID unik untuk melacak pengunjung.

Misalnya, hal ini dapat diterapkan dengan cookie HTTP, yang harus dapat mengidentifikasi pengunjung secara unik di satu perangkat. ID unik ini tidak boleh berubah jika pengunjung login/logout dari situs.

Jangan menetapkan kolom ke ID tetap yang sama untuk pengguna yang berbeda. Hal ini mencampur histori peristiwa pengguna tersebut, yang mengakibatkan kualitas model menurun.

Kolom harus berupa string berenkode UTF-8 dengan batas panjang 128 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Kolom tidak boleh berisi PII atau data pengguna. Sebaiknya gunakan ID Klien Google Analytics untuk kolom ini.
engine

string

Nama resource Engine, dalam bentuk projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

Opsional. Hanya diperlukan untuk peristiwa pengguna yang dihasilkan Engine. Misalnya, peristiwa pengguna dari penelusuran gabungan.
dataStore

string

Nama lengkap resource DataStore, dalam bentuk projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

Opsional. Hanya diperlukan untuk peristiwa pengguna yang penyimpanan datanya tidak dapat ditentukan oleh UserEvent.engine atau UserEvent.documents. Jika penyimpanan data ditetapkan di induk permintaan peristiwa pengguna tulis/impor/kumpulkan, kolom ini dapat dihilangkan.
eventTime

string (Timestamp format)

Hanya diperlukan untuk metode UserEventService.ImportUserEvents. Stempel waktu saat peristiwa pengguna terjadi.

Menggunakan RFC 3339 yang outputnya akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Informasi tentang pengguna akhir.
directUserRequest

boolean

Harus disetel ke benar (true) jika permintaan dibuat langsung dari pengguna akhir, yang dalam hal ini UserEvent.user_info.user_agent dapat diisi dari permintaan HTTP.

Flag ini hanya boleh disetel jika permintaan API dilakukan langsung dari pengguna akhir seperti aplikasi seluler (dan bukan jika gateway atau server memproses dan mengirimkan peristiwa pengguna).

Ini tidak boleh ditetapkan saat menggunakan tag JavaScript di UserEventService.CollectUserEvent.
sessionId

string

ID unik untuk melacak sesi pengunjung dengan batas panjang 128 byte. Sesi adalah penggabungan perilaku pengguna akhir dalam rentang waktu.

Panduan umum untuk mengisi sessionId:

  1. Jika pengguna tidak memiliki aktivitas selama 30 menit, sessionId baru harus ditetapkan.
  2. sessionId harus unik di seluruh pengguna, sebaiknya gunakan uuid atau tambahkan UserEvent.user_pseudo_id sebagai awalan.
pageInfo

object (PageInfo)

Metadata halaman seperti kategori dan informasi penting lainnya untuk jenis peristiwa tertentu seperti view-category-page.
attributionToken

string

Token untuk mengatribusikan respons API ke tindakan pengguna untuk memicu peristiwa.

Sangat direkomendasikan untuk peristiwa pengguna yang merupakan hasil dari RecommendationService.Recommend. Kolom ini memungkinkan atribusi yang akurat atas performa model rekomendasi.

Nilainya harus berupa salah satu dari:

Token ini memungkinkan kami mengatribusikan penyelesaian konversi atau tayangan halaman secara akurat kembali ke peristiwa dan respons prediksi tertentu yang berisi produk yang diklik/dibeli ini. Jika pengguna mengklik produk K dalam hasil rekomendasi, teruskan RecommendResponse.attribution_token sebagai parameter URL ke halaman produk K. Saat merekam peristiwa di halaman produk K, catat RecommendResponse.attribution_token ke kolom ini.
filter

string

Sintaksis filter terdiri dari bahasa ekspresi untuk membuat predikat dari satu atau beberapa kolom dokumen yang difilter.

Salah satu contohnya adalah untuk peristiwa search, SearchRequest terkait dapat berisi ekspresi filter di SearchRequest.filter yang sesuai dengan https://google.aip.dev/160#filtering.

Demikian pula, untuk peristiwa view-item-list yang dihasilkan dari RecommendRequest, kolom ini dapat diisi langsung dari RecommendRequest.filter yang sesuai dengan https://google.aip.dev/160#filtering.

Nilai harus berupa string berenkode UTF-8 dengan batas panjang 1.000 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
documents[]

object (DocumentInfo)

Daftar Document yang terkait dengan peristiwa pengguna ini.

Kolom ini bersifat opsional, kecuali untuk jenis peristiwa berikut:

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

Dalam peristiwa search, kolom ini merepresentasikan dokumen yang ditampilkan kepada pengguna akhir di halaman saat ini (pengguna akhir mungkin belum selesai menjelajahi seluruh halaman). Saat halaman baru ditampilkan kepada pengguna akhir, setelah penomoran halaman/pemfilteran/pengurutan bahkan untuk kueri yang sama, peristiwa search baru dengan UserEvent.documents yang berbeda akan diinginkan.
panel

object (PanelInfo)

Metadata panel yang terkait dengan peristiwa pengguna ini.
searchInfo

object (SearchInfo)

Detail SearchService.Search yang terkait dengan acara.

Kolom ini harus ditetapkan untuk peristiwa search.
completionInfo

object (CompletionInfo)

Detail CompletionService.CompleteQuery yang terkait dengan acara.

Kolom ini harus disetel untuk peristiwa search saat fungsi pelengkapan otomatis diaktifkan dan pengguna mengklik saran untuk penelusuran.
transactionInfo

object (TransactionInfo)

Metadata transaksi (jika ada) yang terkait dengan peristiwa pengguna ini.
tagIds[]

string

Daftar ID untuk grup eksperimen independen tempat peristiwa pengguna ini berada. Parameter ini digunakan untuk membedakan peristiwa pengguna yang terkait dengan penyiapan eksperimen yang berbeda.
promotionIds[]

string

ID promosi jika ini adalah peristiwa yang terkait dengan promosi. Saat ini, kolom ini dibatasi hingga maksimal satu ID.
attributes

map (key: string, value: object)

Fitur peristiwa pengguna tambahan yang akan disertakan dalam model rekomendasi. Atribut ini TIDAK boleh berisi data yang perlu diurai atau diproses lebih lanjut, misalnya JSON atau encoding lainnya.

Jika Anda memberikan atribut kustom untuk peristiwa pengguna yang diproses, sertakan juga atribut tersebut dalam peristiwa pengguna yang Anda kaitkan dengan permintaan prediksi. Pemformatan atribut kustom harus konsisten antara peristiwa yang diimpor dan peristiwa yang diberikan dengan permintaan prediksi. Hal ini memungkinkan Discovery Engine API menggunakan atribut kustom tersebut saat melatih model dan menyajikan prediksi, yang membantu meningkatkan kualitas rekomendasi.

Kolom ini harus memenuhi semua kriteria di bawah, jika tidak, error INVALID_ARGUMENT akan ditampilkan:

  • Kunci harus berupa string berenkode UTF-8 dengan batas panjang 5.000 karakter.
  • Untuk atribut teks, maksimal 400 nilai diizinkan. Nilai kosong tidak diizinkan. Setiap nilai harus berupa string yang dienkode UTF-8 dengan batas panjang 256 karakter.
  • Untuk atribut angka, maksimal 400 nilai yang diizinkan.

Untuk rekomendasi produk, contoh informasi pengguna tambahan adalah traffic_channel, yaitu cara pengguna tiba di situs. Pengguna dapat membuka situs dengan membuka situs secara langsung, melalui penelusuran Google, atau dengan cara lain.
attributes.text[]

string

Nilai tekstual atribut khusus ini. Misalnya, ["yellow", "green"] saat kuncinya adalah "color".

String kosong tidak diizinkan. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Tepatnya salah satu dari CustomAttribute.text atau CustomAttribute.numbers yang harus ditetapkan. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
attributes.numbers[]

number

Nilai numerik atribut khusus ini. Misalnya, [2.3, 15.4] jika kuncinya adalah "lengths_cm".

Tepatnya salah satu dari CustomAttribute.text atau CustomAttribute.numbers yang harus ditetapkan. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
mediaInfo

object (MediaInfo)

Info khusus media.
panels[]

object (PanelInfo)

Opsional. Daftar panel yang terkait dengan acara ini. Digunakan untuk data tayangan iklan tingkat halaman.

PageInfo

Informasi halaman mendetail.

Representasi JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
Kolom
pageviewId

string

ID unik tampilan halaman web.

Nilai ini harus tetap sama untuk semua peristiwa pengguna yang dipicu dari tayangan halaman yang sama. Misalnya, tampilan halaman detail item dapat memicu beberapa peristiwa saat pengguna menjelajahi halaman. Properti pageviewId harus tetap sama untuk semua peristiwa ini agar dapat dikelompokkan dengan benar.

Saat menggunakan pelaporan peristiwa sisi klien dengan piksel JavaScript dan Google Tag Manager, nilai ini akan diisi secara otomatis.
pageCategory

string

Kategori paling spesifik yang terkait dengan halaman kategori.

Untuk merepresentasikan jalur lengkap kategori, gunakan tanda '>' untuk memisahkan hierarki yang berbeda. Jika '>' adalah bagian dari nama kategori, ganti dengan karakter lain.

Halaman kategori mencakup halaman khusus seperti halaman diskon atau promosi. Misalnya, halaman promo khusus mungkin memiliki hierarki kategori: "pageCategory" : "Sales > 2017 Black Friday Deals".

Wajib untuk peristiwa view-category-page. Jenis peristiwa lainnya tidak boleh menyetel kolom ini. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
uri

string

URL lengkap (window.location.href) halaman pengguna saat ini.

Saat menggunakan pelaporan peristiwa sisi klien dengan piksel JavaScript dan Google Tag Manager, nilai ini akan diisi secara otomatis. Panjang maksimum 5.000 karakter.
referrerUri

string

URL perujuk halaman saat ini.

Saat menggunakan pelaporan peristiwa sisi klien dengan piksel JavaScript dan Google Tag Manager, nilai ini akan diisi secara otomatis. Namun, beberapa batasan privasi browser dapat menyebabkan kolom ini kosong.

DocumentInfo

Informasi dokumen mendetail yang terkait dengan peristiwa pengguna.

Representasi JSON 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
Kolom
promotionIds[]

string

ID promosi yang terkait dengan Dokumen ini. Saat ini, kolom ini dibatasi hingga maksimal satu ID.
joined

boolean

Hanya output. Apakah Dokumen yang direferensikan dapat ditemukan di penyimpanan data.

Kolom union document_descriptor. Deskriptor wajib untuk Document terkait.

  • Jika id ditentukan, nilai default untuk {location}, {collection_id}, {data_store_id}, dan {branch_id} akan digunakan saat membuat anotasi dengan Dokumen yang disimpan.

  • Jika name ditentukan, nilai yang diberikan (nilai default diizinkan) untuk {location}, {collection_id}, {data_store_id}, dan {branch_id} akan digunakan saat membuat anotasi dengan Dokumen yang disimpan. document_descriptor hanya dapat berupa salah satu dari hal berikut:
id

string

ID resource Document.
name

string

DocumentNama lengkap resource, dalam bentuk: projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

URI Document - hanya diizinkan untuk penyimpanan data situs.
quantity

integer

Jumlah Dokumen yang terkait dengan peristiwa pengguna. Default-nya adalah 1.

Misalnya, kolom ini adalah 2 jika dua kuantitas Dokumen yang sama terlibat dalam peristiwa add-to-cart.

Wajib untuk peristiwa dengan jenis peristiwa berikut:

  • add-to-cart
  • purchase
conversionValue

number

Opsional. Nilai konversi yang terkait dengan Dokumen ini. Harus ditetapkan jika UserEvent.event_type adalah "conversion".

Misalnya, nilai 1000 menandakan bahwa 1000 detik dihabiskan untuk melihat Dokumen untuk jenis konversi watch.

PanelInfo

Informasi panel mendetail yang terkait dengan peristiwa pengguna.

Representasi JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
Kolom
panelId

string

Wajib. ID panel.
displayName

string

Nama tampilan panel.
documents[]

object (DocumentInfo)

Opsional. ID dokumen yang terkait dengan panel ini.
panelPosition

integer

Posisi panel yang diurutkan, jika ditampilkan kepada pengguna dengan panel lain. Jika ditetapkan, totalPanels juga harus ditetapkan.
totalPanels

integer

Jumlah total panel, termasuk panel ini, yang ditampilkan kepada pengguna. Harus ditetapkan jika panelPosition ditetapkan.

SearchInfo

Informasi penelusuran mendetail.

Representasi JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
Kolom
searchQuery

string

Kueri penelusuran pengguna.

Lihat SearchRequest.query untuk mengetahui definisinya.

Nilai harus berupa string berenkode UTF-8 dengan batas panjang 5.000 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Setidaknya salah satu dari searchQuery atau PageInfo.page_category harus ada untuk peristiwa search. Jenis peristiwa lainnya tidak boleh menyetel kolom ini. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
orderBy

string

Urutan produk ditampilkan, jika berlaku.

Lihat SearchRequest.order_by untuk mengetahui definisi dan sintaksis.

Nilai harus berupa string berenkode UTF-8 dengan batas panjang 1.000 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Kolom ini hanya dapat disetel untuk acara search. Jenis peristiwa lainnya tidak boleh menyetel kolom ini. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
offset

integer

Bilangan bulat yang menentukan offset saat ini untuk penomoran halaman (lokasi awal berindeks 0, di antara produk yang dianggap relevan oleh API).

Lihat SearchRequest.offset untuk mengetahui definisinya.

Jika kolom ini negatif, INVALID_ARGUMENT akan ditampilkan.

Kolom ini hanya dapat disetel untuk acara search. Jenis peristiwa lainnya tidak boleh menyetel kolom ini. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

CompletionInfo

Informasi penyelesaian mendetail, termasuk token atribusi penyelesaian dan info penyelesaian yang diklik.

Representasi JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
Kolom
selectedSuggestion

string

Pengguna akhir dipilih CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posisi CompleteQueryResponse.QuerySuggestion.suggestion yang dipilih pengguna akhir, dimulai dari 0.

TransactionInfo

Transaksi mewakili seluruh transaksi pembelian.

Representasi JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
Kolom
currency

string

Wajib. Kode mata uang. Gunakan kode ISO-4217 tiga karakter.
transactionId

string

ID transaksi dengan batas panjang 128 karakter.
value

number

Wajib. Total nilai bukan nol yang terkait dengan transaksi. Nilai ini dapat mencakup pengiriman, pajak, atau penyesuaian lainnya pada total nilai yang ingin Anda sertakan.
tax

number

Semua pajak yang terkait dengan transaksi.
cost

number

Semua biaya yang terkait dengan produk. Biaya ini dapat berupa biaya produksi, biaya pengiriman yang tidak ditanggung oleh pengguna akhir, atau biaya lainnya, sehingga:
discountValue

number

Total nilai diskon yang diterapkan pada transaksi ini. Angka ini harus dikecualikan dari TransactionInfo.value

Misalnya, jika pengguna membayar sebesar TransactionInfo.value, maka nilai nominal (sebelum diskon) transaksi adalah jumlah TransactionInfo.value dan TransactionInfo.discount_value

Artinya, laba dihitung dengan cara yang sama, terlepas dari nilai diskon, dan TransactionInfo.discount_value dapat lebih besar dari TransactionInfo.value:

MediaInfo

Informasi peristiwa pengguna khusus media.

Representasi JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
Kolom
mediaProgressDuration

string (Duration format)

Waktu progres media dalam detik, jika ada. Misalnya, jika pengguna akhir telah menyelesaikan 90 detik video pemutaran, maka MediaInfo.media_progress_duration.seconds harus disetel ke 90.

Durasi dalam detik dengan maksimal sembilan digit pecahan, yang diakhiri dengan 's'. Contoh: "3.5s".
mediaProgressPercentage

number

Progres media harus dihitung hanya menggunakan mediaProgressDuration relatif terhadap total durasi media.

Nilai ini harus antara [0, 1.0] inklusif.

Jika ini bukan pemutaran atau progres tidak dapat dihitung (misalnya, livestream yang sedang berlangsung), kolom ini harus dibiarkan tidak ditetapkan.

Metode

collect

 Menulis satu peristiwa pengguna dari browser.

import

 Impor massal peristiwa pengguna.

purge

 Menghapus secara permanen semua peristiwa pengguna yang ditentukan oleh filter yang diberikan.

write

 Menulis satu peristiwa pengguna.