關於使用者事件

本頁說明使用者事件物件,包括列出潛在使用者事件類型,並提供所有使用者事件類型的範例資料。

商家適用的 Vertex AI Search 會使用即時使用者事件,產生推薦內容和搜尋結果。上傳資料後,建議和搜尋功能都能使用這些資料,因此如果您同時使用這兩項服務,就不需要重複上傳相同的事件。

搜尋歸因的運作方式

歸因的運作方式

使用者事件類型

使用者瀏覽零售網站時,您可以記錄多種使用者事件類型:

使用者事件名稱 使用者操作 Google Analytics 4 event_name
home-page-view 查看首頁。 view_homepage
搜尋 (搜尋和瀏覽) 搜尋目錄。 view_item_list + [searchQuerypageCategories + 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」。

事件類型優先順序

為獲得最高品質的結果,建議您記錄所有事件類型的使用者事件。下表說明不同使用者事件類型的優先順序。您必須記錄優先順序最高的使用者事件,才能建立優質的資料模型。

優先順序 使用者事件類型

建議的初始實驗必須使用這項功能

(事件類型取決於建議模型類型)

detail-page-view

add-to-cart

purchase-complete

home-page-view

搜尋直播實驗需要額外事件

search

使用者事件規定和最佳做法

下表列出建議和搜尋功能使用的使用者事件類型相關規定和最佳做法。請確認使用者事件符合這些規定,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 的事件。

舉例來說,visitor123 看過五個產品詳細資料頁面,將其中三個產品加入購物車,然後購買了原本看過的五個產品中的兩個。如果這些事件都提供格式一致的相同訪客 ID,Vertex AI Search for commerce 就能在模型中考量該行為序列。

detail-page-view

每個活動只能包含一項產品。

如果沒有產品,就無法使用這項事件。如果包含多項產品,事件格式會錯誤,無法使用。

add-to-cart

每個活動只能包含一項產品。

如果包含多項產品,事件格式會錯誤,無法使用。

purchase-complete

加入 purchase_transaction.revenue

缺少 revenue 欄位的 purchase-complete 事件不會用於訓練模型。

所有購買事件都只能包含一個 purchase_transaction.currency_code

沒有預設貨幣代碼,必須提供代碼。

如果購買事件缺少這個欄位,收益指標就會不正確。

確認部分購買事件包含多項產品。

如果購買事件包含多項產品,模型就能學習共同購買模式。

建議專屬規定

如果您使用建議功能,請確認使用者事件符合下列規定。

如果您使用建議模型,請參閱「模型類型資料需求」,瞭解您打算使用的建議模型類型和最佳化目標,以及其他相關需求。

事件類型 需求 影響
purchase-complete

請勿將多項商品購物車攤平為多個購買事件。這些事件應維持單一購買事件,但包含多項產品。

這項作業會驗證是否已產生有效的共同購買模式。

搜尋廣告專屬規定

如果您使用搜尋功能,請確認使用者事件符合下列最低需求,才能取得結果。

事件類型 需求 影響
search

搜尋事件必須有 searchQuery,瀏覽事件必須有 pageCategories

如果未加入這個欄位,可能會對搜尋結果品質和指標造成嚴重負面影響。

搜尋要求中的訪客 ID 應與該搜尋要求相關事件中傳送的訪客 ID 相符。

如果兩者不相符,表示事件格式有誤,指標可能不正確。

搜尋事件中的產品 ID 清單必須與向使用者顯示的完整產品清單相符。

如果兩者不相符,搜尋結果品質可能會受到嚴重負面影響,指標也會不正確。

如果搜尋使用篩選器,則必須存在 filter 並正確剖析。

如果沒有這個欄位,Vertex AI Search for Commerce 就無法使用資料的篩選器部分,這可能會對搜尋結果品質造成負面影響。

加入 attribution_token 欄位,將其他事件連結回搜尋事件。

如果未加入歸因權杖,系統會在 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 為選用項目。產品資訊欄位 (priceInfoavailability) 為選填欄位。

注意事項:

  • 只有在執行 A/B 實驗時,才需要 experimentIds 欄位。
  • 只有商家適用的 Vertex AI Search 才需要 attributionToken 欄位。這項標籤用於評估成效。請勿將歸因符記傳送至 predictsearchdetail-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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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"

completionAttributionTokencompleteQuery 回應中的 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 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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 使用者事件格式的必要欄位。

除非購物車內沒有任何商品,否則請提供 productDetailsuserEvents 物件。

匯入事件時,您必須在 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-IDPRODUCT-QUANTITYVISOTOR-IDCART-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-IDPRODUCT-QUANTITYVISOTOR-IDCART-ID 替換為產品 ID、產品數量、工作階段 ID 和購物車 ID。

BigQuery

這是這個使用者事件類型的完整 JSON 結構定義。在 BigQuery 中為這類使用者事件建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式會設為 NULLABLE

請注意,透過 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是時間戳記格式的字串。

[
 {
   "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

後續步驟