本頁說明使用者事件物件,包括列出潛在使用者事件類型,並提供所有使用者事件類型的範例資料。
商家適用的 Vertex AI Search 會使用即時使用者事件,產生推薦內容和搜尋結果。上傳資料後,建議和搜尋功能都能使用這些資料,因此如果您同時使用這兩項服務,就不需要重複上傳相同的事件。
搜尋歸因的運作方式
使用者事件類型
使用者瀏覽零售網站時,您可以記錄多種使用者事件類型:
使用者事件名稱 | 使用者操作 | Google Analytics 4 event_name |
---|---|---|
home-page-view | 查看首頁。 | view_homepage |
搜尋 (搜尋和瀏覽) | 搜尋目錄。 | view_item_list + [searchQuery 或 pageCategories + filter ] |
category-page-view (僅限最佳化建議) | 瀏覽特價或促銷活動等特殊頁面。 | view_item_list + pageCategories |
detail-page-view | 查看產品詳細資料頁面。 | view_item |
add-to-cart | 將產品加入購物車。 | add_to_cart |
shopping-cart-page-view | 查看購物車。 | begin_checkout |
purchase-complete | 完成結帳程序。 | purchase |
如需 Google Analytics 4 事件欄位的完整清單,請參閱「Google Analytics 4 使用者事件欄位」。
如要進一步瞭解 UserEvent
物件,請參閱「UserEvent」。
事件類型優先順序
為獲得最高品質的結果,建議您記錄所有事件類型的使用者事件。下表說明不同使用者事件類型的優先順序。您必須記錄優先順序最高的使用者事件,才能建立優質的資料模型。
優先順序 | 使用者事件類型 |
---|---|
建議的初始實驗必須使用這項功能 (事件類型取決於建議模型類型) |
|
搜尋直播實驗需要額外事件 |
使用者事件規定和最佳做法
下表列出建議和搜尋功能使用的使用者事件類型相關規定和最佳做法。請確認使用者事件符合這些規定,Vertex AI Search for Commerce 才能產生優質結果。
這個部分會列出:
如果您使用建議模型,請參閱「模型類型資料需求」,瞭解您打算使用的建議模型類型和最佳化目標,以及其他相關需求。
您可以在「Search for commerce」控制台的「資料品質」頁面,查看搜尋功能的資料品質指標。這些指標會顯示符合建議資料品質標準的產品和使用者事件百分比。如要瞭解如何查看搜尋資料品質,請參閱「解鎖搜尋成效等級」。
一般使用者事件規定
請確認使用者事件符合下列規定,商家適用的 Vertex AI Search 才能生成優質結果。這些限制適用於推薦內容和搜尋結果。
事件類型 | 需求 | 影響 |
---|---|---|
所有活動 |
請勿加入合成資料或重複事件。 |
合成或重複事件會對模型品質造成負面影響,且通常會導致模型訓練失敗。 重複事件可能會導致指標值有誤。 |
針對每種擷取的事件,至少要包含 100 個不重複的訪客 ID。 |
確認商家適用的 Vertex AI Search 有足夠的資料,可產生優質結果。 |
|
在事件匯入或事件記錄和 API 要求中,訪客 ID 的格式必須完全相同。 |
使用一致的訪客 ID 格式,有助於正確識別訪客模式,並根據使用者行為提供更優質的結果。 |
|
活動中包含的產品必須存在於產品目錄中。 |
未加入活動的比例應盡可能降低。如果比例過高,可能會對推薦內容或搜尋結果的品質造成負面影響。 未彙整的事件資料不會用於訓練模型。不過,未彙整的事件可以在相關聯的產品擷取完畢後再彙整。詳情請參閱「重新加入使用者事件」。 |
|
部分使用者事件應具有相同的訪客 ID。 |
如要建構有效的行為序列記錄,Vertex AI Search for commerce 必須能夠查看多個具有相同訪客 ID 的事件。
舉例來說, |
|
detail-page-view |
每個活動只能包含一項產品。 |
如果沒有產品,就無法使用這項事件。如果包含多項產品,事件格式會錯誤,無法使用。 |
add-to-cart |
每個活動只能包含一項產品。 |
如果包含多項產品,事件格式會錯誤,無法使用。 |
purchase-complete |
加入 |
缺少 |
所有購買事件都只能包含一個 沒有預設貨幣代碼,必須提供代碼。 |
如果購買事件缺少這個欄位,收益指標就會不正確。 |
|
確認部分購買事件包含多項產品。 |
如果購買事件包含多項產品,模型就能學習共同購買模式。 |
建議專屬規定
如果您使用建議功能,請確認使用者事件符合下列規定。
如果您使用建議模型,請參閱「模型類型資料需求」,瞭解您打算使用的建議模型類型和最佳化目標,以及其他相關需求。
事件類型 | 需求 | 影響 |
---|---|---|
purchase-complete |
請勿將多項商品購物車攤平為多個購買事件。這些事件應維持單一購買事件,但包含多項產品。 |
這項作業會驗證是否已產生有效的共同購買模式。 |
搜尋廣告專屬規定
如果您使用搜尋功能,請確認使用者事件符合下列最低需求,才能取得結果。
事件類型 | 需求 | 影響 |
---|---|---|
search |
搜尋事件必須有 |
如果未加入這個欄位,可能會對搜尋結果品質和指標造成嚴重負面影響。 |
搜尋要求中的訪客 ID 應與該搜尋要求相關事件中傳送的訪客 ID 相符。 |
如果兩者不相符,表示事件格式有誤,指標可能不正確。 |
|
搜尋事件中的產品 ID 清單必須與向使用者顯示的完整產品清單相符。 |
如果兩者不相符,搜尋結果品質可能會受到嚴重負面影響,指標也會不正確。 |
|
如果搜尋使用篩選器,則必須存在 |
如果沒有這個欄位,Vertex AI Search for Commerce 就無法使用資料的篩選器部分,這可能會對搜尋結果品質造成負面影響。 |
|
加入 |
如果未加入歸因權杖,系統會在 Google 搜尋中顯示錯誤,並對搜尋品質和指標準確度造成嚴重負面影響。 |
搜尋最佳化要求
如要讓搜尋功能根據整體使用者趨勢自動調整搜尋體驗,請上傳下列資料。
請至少每天上傳事件,最晚不得超過 24 小時。
事件指標 | 事件量/頻率 | 說明 |
---|---|---|
search 個事件 |
過去 90 天內有 25 萬次 |
過去 90 天內至少要有 25 萬個事件,才能根據擷取的事件改善搜尋體驗。 建議每天至少上傳一次事件,確保資料品質良好。匯入過往事件時,請確保資料分配偏向最新的時間戳記。最後時間戳記日期的事件數量應等於或大於每日平均事件數量。 |
detail-page-view 可歸因於
search 事件的量 |
最近 30 天內有 500,000 次 | 如要使用使用者事件最佳化搜尋結果,至少需要 500,000 個事件。 |
每個產品可歸因於 detail-page-view 事件的 search 事件平均數 |
最近 30 天內有 10 次 | 必要:如要使用擷取的事件來最佳化搜尋結果,請上傳過去 21 天的事件。 |
可剖析篩選器的 search 事件比例 |
過去 30 天內為 0.1 | 建議用於最佳化搜尋回應中動態 facet 的順序。 |
含有價格的搜尋產品比例 | 最近 30 天內為 0.95 | 必要:使用擷取的事件將搜尋結果最佳化。 |
每個付費產品可歸因於 add-to-cart 事件的 search 事件平均數 |
最近 30 天內為 0.5 | 建議用於收益最佳化的搜尋結果。 |
每個可搜尋的付費產品可歸因於 search 事件的平均 purchase-complete 事件數 |
最近 30 天內為 0.5 | 建議用於收益最佳化的搜尋結果。 |
個人化搜尋規定
搜尋功能需要下列資料,才能根據使用者的活動記錄,提供個人化文字搜尋和瀏覽搜尋結果。
上傳下列資料後,搜尋功能就會自動提供個人化結果。
事件指標 | 事件量/頻率 | 說明 |
---|---|---|
搜尋服務處理的 search 事件量 |
最近 30 天內有 10 萬次 |
如要提供個人化功能,過去 30 天內至少須有 10 萬個搜尋事件。 |
未快取搜尋結果 | 最近 10 萬個使用者事件中,少於 1% 的事件 |
如果您打算使用個人化功能,請勿快取文字搜尋或瀏覽搜尋的搜尋結果。如果對所有訪客都顯示相同的結果,搜尋功能就無法為特定使用者提供真正個人化的結果,而且可能會洩漏使用者的私人資料。如果系統偵測到快取,搜尋功能會自動關閉個人化設定。 如果只快取搜尋結果,搜尋功能仍可提供個人化瀏覽結果。反之,如果只快取瀏覽結果,搜尋服務仍可提供個人化的文字查詢搜尋結果。 |
SearchRequests 與使用者事件之間的訪客 ID 比對 |
最近 100,000 個使用者事件中,有超過 10% 的事件符合條件 |
請確認訪客 ID 的間距和格式在SearchRequests 和使用者事件中一致。一致的訪客 ID 格式可確保搜尋功能正確識別使用者活動。 |
使用者事件類型範例和結構定義
本節提供各支援事件類型的資料格式。
我們提供 JavaScript Pixel 和代碼管理工具的範例。如果是 BigQuery,系統會提供每種類型的完整資料表結構定義。
對於所有使用者事件類型,userId
為選用項目。產品資訊欄位 (priceInfo
和 availability
) 為選填欄位。
注意事項:
- 只有在執行 A/B 實驗時,才需要
experimentIds
欄位。 - 只有商家適用的 Vertex AI Search 才需要
attributionToken
欄位。這項標籤用於評估成效。請勿將歸因符記傳送至predict
、search
和detail-page-view
,或點擊事件。 - 請確保所有活動都使用單一幣別,特別是您打算使用Google Cloud 控制台取得收益指標時。Vertex AI Search for Commerce API 不支援每個目錄使用多種幣別。
如要進一步瞭解使用者事件物件,請參閱 UserEvent
API 參考說明文件。
新增至購物車
以下顯示 add-to-cart
使用者事件格式。
下列範例只會顯示 add-to-cart
使用者事件格式的必要欄位。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "add-to-cart", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": { "value": product-quantity } }] };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'add-to-cart', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' }, 'quantity': product-quantity }] } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] }, { "name": "quantity", "type": "INTEGER", "mode": "REQUIRED" } ] }, { "name": "cartId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
類別頁面檢視
以下顯示 category-page-view
使用者事件格式。
下列範例只會顯示 category-page-view
使用者事件格式的必要欄位。
雖然網頁通常只會與一個類別相關聯,但 pageCategories
欄位也支援類別階層,您可以將其做為清單提供。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "category-page-view", "visitorId": "visitor-id", "pageCategories": ["category1 > category2"] };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'category-page-view', 'visitorId": 'visitor-id', // You can also define the user ID and visitor ID // directly on the Tag Manager tag. 'pageCategories': ['category1 > category2'] } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] } ] }, { "name": "pageCategories", "type": "STRING", "mode": "REPEATED" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
詳細資料頁面檢視
以下顯示 detail-page-view
使用者事件資料格式。
下列範例只會顯示 detail-page-view
使用者事件格式的必要欄位。
在大多數情況下,productDetails
包含相關聯產品的詳細資料,除非是組合包。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "detail-page-view", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" } }] };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'detail-page-view', 'visitorId': 'visitor-id', // You can also define the visitor ID directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' } }] } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] } ] }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
首頁檢視
以下顯示 home-page-view
使用者事件格式。
下列範例只會顯示 home-page-view
使用者事件格式的必要欄位。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "home-page-view", "visitorId": "visitor-id", };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'home-page-view', 'visitorId': 'visitor-id' // You can also define the visitor ID // directly on the Tag Manager tag. } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] }, { "name": "quantity", "type": "INTEGER", "mode": "REQUIRED" } ] }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
完成購買
以下顯示 purchase-complete
使用者事件資料格式。
下列範例只會顯示 purchase-complete
使用者事件格式的必要欄位。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "purchase-complete", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": product-quantity }], "purchaseTransaction": { "revenue": revenue, "currencyCode": "currency-code" } };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'purchase-complete', 'visitorId': 'visitor-id', // You can also define the visitor ID directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' }, 'quantity': product-quantity }], 'purchaseTransaction': { 'revenue': revenue, 'currencyCode': 'currency-code' } } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" }, { "name": "priceInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "price", "type": "FLOAT", "mode": "REQUIRED" }, { "name": "originalPrice", "type": "FLOAT", "mode": "NULLABLE" }, { "name": "currencyCode", "type": "STRING", "mode": "REQUIRED" }, { "name": "cost", "type": "FLOAT", "mode": "NULLABLE" } ] } ] }, { "name": "quantity", "type": "INTEGER", "mode": "REQUIRED" } ] }, { "name": "cartId", "type": "STRING", "mode": "NULLABLE" }, { "name": "purchaseTransaction", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" }, { "name": "revenue", "type": "FLOAT", "mode": "REQUIRED" }, { "name": "tax", "type": "FLOAT", "mode": "NULLABLE" }, { "name": "cost", "type": "FLOAT", "mode": "NULLABLE" }, { "name": "currencyCode", "type": "STRING", "mode": "REQUIRED" } ] }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
搜尋
以下顯示 search
使用者事件格式。
必要搜尋物件下限
以下是 Vertex AI Search for Commerce 傳回搜尋結果清單時,必須提供的最低欄位:
searchQuery
是從search_term
參數或view_search_results
事件讀取。- 系統會從
view_item_list
事件的items
參數讀取productDetails
。其中應包含搜尋結果網頁中向使用者顯示的產品 ID 清單。 userEvents
會擷取 Retail API 需要的所有中繼資料資訊,瞭解使用者與客戶網站的互動方式。
下列範例只會顯示 search
使用者事件格式的必要欄位。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "search", "visitorId": "visitor-id", "searchQuery": "search-query", "pageCategories": ["category1 > category2"], "productDetails": [ { "product": { "id": "product-id1" } }, { "product": { "id": "product-id2" } } ] };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'search', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'searchQuery': 'search-query', 'pageCategories': ['category1 > category2'], 'productDetails': [ { 'product': { 'id': 'product-id1' } }, { 'product': { 'id': 'product-id2' } } ] } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] } ] }, { "name": "searchQuery", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageCategories", "type": "STRING", "mode": "REPEATED" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
自動完成
如要使用自動完成功能,搜尋事件才需要這個欄位。搜尋時不需要。
以下範例顯示使用者輸入「sh」並點選建議清單中的第二個建議「shoes」時,completionDetail
欄位會觸發搜尋事件。如果使用者未點選任何建議,completionDetail
欄位會保持空白。
eventType
必須為 "search"
。
completionAttributionToken
是 completeQuery
回應中的 attributionToken
。
selectedSuggestion
應與 searchQuery
相同。
JavaScript 像素
var user_event = { "eventType": "search", "visitorId": "visitor-id", "searchQuery": "search-query", "pageCategories": ["category1 > category2"], "productDetails": [ { "product": { "id": "product-id1" } }, { "product": { "id": "product-id2" } } ] "completionDetail": { "completionAttributionToken": "completion_token", "selectedSuggestion": "search-query", "selectedPosition": completion_position } };
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'search', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'searchQuery': 'search-query', 'pageCategories': ['category1 > category2'], 'productDetails': [ { 'product': { 'id': 'product-id1' } }, { 'product': { 'id': 'product-id2' } } ] "completionDetail": { "completionAttributionToken": 'completion_token', "selectedSuggestion": 'search-query', "selectedPosition": completion_position } } }); </script>
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] } ] }, { "name": "searchQuery", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageCategories", "type": "STRING", "mode": "REPEATED" }, { "name": "completionDetail", "type": "RECORD" "mode": "NULLABLE" "fields": [ { "name": "completionAttributionToken", "type": "STRING", "mode": "REQUIRED" }, { "name": "selectedSuggestion", "type": "STRING", "mode": "REQUIRED" }, { "name": "selectedPosition", "type": "INTEGER", "mode": "REQUIRED" } ] } ]
查看購物車頁面
以下顯示 shopping-cart-page-view
使用者事件資料格式。
下列範例僅顯示 shopping-cart-page-view
使用者事件格式的必要欄位。
除非購物車內沒有任何商品,否則請提供 productDetails
和 userEvents
物件。
匯入事件時,您必須在 eventTime
欄位中,以 RFC 3339 指定的格式提供時間戳記。
視使用的 API 方法或是否使用其他欄位而定,可能需要其他欄位。(舉例來說,如果使用者事件與實體建立關聯,請務必指定 entity
欄位。)
如要進一步瞭解每個欄位,以及何時需要這些欄位,請參閱 UserEvent
API 參考說明文件。
JavaScript 像素
var user_event = { "eventType": "shopping-cart-page-view"", "visitorId": "VISITOR-ID" "cartId": "CART-ID", "productDetails": [{ "product": { "id": "PRODUCT-ID" }, "quantity": PRODUCT-QUANTITY }] };
請將 PRODUCT-ID
、PRODUCT-QUANTITY
、VISOTOR-ID
和 CART-ID
替換為產品 ID、產品數量、工作階段 ID 和購物車 ID。
代碼管理工具
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'shopping-cart-page-view', 'visitorId': 'VISITOR-ID' // You can also define the visitor ID // directly on the Tag Manager tag. 'cartId': 'CART-ID', 'productDetails': [{ 'product': { 'id': 'PRODUCT-ID' }, 'quantity': PRODUCT-QUANTITY }] } }); </script>
請將 PRODUCT-ID
、PRODUCT-QUANTITY
、VISOTOR-ID
和 CART-ID
替換為產品 ID、產品數量、工作階段 ID 和購物車 ID。
BigQuery
這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。
必要欄位的模式會設為 REQUIRED
或 REPEATED
。選用欄位的模式會設為 NULLABLE
。
請注意,透過 BigQuery 匯入事件時,必須使用 eventTime
。eventTime
是時間戳記格式的字串。
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "visitorId", "type": "STRING", "mode": "REQUIRED" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "experimentIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "productDetails", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "product", "type": "RECORD", "mode": "REQUIRED", "fields": [ { "name": "id", "type": "STRING", "mode": "REQUIRED" } ] }, { "name": "quantity", "type": "INTEGER", "mode": "REQUIRED" } ] }, { "name": "cartId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "ipAddress", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" }, { "name": "directUserRequest", "type": "BOOLEAN", "mode": "NULLABLE" } ] }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" }, { "name": "pageViewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "entity", "type": "STRING", "mode": "NULLABLE" } ]
Google Analytics 4 使用者事件欄位
下表顯示 Google Analytics 4 使用者事件欄位如何對應至 Vertex AI Search for commerce 欄位。
從 Google Analytics 4 匯入或記錄使用者事件前,請確認 Google Analytics 4 使用者事件使用下列欄位,以便 Vertex AI Search for commerce 正確整合資料。
Google Analytics 4 | 零售 |
---|---|
ecommerce.purchase_revenue |
purchaseTransaction.revenue |
event_name |
eventType |
event_timestamp |
eventTime |
items.item_id |
productDetails.product.id |
items.price |
productDetails.product.priceInfo.price |
items.quantity |
productDetails.quantity |
鍵:event_params.key 設為 "currency" 值: event_params.value.string_value |
productDetails.product.priceInfo.currencyCode |
鍵:event_params.key 設為 "currency" 值: event_params.value.string_value |
purchaseTransaction.currencyCode |
鍵:event_params.key 設為 "search_term" 值: event_params.value.string_value |
searchQuery |
user_id |
userInfo.userId |
user_pseudo_id |
visitorId |
後續步驟
- 瞭解如何記錄使用者事件。