REST Resource: projects.locations.dataStores.userEvents

資源：UserEvent

UserEvent 會擷取 Discovery Engine API 需要的所有中繼資料資訊，瞭解使用者與您網站的互動方式。

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)
    }
  ],
  "feedback": {
    object (Feedback)
  },
  "entity": string
}
欄位
eventType

string

這是必要旗標，使用者事件類型。允許的值包括：

一般值：

  • search：搜尋文件。
  • view-item：文件的詳細資料頁面。
  • view-item-list：面板或文件排序清單的檢視畫面。
  • view-home-page：首頁檢視畫面。
  • view-category-page：類別頁面檢視畫面，例如「首頁」>「男裝」>「牛仔褲」

零售相關值：

  • add-to-cart：將商品加入購物車，例如在零售業線上購物
  • purchase：購買商品

媒體相關值：

  • media-play：開始/繼續觀看影片、播放歌曲等。
  • media-complete：已看完或中途停止觀看影片、聽完或中途停止聆聽歌曲等。

自訂轉換價值：

  • conversion：顧客定義的轉換事件。
conversionType

string

選用。轉換類型。

如果 UserEvent.event_type 為 conversion，則為必要欄位。這是由客戶定義的轉換名稱，以小寫英文字母或數字表示，並以「-」分隔，例如「watch」、「good-visit」等。

如果 UserEvent.event_type 不是 conversion，請勿設定這個欄位。這會將自訂轉換事件與預先定義的事件 (例如 search、view-item 等) 混用。
userPseudoId

string

這是必要旗標，用於追蹤訪客的專屬 ID。

舉例來說，這項功能可以透過 HTTP Cookie 實作，應能識別單一裝置上的訪客。如果訪客登入/登出網站，這個專屬 ID 就不應變更。

請勿為不同使用者將這個欄位設為相同的固定 ID。這會將這些使用者的事件記錄混在一起，導致模型品質下降。

這個欄位必須是 UTF-8 編碼的字串，長度上限為 128 個半形字元。否則會傳回 INVALID_ARGUMENT 錯誤。

這個欄位不應包含個人識別資訊或使用者資料。建議您使用 Google Analytics 用戶端 ID 填寫這個欄位。
engine

string

Engine 資源名稱，格式為 projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}。

選用。只有在Engine產生使用者事件時才需要。例如，混合搜尋中的使用者事件。
dataStore

string

DataStore 資源的完整名稱，格式為 projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}。

選用。只有在 UserEvent.engine 或 UserEvent.documents 無法判斷資料儲存庫時，才需要為使用者事件設定這個參數。如果資料儲存庫是在寫入/匯入/收集使用者事件要求的父項中設定，則可以省略這個欄位。
eventTime

string (Timestamp format)

僅適用於 UserEventService.ImportUserEvents 方法。使用者事件發生的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
userInfo

object (UserInfo)

使用者資訊。
directUserRequest

boolean

如果要求是直接由使用者提出，則應設為 true，此時 UserEvent.user_info.user_agent 可從 HTTP 要求填入。

只有在 API 要求直接來自行動應用程式等使用者時，才應設定這個旗標 (如果閘道或伺服器正在處理及推送使用者事件，則不應設定)。

在 UserEventService.CollectUserEvent 中使用 JavaScript 標記時，請勿設定這個參數。
sessionId

string

用於追蹤訪客工作階段的專屬 ID，長度上限為 128 個位元組。工作階段是指一段時間內的使用者行為匯總。

填入 sessionId 的一般準則：

  1. 如果使用者閒置 30 分鐘，系統應指派新的 sessionId。
  2. sessionId 在使用者之間應是專屬的，建議使用 uuid 或新增 UserEvent.user_pseudo_id 做為前置字元。
pageInfo

object (PageInfo)

頁面中繼資料，例如類別，以及特定事件類型 (例如 view-category-page) 的其他重要資訊。
attributionToken

string

這個權杖可將 API 回應歸因於觸發事件的使用者動作。

如果使用者事件是 RecommendationService.Recommend 的結果，強烈建議您使用這項功能。這個欄位可準確歸因建議模型成效。

這個值必須是下列其中一個：

這個權杖可讓我們準確地將網頁瀏覽或轉換完成歸因於事件，以及包含這個點選/購買產品的特定預測回應。如果使用者點選建議結果中的產品 K，請將 RecommendResponse.attribution_token 做為網址參數傳遞至產品 K 的頁面。在產品 K 的頁面記錄事件時，請將 RecommendResponse.attribution_token 記錄到這個欄位。
filter

string

選用。篩選器語法包含運算式語言，可從要篩選的文件中一或多個欄位建構述詞。

舉例來說，如果是 search 事件，相關聯的 SearchRequest 可能會在 SearchRequest.filter 中包含符合 https://google.aip.dev/160#filtering 的篩選運算式。

同樣地，如果是從 RecommendRequest 產生的 view-item-list 事件，這個欄位可能會直接從 RecommendRequest.filter 填入，並符合 https://google.aip.dev/160#filtering。

值必須是 UTF-8 編碼的字串，長度上限為 1,000 個字元。否則會傳回 INVALID_ARGUMENT 錯誤。
documents[]

object (DocumentInfo)

與這個使用者事件相關聯的 Document 清單。

除了下列事件類型外，這個欄位為選填：

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

在 search 事件中，這個欄位代表目前頁面傳回給使用者的文件 (使用者可能尚未瀏覽完整個頁面)。即使是相同查詢，在分頁/篩選/排序後，如果傳回給使用者的網頁是新的，就應使用不同的 UserEvent.documents 傳送新的 search 事件。
panel

object (PanelInfo)

與這個使用者事件相關聯的面板中繼資料。
searchInfo

object (SearchInfo)

SearchService.Search 事件相關詳細資料。

這個欄位應為 search 事件設定。
completionInfo

object (CompletionInfo)

CompletionService.CompleteQuery 事件相關詳細資料。

啟用自動完成功能，且使用者點選搜尋建議時，應為 search 事件設定這個欄位。
transactionInfo

object (TransactionInfo)

與這個使用者事件相關聯的交易中繼資料 (如有)。
tagIds[]

string

這項使用者事件所屬的獨立實驗群組 ID 清單。用於區分與不同實驗設定相關聯的使用者事件。
promotionIds[]

string

如果這是與促銷活動相關聯的活動，則為促銷 ID。目前這個欄位最多只能有一個 ID。
attributes

map (key: string, value: object)

選用。要納入推薦模型中的額外使用者事件特徵。這些屬性不得包含需要進一步剖析或處理的資料，例如 JSON 或其他編碼。

如果您為擷取的使用者事件提供自訂屬性，也請將這些屬性納入與預測要求相關聯的使用者事件。匯入的事件和預測要求提供的事件，自訂屬性格式必須一致。這樣一來，Discovery Engine API 就能在訓練模型和提供預測結果時使用這些自訂屬性，進而提升推薦品質。

這個欄位必須符合下列所有條件，否則會傳回 INVALID_ARGUMENT 錯誤：

  • 金鑰必須是 UTF-8 編碼字串，長度上限為 5,000 個半形字元。
  • 如果是文字屬性，最多可輸入 400 個值。不得留空。每個值都必須是以 UTF-8 編碼的字串，長度上限為 256 個字元。
  • 如果是數字屬性，最多只能有 400 個值。

以產品推薦為例，額外使用者資訊可以是 traffic_channel，也就是使用者到達網站的方式。使用者可直接造訪網站、透過 Google 搜尋進入網站，或以其他方式抵達網站。
attributes.text[]

string

這項自訂屬性的文字值。例如，當索引鍵為「color」時，["yellow", "green"]。

不得留空。否則會傳回 INVALID_ARGUMENT 錯誤。

應設定 CustomAttribute.text 或 CustomAttribute.numbers 其中之一。否則會傳回 INVALID_ARGUMENT 錯誤。
attributes.numbers[]

number

這個自訂屬性的數值。舉例來說，如果索引鍵是「lengths_cm」，則為 [2.3, 15.4]。

應設定 CustomAttribute.text 或 CustomAttribute.numbers 其中之一。否則會傳回 INVALID_ARGUMENT 錯誤。
mediaInfo

object (MediaInfo)

媒體專屬資訊。
panels[]

object (PanelInfo)

選用。與此活動相關的面板清單。用於網頁層級曝光資料。
feedback

object (Feedback)

選用。除了 add-feedback 事件類型外，這個欄位為選填。
entity

string

選用。代表可能經營多個不同實體、網域、網站或區域的客戶實體，例如 Google US、Google Ads、Waymo、google.com、youtube.com 等。建議您設定 entity，以取得更精確的實體搜尋、自動完成和預測結果。

UserInfo

使用者的資訊。

JSON 表示法 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string,
  "preciseLocation": {
    object (PreciseLocation)
  }
}
欄位
userId

string

強烈建議已登入的使用者採用這項做法。登入使用者的專屬 ID，例如使用者名稱。請勿為匿名使用者設定。

請一律使用這個 ID 的雜湊值。

請勿為不同使用者將該欄位設為相同的固定 ID。這會將這些使用者的事件記錄混在一起，導致模型品質下降。

這個欄位必須是 UTF-8 編碼的字串，長度上限為 128 個半形字元。否則會傳回 INVALID_ARGUMENT 錯誤。

代表 Search API 的不透明 ID。搜尋 API 不會以任何方式解讀值。如果上傳事件，這個欄位可用於將事件與跨工作階段的使用者建立關聯。
userAgent

string

HTTP 標頭中包含的使用者代理程式。

這個欄位必須是 UTF-8 編碼的字串，長度上限為 1,000 個半形字元。否則會傳回 INVALID_ARGUMENT 錯誤。

如果使用 GTM 或 JavaScript 代碼在 UserEventService.CollectUserEvent中回報用戶端事件，或已設定 UserEvent.direct_user_request，則不應設定這項參數。
timeZone

string

選用。IANA 時區，例如 Europe/Budapest。
preciseLocation

object (PreciseLocation)

選用。僅限輸入。使用者的精確位置。自訂排序功能會使用這項資訊，計算使用者與相關文件之間的距離。

PreciseLocation

提供精確位置資訊，並提供多種呈現方式。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "point": {
    object (LatLng)
  },
  "address": string
  // End of mutually exclusive fields.
}
欄位
以下列出互斥欄位。回應中最多會設定一個欄位：
point

object (LatLng)

選用。以經緯度點表示的位置。
address

string

以自然語言地址表示的位置。系統稍後會進行地理編碼，並轉換為點或多邊形。
互斥欄位的結尾。

PageInfo

頁面詳細資訊。

JSON 表示法 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
欄位
pageviewId

string

網頁瀏覽的專屬 ID。

從同一個網頁瀏覽觸發的所有使用者事件，都應保持相同值。舉例來說，使用者瀏覽作品詳細資料頁面時，可能會觸發多個事件。所有這些事件的 pageviewId 屬性應保持相同，才能正確分組。

使用 JavaScript 像素和 Google 代碼管理工具回報用戶端事件時，系統會自動填入這個值。
pageCategory

string

與類別頁面相關的最明確類別。

如要表示類別的完整路徑，請使用「>」符號分隔不同層級。如果類別名稱包含「>」，請替換成其他字元。

類別頁面包括特價或促銷活動等特殊頁面。舉例來說，特賣頁面的類別階層可能為 "pageCategory" : "Sales > 2017 Black Friday Deals"。

view-category-page 活動的必填欄位。其他事件類型不應設定這個欄位。否則會傳回 INVALID_ARGUMENT 錯誤。
uri

string

使用者目前網頁的完整網址 (window.location.href)。

使用 JavaScript 像素和 Google 代碼管理工具回報用戶端事件時，系統會自動填入這個值。長度上限為 5,000 個半形字元。
referrerUri

string

目前網頁的參照網址。

使用 JavaScript 像素和 Google 代碼管理工具回報用戶端事件時，系統會自動填入這個值。不過，部分瀏覽器隱私權限制可能會導致這個欄位空白。

DocumentInfo

與使用者事件相關的詳細文件資訊。

JSON 表示法 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "id": string,
  "name": string,
  "uri": string
  // End of mutually exclusive fields.
  "quantity": integer,
  "conversionValue": number
}
欄位
promotionIds[]

string

與這份文件相關聯的促銷 ID。目前這個欄位最多只能有一個 ID。
joined

boolean

僅供輸出。參照的文件是否位於資料儲存庫中。

相關 Document 的必要描述符。

  • 如果指定 id，使用儲存的 Document 註解時，系統會使用 {location}、{collection_id}、{data_store_id} 和 {branch_id} 的預設值。

  • 如果指定 name，系統會在以儲存的 Document 進行註解時，使用 {location}、{collection_id}、{data_store_id} 和 {branch_id} 的提供值 (允許預設值)。以下列出互斥欄位。回應中最多會設定一個欄位：
id

string

Document 資源 ID。
name

string

Document 資源完整名稱，格式為：projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

Document URI - 僅適用於網站資料儲存庫。
互斥欄位的結尾。
quantity

integer

與使用者事件相關聯的文件數量。預設值為 1。

舉例來說，如果 add-to-cart 事件涉及兩份相同文件，這個欄位的值就是 2。

下列活動類型必須提供這項資訊：

  • add-to-cart
  • purchase
conversionValue

number

選用。與這份文件相關聯的轉換價值。如果 UserEvent.event_type 為「conversion」，則必須設定。

舉例來說，如果值為 1000，表示使用者觀看「文件」watch轉換類型 1000 秒。

PanelInfo

與使用者事件相關聯的詳細面板資訊。

JSON 表示法 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
欄位
panelId

string

這是必要旗標，面板 ID。
displayName

string

面板的顯示名稱。
documents[]

object (DocumentInfo)

選用。與這個面板相關聯的文件 ID。
panelPosition

integer

如果面板與其他面板一起向使用者顯示，則為面板的排序位置。如果設定這項政策，就必須一併設定 totalPanels。
totalPanels

integer

向使用者顯示的面板總數，包括這個面板。如果已設定 panelPosition，則必須設定這個值。

SearchInfo

詳細搜尋資訊。

JSON 表示法 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
欄位
searchQuery

string

選用。使用者的搜尋查詢。

如需定義，請參閱 SearchRequest.query。

這個值必須是 UTF-8 編碼的字串，長度上限為 5,000 個字元。否則會傳回 INVALID_ARGUMENT 錯誤。

search 事件至少需要一個 searchQuery 或 PageInfo.page_category。其他事件類型不應設定這個欄位。否則會傳回 INVALID_ARGUMENT 錯誤。
orderBy

string

產品退貨的順序 (如適用)。

如需定義和語法，請參閱 SearchRequest.order_by。

值必須是 UTF-8 編碼的字串，長度上限為 1,000 個字元。否則會傳回 INVALID_ARGUMENT 錯誤。

這項設定只能用於 search 事件。其他事件類型不應設定這個欄位。否則會傳回 INVALID_ARGUMENT 錯誤。
offset

integer

整數，指定分頁的目前偏移量 (API 認為相關的產品中，以 0 為索引的起始位置)。

如需定義，請參閱 SearchRequest.offset。

如果這個欄位為負數，系統會傳回 INVALID_ARGUMENT。

這項設定只能用於 search 事件。其他事件類型不應設定這個欄位。否則會傳回 INVALID_ARGUMENT 錯誤。

CompletionInfo

詳細的完成資訊，包括完成歸因權杖和點擊完成資訊。

JSON 表示法 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
欄位
selectedSuggestion

string

選用。使用者選取 CompleteQueryResponse.QuerySuggestion.suggestion。
selectedPosition

integer

使用者選取的 CompleteQueryResponse.QuerySuggestion.suggestion 位置，從 0 開始。

TransactionInfo

交易代表整筆購買交易。

JSON 表示法 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
欄位
currency

string

這是必要旗標，貨幣代碼。請使用三字元 ISO-4217 代碼。
transactionId

string

交易 ID，長度上限為 128 個半形字元。
value

number

這是必要旗標，與交易相關聯的非零總價值。這個值可能包含運費、稅金，或您想納入的總價值其他調整項。
tax

number

與交易相關的所有稅金。
cost

number

與產品相關的所有費用。這些費用可能包括製造費用、非由使用者負擔的運費，或其他任何費用，例如：
discountValue

number

這筆交易套用的折扣總額。這項數據應從 TransactionInfo.value 中排除

舉例來說，如果使用者支付 TransactionInfo.value 金額，則交易的名義 (折扣前) 價值為 TransactionInfo.value 和 TransactionInfo.discount_value 的總和

也就是說，無論折扣值為何，利潤的計算方式都相同，且 TransactionInfo.discount_value 可能大於 TransactionInfo.value：

MediaInfo

媒體專屬的使用者事件資訊。

JSON 表示法 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
欄位
mediaProgressDuration

string (Duration format)

媒體進度時間 (以秒為單位，如適用)。舉例來說，如果使用者已觀看 90 秒的影片，則 MediaInfo.media_progress_duration.seconds 應設為 90。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。
mediaProgressPercentage

number

媒體進度應只使用 mediaProgressDuration 相對於媒體總長度計算。

這個值必須介於 [0, 1.0] 之間 (含)。

如果不是播放作業或無法計算進度 (例如進行中的直播)，則應取消設定這個欄位。

意見回饋

使用者意見回饋相關資訊。這項資訊會用於記錄和指標用途。

JSON 表示法 
{
  "feedbackType": enum (FeedbackType),
  "reasons": [
    enum (Reason)
  ],
  "comment": string,
  "conversationInfo": {
    object (ConversationInfo)
  },
  "llmModelVersion": string,
  "feedbackSource": enum (FeedbackSource),
  "componentVersion": string,
  "dataTermsAccepted": boolean
}
欄位
feedbackType

enum (FeedbackType)

這是必要旗標，指出使用者是否給予正面或負面評價。如果使用者留下負評，可能會有更多意見回饋詳細資料。
reasons[]

enum (Reason)

選用。使用者給予不喜歡的原因。
comment

string

選用。如果使用者給予不喜歡，則為意見回饋的額外使用者留言。
conversationInfo

object (ConversationInfo)

使用者提供意見回饋時的相關對話資訊。
llmModelVersion

string

用於生成回覆的 LLM 模型版本。
feedbackSource

enum (FeedbackSource)

選用。使用者意見回饋的 UI 元件，可能是 GOOGLE_CONSOLE、GOOGLE_WIDGET、GOOGLE_WEBAPP。
componentVersion

string

選用。傳送這份報告的元件版本。
dataTermsAccepted

boolean

選用。顧客是否接受資料使用條款。

FeedbackType

使用者提供的意見類型。

列舉
FEEDBACK_TYPE_UNSPECIFIED 未指定意見類型。
LIKE 使用者給予正面評價。
DISLIKE 使用者給予負評。

原因

使用者留下負評的原因。

列舉
REASON_UNSPECIFIED 原因不明。
INACCURATE_RESPONSE 回覆內容不正確。
NOT_RELEVANT 回覆內容不相關。
INCOMPREHENSIVE 回覆不完整。
OFFENSIVE_OR_UNSAFE 回覆內容令人反感或不安。
FORMAT_AND_STYLES 回覆格式不正確。
BAD_CITATION 回覆內容與查詢內容關聯性不高。
CANVAS_NOT_GENERATED 回覆未生成預期的畫布。
CANVAS_QUALITY_BAD 生成的畫布品質不佳 (例如不準確、不完整、格式混亂)。
CANVAS_EXPORT_FAILED 無法匯出生成的畫布 (例如下載或外部匯出動作未順利完成)。

ConversationInfo

對話資訊，例如問題索引和工作階段名稱。

JSON 表示法 
{
  "questionIndex": integer,
  "session": string,
  "query": {
    object (Query)
  },
  "assistToken": string,
  "answerQueryToken": string,
  "taskName": string
}
欄位
questionIndex

integer

對話訊息中使用者輸入內容的索引。
session

string

新生成或繼續的對話名稱。
query

object (Query)

這是必要旗標，使用者的搜尋查詢。
assistToken

string

選用。可用於擷取助理記錄的權杖。
answerQueryToken

string

選用。可用於擷取答案記錄的權杖。
taskName

string

選用。如果對話是由長時間執行的代理程式工作處理，則為 Sobi 工作的完整資源名稱。格式：projects/{project}/locations/{location}/tasks/{taskId}

FeedbackSource

意見回饋來源 (視整合項目而定)。

列舉
FEEDBACK_SOURCE_UNSPECIFIED 未指定意見回饋來源。
GOOGLE_CONSOLE 意見回饋來源是 Google 控制台。
GOOGLE_WIDGET 意見回饋來源是 Google 搜尋小工具。
GOOGLE_WEBAPP 意見回饋來源是 Google Webapp。
GOOGLE_AGENTSPACE_MOBILE 意見回饋來源為 Google AgentSpace 行動應用程式。

方法

collect

 從瀏覽器寫入單一使用者事件。

import

 大量匯入使用者事件。

purge

 永久刪除篩選條件指定的所有使用者事件。

write

 寫入單一使用者事件。