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)
    }
  ]
}
欄位
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)

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

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,

  // 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
}
欄位
promotionIds[]

string

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

boolean

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

聯集欄位 document_descriptor。相關 Document 的必要描述元。

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

  • 如果指定 name，系統會在以儲存的 Document 進行註解時，使用 {location}、{collection_id}、{data_store_id} 和 {branch_id} 的提供值 (允許預設值)。document_descriptor 只能是下列其中一項：
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] 之間 (含首尾)。

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

方法

collect

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

import

 大量匯入使用者事件。

purge

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

write

 寫入單一使用者事件。