Vertex AI Search for retail 已更名為 Vertex AI Search for commerce。我們會更新內容，反映新的品牌形象。

本頁面由 Cloud Translation API 翻譯而成。

記錄即時使用者事件

本頁說明如何記錄即時使用者事件。商家適用的 Vertex AI Search 會使用即時使用者事件，生成推薦內容和搜尋結果。盡可能記錄各個含有有效產品資訊的使用者事件類型，藉此提升結果品質。

本頁的記錄程序適用於推薦內容和搜尋。記錄資料後，這兩項服務都能使用這些事件，因此如果您同時使用這兩項服務，就不必重複上傳相同資料。

事前準備

記錄使用者事件前，請先完成下列事項：

已建立 Google Cloud 專案，並設定驗證。
有效的 API 金鑰 (適用於 JavaScript Pixel 或 Google 代碼管理工具)，或已指派 Retail Editor 角色的有效服務帳戶 (如果使用 API 直接寫入)。

必要元件

歸因權杖：可針對記錄的使用者事件啟用成效指標，根據先前提供的建議或搜尋結果，擷取使用者首次與產品互動的資料。進一步瞭解如何加入歸因權杖。
訪客 ID：記錄使用者事件時必須提供。詳情請參閱「關於使用者資訊」。

記錄使用者事件的一般提示

請遵循最佳做法，例如重新加入活動、隨時更新目錄，以及盡可能提供詳細資訊。
如需使用者事件類型範例和結構定義的 JSON 範例，請參閱「關於使用者事件」頁面。

記錄使用者事件的最佳做法

商家適用的 Vertex AI Search 需要高品質資料，才能生成高品質結果。如果資料不完整或不正確，結果品質就會受到影響。

記錄使用者事件時，請務必遵循下列最佳做法：

如果在匯入目錄之前或期間記錄使用者事件，請重新加入在目錄匯入完成前記錄的任何事件。

您可以在記錄使用者事件之前、之後或同時匯入目錄。如果目錄很大且使用者事件很多，平行執行這些工作可以節省時間。目錄匯入完成後，您必須使用 API 重新加入匯入完成前上傳的事件。

建立使用者事件時，Vertex AI Search for Commerce 會嘗試將記錄的使用者事件與產品目錄中的中繼資料彙整。只有成功彙整的事件會用於訓練，因此請務必重新彙整在目錄完全匯入前記錄的任何事件。如果事件參照的項目不存在於目錄中，系統會捨棄該事件，或不會將其與正確的產品建立關聯。同樣地，如果匯入過去的使用者事件，目錄必須包含使用者提及的任何產品；您可以將舊產品標示為 OUT_OF_STOCK，而非從目錄中移除。
隨時更新目錄。

記錄使用者事件時，系統會將使用者事件中包含的產品與目前的目錄連結。如果為不在目前目錄中的產品記錄事件，就無法用於訓練模型。這稱為「未加入」的活動。如果在目錄完全匯入前記錄了事件，則必須重新彙整在匯入期間記錄的事件。有幾個未加入的活動是正常現象。不過，如果未彙整的事件百分比達到使用者事件總數的 5% 以上，請確保目錄為最新狀態、重新加入目錄完全更新前記錄的事件，並調查未彙整事件的建立原因。

您可以使用事件篩選功能，查看未加入的活動。瞭解詳情。
盡可能提供詳細的使用者事件資訊。

每種使用者事件類型都有不同的必要資訊和可接受的資訊。詳情請參閱「關於使用者事件」。
設定 Cloud Monitoring 快訊，以便在使用者事件記錄程序發生任何中斷時收到通知。
大量匯入使用者事件時，請限制匯入的資料大小。

大量匯入使用者事件最多可能需要 24 小時才能完成。

每個檔案的大小不得超過 2 GB。每項匯入要求中最多可以納入 100 個檔案。其中一種做法是一次只匯入一日的使用者事件。
大量匯入後，請檢查錯誤報表，確認資料匯入正確無誤。
匯入使用者事件資料時，請為每個使用者事件加入準確的時間戳記，並避免匯入時間戳記相同的連續使用者事件。

請在 eventTime 欄位中提供時間戳記，格式須符合 RFC 3339 規定。
如果匯入的使用者事件有誤，請與 Vertex AI Search for Commerce 聯絡人討論如何修正問題。
請盡可能保持使用者事件資料的連續性。

使用者事件資料缺漏可能會降低模型品質。
使用安全的不重複 ID 形式，確保 Vertex AI Search for Commerce 無法識別使用者身分，並保護使用者隱私。您有責任從資料中遮蓋個人識別資訊 (PII)，例如電子郵件或住家地址。

寫入使用者事件的教學課程

本教學課程說明如何使用 userEvents.write 方法記錄使用者事件。

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

串流傳輸使用者事件的方式

您可以透過多種方式記錄使用者事件：

使用 JavaScript 像素。
建議使用代碼管理工具設定 Google Analytics 4 (GA4)。
透過 user.Events.write 方法，從後端伺服器直接將事件傳送至 API。
代碼管理工具，可單獨使用或與 Google Analytics 4 搭配使用。
使用伺服器端代碼，部署單一伺服器端容器和多個下游用戶端，即可記錄事件。

使用 JavaScript 像素記錄使用者事件

下列範例使用 JavaScript 像素記錄 detail-page-view UserEvent。

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

如果您已透過 Google Analytics 360 匯入使用者事件，請將 visitorID 設為 Google Analytics 用戶端 ID。請注意，Google Analytics Client-ID 只是完整 _ga Cookie 名稱的一部分 (例如，Client-ID 123456789.123456789 是 _ga Cookie GA1.3.123456789.123456789 的一部分)。

以下是簡短範例，說明如何在使用者事件中設定用戶端 ID 的格式。將「G-XXXXXX」換成您的 Google Analytics 追蹤 ID。

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

使用 `userEvents.write` 方法記錄使用者事件

您可以使用 userEvents.write 方法，直接從後端伺服器將使用者事件傳送至 API。

如要記錄使用者事件，請傳送 POST 要求至 userEvents.write 方法，並提供適當的要求主體。

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

使用 Google Analytics 4 記錄使用者事件

您可以將 Google Analytics 4 使用者事件資料記錄到 Vertex AI Search for Commerce。

檢查資料來源

請確認要匯入的使用者事件資料格式正確。

如需 Vertex AI Search for commerce 使用的 Google Analytics 4 欄位，以及這些欄位對應的 Vertex AI Search for commerce 欄位表格，請參閱「Google Analytics 4 使用者事件欄位」。

如要查看所有 Google Analytics 事件參數，請參閱「Google Analytics 事件參考資料」一文。

請確認下列事項：

如果您要匯入購買事件 (部分 Vertex AI Search for commerce 模型需要)，事件報表會包含幣別代碼。請參閱 Google Analytics 說明文件中的 purchase 事件參數。
如果您打算匯入 search 事件，事件報表會包含搜尋查詢。

系統支援匯入 search 事件，但 search 事件不會像其他事件類型一樣從 Google Analytics 4 對應，因為 Google Analytics 4 原生不支援 Vertex AI Search for commerce search 事件類型。匯入期間，系統會合併 view_item_list 和 search_term 事件參數的資訊，從 Google Analytics 4 建立search事件search。

請參閱 Google Analytics 說明文件中的 search 事件參數。

記錄 Google Analytics 4 事件

在呼叫 userEvents.collect 方法時，加入事件的網址編碼原始 JSON 資料，即可記錄使用者事件。

針對 prebuilt_rule 參數，請使用 ga4_bq 值。

為方便閱讀，下列使用 userEvents.collect 呼叫的範例會先將 GA4_EVENT 設為變數，其中包含範例事件的原始 JSON 資料。範例中的 userEvents.collect 呼叫會使用 GA4_EVENT 變數，對事件資料進行網址編碼。

為方便日後進行網址編碼，您可以將 GA4_EVENT 設為包含事件資料的變數。這個範例顯示 add-to-cart 事件。

GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

發出 userEvents.collect 呼叫，其中包含使用者事件的網址編碼原始 JSON 資料：

curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

使用 Google 代碼管理工具記錄使用者事件

代碼管理工具可讓您管理及測試多個代碼，不必對網站進行許多伺服器端程式碼變更。

設定期間所做的某些決定，取決於您是否使用 Google Analytics 和 Google Analytics 電子商務。您可以使用 Google Analytics 4 或加強型電子商務，導入 Google Analytics 電子商務。 Cloud Retail 代碼同時支援這兩種做法。

您不需要使用 Google Analytics 或 Google Analytics 電子商務；如果不使用，您可以在建立 Cloud Retail 代碼時，設定「變數 - 電子商務」 (使用 GA4 電子商務結構定義) 或「變數 - Cloud Retail」 (使用 Vertex AI Search for commerce 結構定義)，並在建立代碼後手動填入網站的資料層程式碼。

Google Analytics 電子商務是 Google Analytics 的額外設定，可將產品名稱、ID、價格、交易詳細資料和其他結構化電子商務資料傳送至 Google Analytics。Vertex AI Search for Commerce 可自動使用 Google Analytics 電子商務資料層，因此如果您已設定該資料層，設定作業會更加輕鬆。如果尚未為 Google Analytics 設定 Google Analytics 電子商務，但想使用這項功能，請參閱 Google Analytics 4 開發人員指南，瞭解更多詳細資料和設定說明。

請使用這項一次性程序，在代碼管理工具中設定 Cloud Retail 代碼，記錄使用者事件。

建立訪客 ID 變數

visitorId 值用於追蹤使用者。visitorId 通常是工作階段 ID，所有事件都必須包含這項參數。設定將工作階段 ID 設為 visitorId 的變數。

如果您使用 Google Analytics，可以改用 Google Analytics 訪客 ID。如要設定這項功能，請按照下列程序，覆寫 Cloud Retail 代碼的訪客 ID 值。這會將第一方 Cookie「_ga」對應至名為「GA visitorId」的代碼管理工具變數。任何工作階段 ID Cookie 都可以這麼做，不一定要是 Google Analytics 的 Cookie。

本程序假設您使用 Google Analytics。如果不是，您可以使用其他 Cookie 或變數，也可以從 cloud_retail 資料層取得訪客 ID。

如要將 visitorID 值設為 Cloud Retail 代碼的變數，請按照下列步驟操作：

在代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。
在對話方塊頂端為變數命名，例如「Google Analytics visitorId」。
輸入變數設定。

您可以將用戶端 ID 或 Cookie ID 設為訪客 ID 的來源。在擷取歷史和即時使用者事件時，請一律使用一致的訪客 ID 來源。
用戶端 ID
在 Google Analytics 4 中，這個變數會對應至 Google Analytics 4 BigQuery Export 結構定義中的 user_pseudo_id 欄位。
1. 將「變數類型」設為「自訂 JavaScript」。
2. 在「自訂 JavaScript」欄位中輸入下列指令碼。
  
  將「G-XXXXXX」換成您的 Google Analytics 追蹤 ID。如要找出追蹤 ID，請參閱「我的追蹤 ID 受到什麼影響？」。
  function() { var tracker = ga.getByName('G-XXXXXX'); return tracker.get('clientID'); }
3. 按一下「儲存」儲存變數。
Cookie ID
1. 選擇「第一方 Cookie」做為變數類型。
2. 在「Cookie Name」欄位中輸入「_ga」。
3. 按一下「格式化值」，選取「將未定義的值轉換為...」，然後輸入「""」 (空字串)。
4. 按一下「儲存」儲存變數。
  
  這會將第一方 Cookie「__ga」對應至名為「GA visitorId」的代碼管理工具變數。

接著，在代碼管理工具中建立 Cloud Retail 代碼。這個代碼會使用您剛建立的訪客 ID 變數。

建立 Google 代碼管理工具代碼

在代碼管理工具中設定代碼，將使用者事件資訊傳送至 Vertex AI Search for Commerce。

登入 Google 代碼管理工具，然後選取網站的容器。
前往「代碼」分頁，然後按一下「新增」來新增代碼。
在面板頂端為代碼命名 (預留位置為「未命名變數」)，例如「商家適用的 Vertex AI Search」。
按一下「代碼設定」，然後選擇「Cloud Retail」代碼，開啟代碼設定面板。
輸入 API 金鑰。

設定 Vertex AI Search for Commerce 時，請使用您建立的金鑰。

您可以在 Google Cloud 控制台的「API 和服務」>「憑證」頁面中，查看 API 金鑰。
輸入啟用 Vertex AI Search for Commerce 的 Google Cloud 專案編號。

專案編號可從 Google Cloud 控制台資訊主頁取得。
「使用者事件資料來源」欄位：
- 資料層 (建議)：如果導入方式屬於下列其中一種，請選取這個選項：
  - 您已透過代碼管理工具導入 Google Analytics 電子商務。重複使用資料層做為事件資料來源，不必填入新的資料層。如果有的話，這會使用 Google Analytics 4 架構。否則會使用通用 Analytics 加強型電子商務。使用這個資料來源時，您只能記錄 add-to-cart、purchase-complete、detail-page-view 和 search 事件。系統會使用電子商務曝光次數和搜尋查詢 (請參閱「建立搜尋查詢變數」) 記錄 search 事件。
  - 您使用 Google Analytics 電子商務，且可手動填入資料層程式碼。請參閱代碼管理工具開發人員指南。
- 變數、Cloud Retail：選取這個選項，即可在 Google 代碼管理工具變數中填入商家適用的 Vertex AI Search 必填欄位。如果您未使用 Google Analytics 電子商務，或 Google Analytics 電子商務沒有 Vertex AI Search for commerce 所需的資料，可以選擇這個選項。如果您要從舊版資料層 - Cloud Retail 選項切換至這個來源，請一併建立含有 cloud_retail 鍵的資料層變數，並將其與這個「變數 - Cloud Retail」選項建立關聯。
- 變數，電子商務：如果您未在資料層中使用 Google Analytics 電子商務，且無法手動填入資料層程式碼，但仍想使用 Google Analytics 電子商務結構定義，請選取這個選項。如果您已導入 Google Analytics 電子商務，但想擴增或變更資料層中的值，這項功能也很有用。然後，您可以將這些值匯入 Google Analytics 電子商務結構定義格式的自訂變數，供 Cloud Retail 代碼使用。
  
  在隨即顯示的「讀取使用者變數中的電子商務資料」欄位中，選擇一個變數。這樣一來，Vertex AI Search for Commerce 就能從您建立的自訂變數讀取 Google Analytics 電子商務使用者事件資料。
  
  變數應與 GA4 開發人員指南中所述的格式一致。如要以正確格式建構變數，可以使用強化電子商務物件產生器，或是代碼管理工具社群範本庫的自訂變數範本。社群範本並非由 Google 維護。如要使用這個範本，請參閱加強型電子商務物件產生器資源庫頁面，瞭解相關說明文件和其他資源。
按一下「+ 覆寫 UserEvent 訊息中的值」按鈕。
針對「欄位選擇器」，請選取 visitorId 做為欄位，然後針對「欄位值」，選取您在「建立訪客 ID 變數」中建立的新訪客 ID 變數。
按一下 [儲存]。

系統會建立 Cloud Retail 代碼。

舊版資料來源選項

先前，「資料層 - 電子商務」和「資料層 - Cloud Retail」是資料來源選項。新版代碼不支援這些舊版選項。如果將現有代碼切換為新的資料來源，請使用代碼管理工具預覽，確認無誤後再部署。切換時：

如果您使用「資料層 - 電子商務」，可以改用「資料層」。如果有的話，這會使用 Google Analytics 4 架構。否則會使用通用 Analytics 加強型電子商務。
如果您使用「資料層 - Cloud Retail」，請改用「變數 - Cloud Retail」。建立含有鍵的資料層變數， cloud_retail並將其與「變數 - Cloud Retail」選項建立關聯。

下一個：

如果您使用搜尋功能，請為搜尋查詢建立變數，並將其附加至新代碼。
為代碼建立事件觸發條件。

建立搜尋查詢變數

如果您使用搜尋功能，可以在代碼管理工具中建立搜尋查詢變數，並將其附加至 Cloud Retail 代碼。這樣一來，Vertex AI Search for Commerce 就能從 Analytics 取得搜尋查詢。

您建立的變數類型取決於使用者事件資料來源。

變數 - 電子商務，或使用 Google Analytics 電子商務結構定義的資料層：在代碼管理工具中建立網址或 DOM 元素變數，並將其附加至 Cloud Retail 代碼。此外，請啟用代碼選項，使用 Google Analytics 電子商務曝光資料建立搜尋事件。
變數 - Cloud Retail，或手動填入的資料層：在代碼管理工具中建立網址或 DOM 元素變數，並附加至 Cloud Retail 代碼。如要判斷使用者事件的類型是否為 search，您也必須：
- 為搜尋事件類型建立常數類型變數，並附加至代碼。
- 在資料層或 Cloud Retail 變數中設定搜尋事件類型。

建立並附加搜尋查詢的代碼管理工具變數

如果您使用搜尋功能，可以建立網址、DOM 元素或自訂 JavaScript 變數，並填入網站上輸入的搜尋查詢。

除了這個程序，您也可以設定資料層來提供搜尋查詢資訊。不過，如果您無法存取資料層，或不想設定資料層，可以選擇使用代碼管理工具變數。

您可以建立網址類型變數、DOM 元素類型變數，或自訂 JavaScript (網頁) 變數。您要建立哪個資料流及如何設定，取決於網站的導入方式：

網址變數會從網站的搜尋結果網址取得搜尋查詢。如果網站的搜尋結果網址包含查詢字串，請使用這個變數。
DOM 元素變數會從網站的文件物件模型 (DOM) 取得搜尋查詢資訊。您不需要編輯 DOM 即可使用這個變數。不過，您應該能夠讀取及瞭解 DOM，以便正確設定這個變數。
自訂 JavaScript 變數會傳回由 JavaScript 函式格式化的資料。如果您有現有資料，想以 Cloud Retail 或電子商務架構格式化，這個方法就非常實用。

首先，請建立「網址」、「DOM 元素」或「自訂 JavaScript」類型的代碼管理工具變數：

在代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。
在對話方塊頂端為變數命名，例如「search_variable」。
輸入變數設定：
網址類型
1. 將「變數類型」設為「網址」。
2. 將「元件類型」設為「查詢」。
3. 如果您指定查詢鍵，請將其設為網址中搜尋查詢前的鍵。
  
  舉例來說，如果網址為 http://example.com/?q=shoes，查詢鍵為 q。在本例中，變數的值會設為 shoes。
DOM 元素類型
1. 將「變數類型」設為「DOM 元素」。
2. 設定「選取方式」，然後輸入搜尋查詢的元素 ID 或元素選取器。
  
  這項設定取決於網站是否使用元素 ID 或 CSS 選取器來識別搜尋查詢。
3. 如果您指定屬性，請將其設為包含搜尋查詢字詞的屬性。
  
  舉例來說，如果 DOM 中的搜尋查詢是 <id="search" value="shoes">，屬性就會是 value。在這個範例中，變數的值會設為 shoes。
自訂 JavaScript 類型
1. 將「變數類型」設為「自訂 JavaScript」。
2. 替換下列程式碼中的變數，然後貼到「自訂 JavaScript」窗格中。
3. 在「自訂 JavaScript」窗格中，新增 JavaScript 程式碼，在零售業結構化資料中傳回搜尋事件。
  
  下列程式碼範例會將現有 Ecommerce Items 變數中的資料轉換為 Vertex AI Search for commerce 架構使用的 productDetails 陣列，並傳回完整事件。如要使用這段程式碼，請在代碼管理工具導入作業中，將 Ecommerce Items、Search Query 和 Search Filter 替換為變數。
  function () { var retail; var items = []; for (var i = 0; i < {{Ecommerce Items}}.length; i++) { var item = {'product': { 'id': {{Ecommerce Items}}[i].item_id } }; items.push(item); } retail = { 'eventType': 'search', 'searchQuery': '{{Search Query}}', 'filter': '{{Search Filter}}', 'productDetails': items } return retail; }
按一下「儲存」儲存變數。

接著，將變數附加至 Cloud Retail 代碼：

在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。
如果代碼的使用者事件資料來源為「變數 - 電子商務」，或您使用資料層搭配 Google Analytics 電子商務架構，請選取「使用加強型電子商務曝光次數建立搜尋事件」核取方塊。

這樣一來，Vertex AI Search for Commerce 就能根據從這個代碼取得的搜尋資料，判斷使用者事件的類型是否為 search。
在「User Events Data」部分，按一下「+ Overwrite a value on the UserEvent message」按鈕。
從「欄位選取器」選取 searchQuery，並將搜尋查詢變數設為「欄位值」。
儲存代碼。

下一個：

如果您選擇使用 Cloud Retail 變數或手動填入的資料層，做為 Cloud Retail 代碼的使用者事件來源，請參閱「建立及附加常數變數」。
為代碼建立事件觸發條件。

建立並附加常數變數

如果您選擇「變數 - Cloud Retail」或手動填入的資料層，做為 Cloud Retail 代碼的使用者事件來源，即可使用這個程序。

為搜尋事件建立常數類型變數，並在 Cloud Retail 代碼中將其設為使用者事件覆寫，Vertex AI Search for commerce 就能判斷使用者事件的類型是否為 search。

除了這個程序，您也可以使用資料層或 Cloud Retail 變數指定search使用者事件類型，做為代碼的事件來源。否則，請按照下列步驟設定事件類型。

首先，請建立常數型別變數：

在代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。
在對話方塊頂端為變數命名，例如「search_constant」。
將「變數類型」設為「常數」。
在「Value」(值) 欄位中輸入 search
按一下「儲存」儲存變數。

接著，將變數附加至 Cloud Retail 代碼：

在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。
在「User Events Data」部分，按一下「+ Overwrite a value on the UserEvent message」按鈕。
從「欄位選取器」選取 eventType，並將搜尋查詢變數設為「欄位值」。
儲存代碼。

接著，為代碼建立事件觸發條件。

為代碼管理工具代碼建立事件觸發條件

為 Vertex AI Search for commerce 模型使用的所有使用者事件類型建立觸發條件。

代碼管理工具代碼必須有觸發條件，用來控制代碼在網站上「觸發」的時機。觸發條件會監聽事件發生時間 (例如使用者瀏覽首頁或將商品加入購物車)，並提示代碼將使用者事件資訊傳送至 Vertex AI Search for commerce。

代碼管理工具提供一些標準觸發條件。舉例來說，「視窗載入」是 detail-page-view 事件的觸發條件。如要進一步瞭解各類型，請參閱 Google 代碼管理工具說明文件中的「觸發條件類型」。

通常，您會將代碼設為在使用者瀏覽任何包含 Vertex AI Search for Commerce 所需事件的頁面時觸發，例如首頁、產品詳細資料頁面、購物車頁面或結帳完成頁面。在這些情況下，代碼應在網頁載入後觸發，這樣 Cookie 才能正常運作，所有資料層變數也會填入值。如要達成這個目標，請將觸發條件設為在「視窗載入」或「DOM 就緒」時觸發。

您可能需要在執行動作時觸發代碼，而不是在網頁載入時觸發 (例如，使用者將商品加入購物車時，網頁不會強制重新載入)。在這些情況下，您可以設定網站上的點擊動作，同時將更新推送至資料層，並將觸發條件與該動作建立關聯。

舉例來說，如果您為 add-to-cart 事件建立觸發條件，可以選擇「點擊 - 僅限連結」觸發條件類型，並設為在點擊 ID (本例中為 addtocart) 上觸發。接著，您會在網站上設定 addtocart 連結，在點擊時一併更新資料層的新值：

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

部分使用者事件必須建立自訂觸發條件。一般來說，您會在代碼管理工具中使用使用者事件名稱建立自訂觸發條件。如果無法修改前端程式碼，可以使用 JavaScript 巨集建立自訂觸發條件。如要進一步瞭解自訂觸發條件，請參閱「自訂事件觸發條件」。

請按照下列程序在代碼管理工具中建立觸發條件：

如果尚未設定現有觸發條件：為代碼管理工具代碼建立新觸發條件
如果已設定 Google Analytics 電子商務觸發條件：您可以重複使用為 Google Analytics 電子商務設定的觸發條件，不必建立新的觸發條件。請參閱「重複使用 Google Analytics 電子商務觸發條件」。

為代碼管理工具代碼建立新的觸發條件

如果您未使用 Google Analytics 電子商務，請為 Vertex AI Search for commerce 模型需要的任何使用者事件，建立新的事件觸發條件。然後，將新觸發條件與您在代碼管理工具中建立的 Cloud Retail 代碼建立關聯。

開始執行下列步驟前，請確認您已在代碼管理工具中建立 Cloud Retail 代碼。請參閱「建立代碼管理工具代碼」。

首先，請建立觸發條件。針對 Vertex AI Search for Commerce 模型所需的所有使用者事件，重複執行這個程序：

在代碼管理工具的「觸發條件」頁面中，依序點選「新增」>「觸發條件設定」。
選擇適用於要建立觸發條件的使用者事件的觸發條件類型。
儲存觸發條件。

接著，將新觸發條件與 Cloud Retail 代碼建立關聯。這是一次性程序：

在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。
按一下「觸發條件」，選取新的觸發條件，然後按一下「新增」。
儲存代碼。

接著預覽代碼，並設定監控事件記錄錯誤和其他問題，確保系統持續順利接收資料。

如果使用cloud_retail資料層做為使用者事件來源，請務必設定資料層。

重複使用 Google Analytics 電子商務觸發條件

如果您使用代碼管理工具導入 Google Analytics 電子商務，請重複使用 Google Analytics 電子商務的事件觸發條件，用於 Vertex AI Search for commerce。

使用這個資料來源時，您只能記錄 add-to-cart、purchase-complete、detail-page-view 和 search 事件。系統會使用電子商務曝光次數和搜尋查詢 (請參閱「建立搜尋查詢變數」) 記錄 search 事件。

下表說明 Google Analytics 電子商務和強化電子商務事件如何對應至商家適用的 Vertex AI Search 事件。

Google Analytics 4	加強型電子商務	Vertex AI Search 電子商務套件
`add_to_cart`	`add`	`add-to-cart`
`purchase`	`purchase`	`purchase-complete`
`view_item`	`detail`	`detail-page-view`
`view_item_list`或`view_search_results`	`impressions`	`search` (如果與欄位 `searchQuery` 合併)

開始執行這些步驟前，請先確認下列事項：

在代碼管理工具中設定代碼類型為「Google Analytics - GA4 事件」的代碼，並啟用強化電子商務或 GA4。詳情請參閱代碼管理工具說明文件和 GA4 開發人員指南。
在代碼管理工具中設定強化電子商務或 GA4 代碼，以便在您打算為 Vertex AI Search for Commerce 記錄的使用者事件觸發。
在代碼管理工具中建立 Cloud Retail 代碼，並將「資料層」或「變數 - 電子商務」設為使用者事件資料來源 (請參閱「建立代碼管理工具代碼」)。

如要重複使用 Google Analytics 電子商務觸發條件，請按照下列步驟操作：

在「代碼管理工具」的「代碼」頁面中，按一下 Google Analytics 電子商務代碼 (類型為「Google Analytics - GA4 事件」) 進行編輯。
在「進階設定」>「代碼觸發順序」下方，選取「在 <強化電子商務或 GA4 代碼名稱> 觸發後觸發代碼」。
選取 Cloud Retail 代碼做為清除代碼。

選取「如果無法啟動或已暫停 <加強型電子商務或 GA4 代碼名稱>，則不啟動 <Cloud Retail 代碼名稱>」。
儲存代碼。

接著預覽代碼，並設定事件記錄錯誤和其他問題的監控功能，確保系統持續順利接收資料。

如果使用cloud_retail資料層做為使用者事件來源，請務必設定資料層。

搭配代碼管理工具使用 `cloud_retail` 資料層

如果您在代碼管理工具中建立 Cloud Retail 代碼，並使用cloud_retail資料層做為使用者事件來源，請按照代碼管理工具開發人員指南的說明，在來源 HTML 中設定 dataLayer變數。

關於資料層

大多數代碼管理工具代碼都需要根據使用者或網頁變更的資料 (例如使用者 ID 或產品 ID)。如果是 Cloud Retail 代碼，則必須使用資料層以結構化方式公開資料，代碼管理工具才能使用。

資料層是 JavaScript 物件，通常會使用伺服器端程式碼新增至網頁，或是在前端使用 HTML 或範本新增。如果網頁已設定資料層，就會包含類似下列的程式碼：

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

這段程式碼會建立 dataLayer 物件，並將 cloud_retail 結構指派給該物件做為陣列元素。

`cloud_retail` 資料層中的必填欄位

「關於使用者事件」列出所有必要欄位，以及應傳遞至 cloud_retail 資料層的事件類型範例。

伺服器端程式碼或範本應在要傳送事件的每個頁面上，都有正確的指令碼代碼。在每個頁面上正確填入 dataLayer 物件後，您應該就能測試 Cloud Retail 代碼。

部分欄位 (例如 visitorId) 是 UserEvent 訊息的必要欄位，但填入資料層時可能無法使用。舉例來說，visitorId 可能衍生自使用者的 Cookie，或 experimentIds 衍生自 A/B 實驗架構。在這種情況下，請使用變數覆寫代碼管理工具代碼中的欄位。

您可以覆寫下列欄位：

visitorId
userInfo.userId
attributionToken
experimentIds

如要在代碼管理工具中覆寫 UserEvent 欄位，請參閱「在代碼管理工具中設定 visitorID 欄位」，瞭解如何使用使用者定義變數覆寫 visitorId 欄位值。

以下範例顯示需要納入網頁的資料層，以便透過代碼管理工具傳送 detail-page-view UserEvent：

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

預覽代碼管理工具代碼

代碼管理工具的預覽模式可讓您在發布新代碼前，先在網站上測試。

如要進一步瞭解預覽模式，請參閱代碼管理工具的預覽模式說明文件。

請按照下列程序操作，確認代碼是否正確觸發。

在代碼管理工具總覽頁面中，按一下「預覽」。

Tag Manager 預覽模式會在新的瀏覽器分頁中開啟。
輸入網站資訊，然後按一下「開始」啟動 Tag Assistant。

在目前的瀏覽器分頁中，Tag Assistant 會啟動，而您的網站則會在新的分頁中開啟。
在網站上，前往應觸發 Cloud Retail 代碼的任何頁面。
確認 Tag Assistant 在「已觸發的代碼」部分下方的「代碼」分頁中，列出 Cloud Retail 代碼。
在 Tag Assistant 中前往「資料層」分頁，確認系統顯示 cloud_retail 或電子商務資料層中的正確值。

檢查代碼錯誤

如果預覽代碼時發現部分欄位有誤或缺漏，代碼通常也會傳回錯誤，除非代碼完全未觸發。

您可以在「Search for commerce」控制台的「監控」頁面中查看錯誤。這個頁面會記錄大部分錯誤，但語法錯誤除外，這類錯誤通常只會出現在要求結果中。

您可以按照下列步驟使用 Chrome 開發人員工具，檢查產生的任何錯誤，包括語法錯誤。

在 Chrome 瀏覽器中，為網站開啟代碼管理工具的預覽模式，然後前往應觸發 Cloud Retail 代碼的任何頁面。
開啟預覽模式後，開啟開發人員工具，然後點選「網路」分頁標籤。
請重新載入頁面。
在開發人員工具中搜尋 userEvent。

「網路」分頁會顯示 userEvent:collect 事件和狀態碼。
- 200 回應表示代碼狀態良好。
- 其他回應 (例如 400 錯誤，以及以紅色醒目標示事件) 則表示需要進行偵錯。
按兩下事件名稱即可執行要求，並顯示包含更多錯誤資訊的完整回應。

舉例來說，您可能會看到包含「'visitorId' is required, and cannot be empty」訊息的 400 錯誤，表示 visitorId 未正確設定。
如果沒有觸發 userEvent，請檢查開發人員工具的「Console」分頁，確認資料層是否有語法錯誤。

使用伺服器端代碼記錄使用者事件

使用伺服器端代碼，您可以部署單一伺服器端容器，並搭配多個下游用戶端。這會在用戶端建立單一可靠來源，並提供許多伺服器端消費者。這項架構會將負載從網頁轉移到伺服器，因此對於想盡可能提升網站效能的使用者來說，這項架構非常實用。

伺服器端代碼的另一項優點是，單一伺服器端代碼也能支援許多上游用戶端，例如網頁和行動裝置。瞭解如何設定伺服器端代碼。

商家適用的 Vertex AI Search 提供專屬的舊版伺服器端代碼。

Cloud Retail 伺服器端代碼需要並接受與 Cloud Retail 網站代碼類似的參數，例如：

專案編號
API 金鑰 (用於驗證)
覆寫 visitorId 和 searchQuery 等重要欄位

Cloud Retail 代碼的伺服器版本和網頁版本的主要差異在於，您無法定義資料來源。伺服器代碼的資料來源是 Google 代碼以 GA4 架構傳送的資料串流。

設定 Cloud Retail 代碼

查看已記錄的事件

在「Search for commerce」控制台的「資料」頁面中，查看事件整合指標。這個頁面會顯示去年寫入或匯入的所有事件。成功擷取資料後，最多可能需要 24 小時才會顯示指標。

前往「資料」頁面

後續步驟

進一步瞭解使用者事件。
您也可以匯入歷來的使用者事件。記錄足夠的使用者事件資料來訓練模型，可能需要相當長的時間。您可以從過去的事件大量匯入使用者事件資料，加快初始模型訓練速度。請參閱「匯入歷來的使用者事件」。
如果事件是在目錄匯入完成前記錄，請重新加入事件。
瞭解如何匯入及管理使用者事件。
開始取得預測結果。
監控及排解資料上傳程序的問題。
進一步瞭解代碼管理工具。