記錄即時使用者事件

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

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

事前準備

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

• 已建立 Google Cloud 專案，並設定驗證。

• 有效的 API 金鑰 (適用於 JavaScript 像素或代碼管理工具)，或已指派 Retail Editor 角色的有效服務帳戶 (如果使用 API 直接寫入)。

必要元件

• 歸因權杖：可根據先前提供的建議或搜尋結果，擷取使用者首次與產品互動的成效指標，以記錄使用者事件。進一步瞭解如何加入歸因代碼。

• 訪客 ID：記錄使用者事件時必須提供。詳情請參閱「關於使用者資訊」。

開始錄製

• 請遵循最佳做法，例如重新加入活動、更新目錄，並盡可能提供詳細資訊。

• 如需使用者事件類型範例和結構定義的 JSON 範例，請參閱「關於使用者事件」頁面。

注意： 請使用安全形式的專屬 ID，確保 Vertex AI Search for Commerce 無法識別使用者身分，並保護使用者隱私。您有責任從資料中遮蓋 PII (個人識別資訊)，例如電子郵件地址或住家地址。

串流傳輸即時使用者事件

雖然大量匯入和即時串流都是在 Vertex AI Search for commerce 中擷取使用者事件的有效機制，但即時串流有幾項細微的優點：

• 立即擴充：即時串流通常不需要額外的擷取、轉換、載入 (ETL) 管道，因此事件量增加時，擴充作業會更加容易。基礎架構通常可以自然成長，不必大幅調整。

• 與 Google Analytics 4 整合：使用 GA4 導入的網站可以透過 Google 代碼管理工具擷取及串流即時事件至 Vertex AI Search for commerce，不必再實作自訂事件追蹤。

• 直接呼叫 API：使用 REST API，即可直接從前端或透過 Proxy 伺服器傳輸即時事件，整合整個程序並減少潛在的故障點。

• 最新的 KPI 評估和錯誤回報：即時事件處理速度更快，因此 KPI 評估和錯誤回報也更即時。方便您更快找出並解決問題。

• 即時個人化：Vertex AI Search for commerce 可擷取並處理即時使用者事件，根據近期的瀏覽和購買行為提供個人化搜尋結果。

即時使用者事件串流方法

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

• 使用 JavaScript 像素。

• 建議使用代碼管理工具搭配 Google Analytics 4。

• 透過 user.Events.write 方法，從後端伺服器直接將事件傳送至 API。

• 代碼管理工具，可單獨使用或與 Google Analytics 4 搭配使用。

• 使用伺服器端代碼時，只要部署一個伺服器端容器，就能記錄多個下游用戶端的事件。

即時串流的潛在缺點

即時串流的潛在缺點可能包括：

• 重新擷取次數有限：與大量匯入不同，大量匯入的資料可暫存在 BigQuery 或 Cloud Storage 中，但如果發生錯誤或資料格式有誤，即時事件就難以重新擷取。因此，在資料擷取點必須有完善的驗證機制，確保資料完整性。

• 自訂分析的挑戰：如果需要自訂分析事件資料，通常必須將事件匯出至 BigQuery 進行後續處理。這可能會成為大量事件串流的瓶頸，進而減緩分析和報表作業。

• 回溯偵錯和事件資料移轉功能受限：直接傳送事件而不經過暫存，會限制對已擷取事件進行回溯鑑識的能力。 另一個潛在限制是，在較低環境中訓練模型時，可能沒有足夠的事件。建立事件資料的暫存區 (BigQuery 或 Cloud Storage) 後，您就能在進行少量資料轉換後，將事件匯入或轉移至其他環境。

瞭解這些細微差異，有助您根據 Vertex AI Search for commerce 生態系統中的特定需求和優先要務，做出明智決策，選擇最合適的使用者事件擷取策略。

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

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

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

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

  您可以在記錄使用者事件之前、之後或同時匯入目錄。如果目錄很大且使用者事件很多，同時執行這些工作可以節省時間。目錄匯入完成後，您必須使用 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 像素記錄使用者事件

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

  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);
  })();
  

如果您已透過 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。

    var tracker = ga.getByName('G-XXXXXX');
    var user_event = {
          "visitorId": tracker.get('clientId')
    };
  

使用 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 電子商務套件。

檢查資料來源

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

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

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

請確認下列事項：

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

2. 如果您打算匯入 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 變數，對事件資料進行網址編碼。

1. 為方便日後進行網址編碼，您可以將 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"
   }'

2. 發出 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 代碼管理工具記錄使用者事件

注意： 您必須使用代碼管理工具，才能在商家適用的 Vertex AI Search 前端使用 Google Analytics 4。

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

設定期間所做的某些決定，取決於您是否使用 Google Analytics 和 Google Analytics 電子商務。Google Analytics 電子商務可使用 Google Analytics 4 或加強型電子商務導入。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 欄位。記錄使用者事件、匯入使用者事件及傳送預測要求時，都應使用相同的時區。使用不一致的訪客 ID 不會傳回錯誤，但會導致使用者事件記錄不完整，進而降低模型個人化品質。

如要將 visitorID 值設為 Cloud Retail 代碼的變數：

1. 在 代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。

2. 在對話方塊頂端為變數命名，例如「Google Analytics visitorId」。

3. 輸入變數設定。

   您可以將用戶端 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。

1. 登入 Google 代碼管理工具，然後選取網站的容器。

2. 前往「代碼」分頁，然後按一下「新增」，即可新增代碼。

3. 在面板頂端為代碼命名 (預留位置為「未命名變數」)，例如「Vertex AI Search for commerce」。

4. 按一下「代碼設定」，然後選擇「Cloud Retail」代碼，開啟代碼設定面板。

5. 輸入 API 金鑰。

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

   您可以在 Google Cloud 控制台的「API 和服務」>「憑證」頁面中，查看 API 金鑰。

6. 輸入啟用 Vertex AI Search for Commerce 的 Google Cloud 專案編號。

   專案編號位於 Google Cloud 控制台資訊主頁。

7. 「使用者事件資料來源」欄位：

   • 資料層 (建議)：如果導入方式屬於下列其中一種，請選取這個選項：

     • 您已透過代碼管理工具導入 Google Analytics 電子商務。重複使用資料層做為事件資料來源， 不必填入新的資料層。如果有的話，這會使用 Google Analytics 4 架構。否則會使用通用 Analytics 加強型電子商務。 使用這個資料來源時，只能記錄 add-to-cart、purchase-complete、detail-page-view 和 search 事件。系統會使用電子商務曝光次數和搜尋查詢 (請參閱「建立搜尋查詢變數」) 記錄 search 事件。

     • 您使用 Google Analytics 電子商務，並可手動填入資料層程式碼。請參閱代碼管理工具開發人員指南。

   • 變數 > Cloud Retail：選取這個選項，即可在代碼管理工具變數中填入 Vertex AI Search for commerce 的必要欄位。如果您未使用 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 維護。如要使用這個範本，請參閱加強型電子商務物件產生器資源庫頁面，瞭解相關說明文件和其他資源。

8. 按一下「+ 覆寫 UserEvent 訊息中的值」按鈕。

9. 針對「欄位選擇器」，請選取 visitorId 做為欄位，然後針對「欄位值」，選取您在「建立訪客 ID 變數」中建立的新訪客 ID 變數。

10. 按一下 [儲存]。

    系統會建立 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」類型的代碼管理工具變數：

1. 在 代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。

2. 在對話方塊頂端為變數命名，例如「search_variable」。

3. 輸入變數設定：

   網址類型

   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;
      }
      

4. 按一下「儲存」儲存變數。

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

1. 在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。

2. 如果代碼的使用者事件資料來源是「變數」>「電子商務」，或是您使用 Google Analytics 電子商務架構的資料層，請勾選「使用加強型電子商務曝光次數建立搜尋事件」核取方塊。

   這樣一來，Vertex AI Search for Commerce 就能根據從這個代碼取得的搜尋資料，判斷使用者事件的類型是否為 search。

3. 在「User Events Data」(使用者事件資料) 部分，按一下「+ Overwrite a value on the UserEvent message」(覆寫 UserEvent 訊息中的值) 按鈕。

4. 從「欄位選取器」選取 searchQuery，然後將搜尋查詢變數設為「欄位值」。

5. 儲存代碼。

下一個：

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

建立及附加常數變數

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

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

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

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

1. 在 代碼管理工具中，前往「變數」分頁，然後按一下「新增」，建立新的使用者定義變數。

2. 在對話方塊頂端為變數命名，例如「search_constant」。

3. 將「變數類型」設為「常數」。

4. 在「值」欄位中輸入 search

5. 按一下「儲存」儲存變數。

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

1. 在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。

2. 在「User Events Data」(使用者事件資料) 部分，按一下「+ Overwrite a value on the UserEvent message」(覆寫 UserEvent 訊息中的值) 按鈕。

3. 從「欄位選取器」選取 eventType，然後將搜尋查詢變數設為「欄位值」。

4. 儲存代碼。

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

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

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

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

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

通常，當使用者瀏覽任何包含 Vertex AI Search 電子商務套件所需事件的頁面 (例如首頁、產品詳細資料頁面、購物車頁面或結帳完成頁面) 時，系統就會觸發代碼。在這些情況下，代碼應在網頁載入後觸發，這樣 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 模型所需的所有使用者事件，重複執行這個程序：

1. 在 代碼管理工具的「觸發條件」頁面中，依序點選「新增」>「觸發條件設定」。

2. 選擇適用於要建立觸發條件的使用者事件的觸發條件類型。

3. 儲存觸發條件。

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

1. 在「代碼管理工具」的「代碼」頁面中，按一下 Cloud Retail 代碼進行編輯。

2. 按一下「觸發條件」，選取新觸發條件，然後按一下「新增」。

3. 儲存代碼。

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

如果使用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 for commerce 事件。

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 電子商務套件記錄的使用者事件觸發。
• 在代碼管理工具中建立 Cloud Retail 代碼，並以「資料層」或「變數」>「電子商務」做為使用者事件資料來源 (請參閱「建立代碼管理工具代碼」)。

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

1. 在「代碼管理工具」的「代碼」頁面中，輸入「Google Analytics 事件」，然後點選 Google Analytics 電子商務代碼進行編輯。

2. 在「進階設定」>「代碼觸發順序」下方，選取「在 <強化電子商務或 GA4 代碼名稱> 觸發後觸發代碼」。

3. 選取 Cloud Retail 代碼做為清除代碼。

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

4. 儲存代碼。

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

如果使用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 欄位值。

注意： 請務必正確填寫 visitorID 欄位。記錄使用者事件、匯入使用者事件及傳送預測要求時，都應使用相同的時區。使用不一致的訪客 ID 不會傳回錯誤，但會導致使用者事件記錄不完整，進而降低模型個人化品質。

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

    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': {
        ...
      },
    }];
  

預覽代碼管理工具代碼

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

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

請按照下列程序操作，確認代碼已正確啟用。

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

   Tag Manager 預覽模式會在新的瀏覽器分頁中開啟。

2. 輸入網站資訊，然後按一下「開始」啟動 Tag Assistant。

   在目前的瀏覽器分頁中，Tag Assistant 會啟動，而您的網站則會在新的分頁中開啟。

3. 在網站上，前往應觸發 Cloud Retail 代碼的任何頁面。

4. 確認 Tag Assistant 在「已觸發的代碼」部分下方的「代碼」分頁中，列出 Cloud Retail 代碼。

5. 在 Tag Assistant 中前往「資料層」分頁，確認系統顯示 cloud_retail 或電子商務資料層中的正確值。

檢查代碼錯誤

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

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

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

1. 在 Chrome 瀏覽器中，為網站開啟代碼管理工具的預覽模式，然後前往應觸發 Cloud Retail 代碼的任何頁面。

2. 開啟預覽模式後，開啟開發人員工具並點選「網路」分頁標籤。

3. 請重新載入頁面。

4. 在開發人員工具中搜尋 userEvent。

   「網路」分頁會顯示 userEvent:collect 事件和狀態碼。

   • 200 回應表示代碼狀態良好。
   • 其他回應 (例如 400 錯誤，以及以紅色醒目顯示事件) 則表示需要進行偵錯。

5. 按兩下事件名稱即可執行要求，並顯示包含更多錯誤資訊的完整回應。

   舉例來說，您可能會看到 400 錯誤，其中包含「'visitorId' is required, and cannot be empty」(必須提供'visitorId'，且不得為空白) 的訊息，表示 visitorId 未正確設定。

6. 如果沒有觸發 userEvent，請檢查開發人員工具的「Console」分頁，確認資料層是否有語法錯誤。

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

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

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

Vertex AI Search for commerce 提供專屬的舊版伺服器端代碼。

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

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

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

設定 Cloud Retail 代碼

查看已記錄的事件

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

前往「資料」頁面

後續步驟

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