匯入歷來的使用者事件

本頁面說明如何將過去的事件資料大量匯入 AI Commerce Search。訓練模型時需要使用者事件資料。設定即時事件記錄後，可能需要相當長的時間，才能記錄足夠的使用者事件資料來訓練模型。匯入歷來資料可加快程序。

本頁的匯入程序適用於建議和搜尋。匯入資料後，這兩項服務都能使用這些事件，因此如果您同時使用這兩項服務，就不需要重複匯入相同資料。

你可以從以下來源匯入活動：

Cloud Storage。
BigQuery。
Google Analytics 360 事件的 BigQuery。
Google Analytics 4 事件的 BigQuery。
使用 userEvents.import 方法內嵌事件。

事前準備

為避免匯入錯誤，並確認有足夠的資料可產生良好結果，請先查看下列資訊，再匯入使用者事件。

請參閱記錄使用者事件的最佳做法。
使用者事件格式會因使用者事件類型而異。如要瞭解為各事件類型建立資料表的格式，請參閱「使用者事件類型和範例結構定義」。
建議和搜尋功能有不同的最低資料門檻。請確認使用者事件符合您打算使用的服務需求：
- 如需搜尋和推薦內容的規定，請參閱「使用者事件規定和最佳做法」。
- 如果您使用推薦模型，請參閱「使用者事件資料規定」，瞭解使用不同推薦模型類型和最佳化目標時，需要遵守的其他規定。

匯入事件的注意事項

本節說明可用於批次匯入過往使用者事件的方法、各方法適用的時機，以及部分限制。

匯入來源	說明	使用時機	限制
Cloud Storage	使用 Google Cloud 控制台`curl`或匯入檔案 (≤ 2 GB，最多 100 個) 中的 JSON 資料。支援自訂屬性。	單一步驟即可載入大量資料。	如要將 Google Analytics 資料移至 Cloud Storage，必須先匯出至 BigQuery。
BigQuery	使用 Google Cloud 控制台或 `curl`，從 BigQuery 資料表匯入 AI Commerce Search 結構定義。	在匯入前預先處理或分析事件資料。	需要手動對應結構定義；大量事件的資源成本較高。
BigQuery + Google Analytics 360	將現有的 Google Analytics 360 資料直接匯入 AI Commerce Search。	現有的 GA360 轉換追蹤，不需要手動對應架構。	僅提供部分屬性子集；搜尋需要追蹤 Google Analytics 曝光次數。
BigQuery + Google Analytics 4	將現有 Google Analytics 4 資料直接匯入 AI Commerce Search。	現有的 GA4 轉換追蹤，不需要手動對應架構。	僅提供有限的屬性子集；搜尋需要 `search_query` 事件參數鍵。
內嵌匯入	使用直接 `userEvents.import` 方法呼叫匯入。	高隱私權後端驗證規定。	導入作業比標準網頁匯入更複雜。

大小限制

系統的使用者事件總數上限為 400 億個。根據擷取平台，資料匯入的大小限制如下：

如要從 Cloud Storage 大量匯入，每個檔案的大小不得超過 2 GB，且單一大量匯入要求最多可納入 100 個檔案。
如果是匯入 BigQuery，大小限制為 128 GB。
如果是內嵌匯入，建議每個要求最多匯入 10,000 個使用者事件。
如要瞭解訓練模型和搜尋最佳化所需的最低天數，請參閱模型訓練和調整。初始模型訓練和調整作業可能需要兩到五天，如果資料集較大，則需要更久。

將搜尋事件連結至使用者互動

如要啟用收益最佳化排序 (第 3 層) 和個人化 (第 4 層)，光是上傳一般 search 事件是不夠的。AI 商業搜尋模型需要強烈的信號，才能瞭解使用者意圖和滿意度，進而得知哪些產品在特定查詢中表現良好。這項信號是由可歸因的使用者互動提供。您必須上傳後續活動，具體來說就是 detail-page-view、add-to-cart 和 purchase-complete。

使用者互動的重要性

關聯性信號：search 事件會告知模型使用者想要什麼。detail-page-view (點擊) 會向模型指出哪個結果與查詢相關。
收益信號：add-to-cart 和 purchase-complete 事件會告訴模型哪些結果能帶來實際業務價值。

最佳化資料品質門檻

如要啟用收益最佳化模型，資料必須達到特定量和品質門檻。

必須提供以下指標：

指標	條件	背景資訊
可歸因的點擊量	過去 30 天內有 250,000 個`detail-page-view`事件	這些連結必須有有效的使用者互動，才能連結至搜尋結果。
搜尋活動量	過去 90 天內有 2,000,000 個事件	您必須有大量的歷史搜尋流量做為基準，才能建立統計顯著程度。
點擊密度	每個產品平均有 10 個 `detail-page-view` 事件	確保模型在目錄中獲得足夠的信號涵蓋範圍 (過去 30 天內)。
轉換信號	每個產品平均 0.5 個 `add-to-cart` 事件	建議充分運用可盡量提高收益的目標。
價格涵蓋範圍	95% 的搜尋產品有價格	如果模型不知道退貨產品的價格，就無法盡量提高收益。

詳情請參閱「資料品質」頁面。

使用 BigQuery 或 Cloud Storage 大量匯入

使用 BigQuery 或 Cloud Storage 做為 AI Commerce Search 中使用者事件資料的暫存區，可帶來以下優勢：

提升復原能力：將事件儲存在 BigQuery 或 Cloud Storage 中，可提供可靠的備份機制，必要時可清除並重新擷取。這項復原能力可防止資料遺失，並簡化錯誤或不一致情況下的復原程序。匯入方法也內建復原機制，未擷取的事件會連同錯誤詳細資料儲存在錯誤 bucket 中。
就地進行自訂分析：由於 BigQuery 可輕鬆存取事件，因此您可直接對使用者事件資料執行自訂分析，不必額外匯出或轉移資料。進而實現分析工作流程和即時洞察。
使用現有事件：大量匯入作業可使用以各種格式收集的現有使用者事件資料。簡單的擷取、轉換及載入 (ETL) 程序可將這類資料轉換為 AI Commerce Search 格式，因此不必進行大規模前端變更或複雜的整合。

大量匯入的潛在缺點包括：

即時個人化受限：大量匯入的頻率會限制即時個人化功能。事件產生和擷取之間的轉換時間差，可能會影響個人化搜尋結果的回應速度。
KPI 評估和錯誤回報速度較慢：相較於即時串流，大量匯入程序以批次為導向，因此 KPI 評估和錯誤回報會出現延遲。這可能會阻礙您對新興趨勢或問題做出即時回應。
ETL 管道基礎架構：相較於即時串流，ETL 管道需要建構及監控，以防發生故障。此外，您也需要導入機制，在修正失敗的事件後重試匯入。實作這項功能可能需要一些初步開發工作。

瞭解這些取捨因素，有助於您在 AI 商店搜尋中，根據特定用途和優先要務，選取最合適的使用者事件擷取方式。

從 Cloud Storage 匯入使用者事件

使用 Google Cloud 控制台或 userEvents.import 方法，從 Cloud Storage 匯入使用者事件。

控制台

前往 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search「資料」頁面。

前往「資料」頁面
按一下「匯入」開啟「匯入資料」面板。
選擇「使用者事件」。
選取「Google Cloud Storage」做為資料來源。
選擇「零售使用者事件結構定義」做為結構定義。
輸入資料的 Cloud Storage 位置。
按一下「匯入」。

curl

使用 userEvents.import 方法匯入使用者事件。

建立匯入作業的輸入參數資料檔案。使用 GcsSource 物件指向 Cloud Storage bucket。

你可以提供多個檔案，或只提供一個檔案。
- INPUT_FILE：Cloud Storage 中包含使用者事件資料的檔案。如需各使用者事件類型格式的範例，請參閱「關於使用者事件」。請確認每個使用者事件都位於單一行，且沒有換行符號。
- ERROR_DIRECTORY：Cloud Storage 目錄，用於存放匯入作業的錯誤資訊。
輸入檔案欄位的格式必須為 gs://<bucket>/<path-to-file>/。錯誤目錄的格式必須為 gs://<bucket>/<folder>/。如果錯誤目錄不存在，AI Commerce Search 會建立該目錄。值區必須已存在。
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

如要匯入目錄資訊，請向 userEvents:import REST 方法發出 POST 要求，並提供資料檔案名稱。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl -X POST \
     -v \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     --data @./DATA_FILE.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"
  }
}'

從 BigQuery 匯入使用者事件

使用 Google Cloud 控制台或 userEvents.import 方法，從 BigQuery 匯入使用者事件。

設定 BigQuery 存取權

請按照「設定 BigQuery 資料集的存取權」中的操作說明，為 AI Commerce Search API 服務帳戶授予最低的「BigQuery 使用者」角色，確保匯入作業順利完成，並為 BigQuery 資料集授予額外的「BigQuery 資料編輯者」角色。「BigQuery 資料擁有者」角色並非必要。

從 BigQuery 匯入使用者事件

您可以使用 Gemini Enterprise for Customer Experience 主控台的 AI Commerce Search，或 userEvents.import 方法匯入使用者事件。

控制台

前往 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search「資料」頁面。

前往「資料」頁面
按一下「匯入」開啟「匯入資料」面板。
選擇「使用者事件」。
選取「BigQuery」BigQuery做為資料來源。
選取資料架構。
- Google Analytics 4：用於 Google Analytics 4 事件。
- Google Analytics 360：用於 Google Analytics 360 事件，除非您只從 Google Analytics 360 匯入首頁瀏覽事件 (在這種情況下，請使用零售業使用者事件結構定義)。
- 零售業使用者事件結構定義：用於從 Google Analytics 以外的來源匯入事件，以及僅從 Google Analytics 360 匯入首頁瀏覽事件。
輸入資料所在的 BigQuery 資料表。
選用：在專案中輸入 Cloud Storage bucket 的位置，做為資料的暫時位置。
如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
選用：在 顯示進階選項 下方，輸入專案中 Cloud Storage bucket 的位置，做為資料的暫時位置。

如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
按一下「匯入」。

curl

在對 userEvents.import 方法的呼叫中加入事件資料，即可匯入使用者事件。請參閱 userEvents.import API 參考資料。

您為 dataSchema 指定的值取決於匯入的內容：

user_event_ga4：用於 Google Analytics 4 事件。
user_event_ga360：用於 Google Analytics 360 事件，除非您只從 Google Analytics 360 匯入首頁瀏覽次數 (在這種情況下，請使用 user_event)。
user_event：用於從 Google Analytics 以外的來源匯入事件，以及僅從 Google Analytics 360 匯入首頁瀏覽事件。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
-v \
-X POST \
-H "Content-Type: application/json; charset=utf-8" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

使用 BigQuery 匯入 Analytics 360 使用者事件

下列程序假設您熟悉如何使用 BigQuery 和 Analytics 360。

事前準備

繼續下一個步驟前，請確認下列事項：

您使用加強型電子商務。
您已將 BigQuery 連結至 Analytics 360。

檢查資料來源

請確認您要匯入的使用者事件資料格式正確，且位於您有權存取的 BigQuery 資料表中。

請確認資料表名稱為「project_id:ga360_export_dataset.ga_sessions_YYYYMMDD」。

如要進一步瞭解資料表格式和命名方式，請參閱 Google Analytics 說明文件。
在 BigQuery Google Cloud 控制台中，從「探索工具」面板選取資料表，即可預覽資料表。

請確認下列事項：
1. 「clientId」欄有有效值，例如「123456789.123456789」。
  
  請注意，這個值與完整的 _ga Cookie 值不同 (格式如 GA1.3.123456789.123456789)。
2. 「hits.transaction.currencyCode」欄含有有效貨幣代碼。
  
  注意： AI Commerce Search API purchase-complete 事件類型需要貨幣代碼。如果您要匯入購買事件 (部分 AI 商業搜尋模型需要這類事件)，請更新加強型電子商務報表，加入幣別代碼。
3. 如果您打算匯入 search 事件，請確認資料中是否包含 hits.page.searchKeyword 或 hits.customVariable.searchQuery 欄。
  
  雖然 AI Commerce Search 需要 searchQuery 和 productDetails 才能傳回搜尋結果清單，但 Analytics 360 不會在單一事件中同時儲存搜尋查詢和產品曝光次數。如要使用 AI 商業搜尋，您需要在資料層建立代碼或 JavaScript 像素，才能從 Google Analytics 來源匯入兩種使用者事件：
  - (從 search_term 參數或 view_search_results 事件讀取)，衍生自 hits.page.searchKeyword 或 hits.customVariables.customVarValue (如果 hits.customVariables.customVarName 為 searchQuery)。searchQuery
  - productDetails，即從 view_item_list 事件的 items 參數讀取的產品曝光，如果 hits.product.isImpressions 為 TRUE，則取自 hits.product。

檢查上傳的目錄和 Analytics 360 使用者事件資料表中的商品 ID 是否一致。

使用 BigQuery 資料表預覽畫面中 hits.product.productSKU 欄的任何產品 ID，透過 product.get 方法確認上傳的目錄中是否包含相同產品。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

   curl \
     -v \
     -X GET \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

您可以使用 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search，或 userEvents.import 方法匯入 Google Analytics 360 事件。

控制台

前往 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search「資料」頁面。

前往「資料」頁面
按一下「匯入」開啟「匯入資料」面板。
選擇「使用者事件」。
選取「BigQuery」BigQuery做為資料來源。
選取資料架構。
- Google Analytics 4：用於 Google Analytics 4 事件。
- Google Analytics 360：用於 Google Analytics 360 事件，除非您只從 Google Analytics 360 匯入首頁瀏覽事件 (在這種情況下，請使用零售業使用者事件結構定義)。
- 零售業使用者事件結構定義：用於從 Google Analytics 以外的來源匯入事件，以及僅從 Google Analytics 360 匯入首頁瀏覽事件。
輸入資料所在的 BigQuery 資料表。
選用：在專案中輸入 Cloud Storage bucket 的位置，做為資料的暫時位置。
如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
選用：在 顯示進階選項 下方，輸入專案中 Cloud Storage bucket 的位置，做為資料的暫時位置。

如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
按一下「匯入」。

REST

在對 userEvents.import 方法的呼叫中加入事件資料，即可匯入使用者事件。

請將 dataSchema 替換為 user_event_ga360 值。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

Java

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

如果您已將 Analytics 360 與 BigQuery 整合，並使用加強型電子商務，即可匯入 Analytics 360 使用者事件。

使用 BigQuery 匯入 Analytics 360 首頁瀏覽次數

在 Analytics 360 中，系統不會區分首頁瀏覽事件和其他網頁瀏覽事件。也就是說，在「匯入 Analytics 360 事件」中，系統不會將首頁瀏覽事件與其他事件類型 (例如詳細資料頁面瀏覽) 一併匯入為事件。

下列程序說明如何從 Analytics 360 資料中擷取首頁瀏覽事件，並匯入 AI Commerce Search。簡而言之，做法是將使用者對首頁的瀏覽次數 (以首頁路徑識別) 擷取到新的 BigQuery 資料表中，然後從該資料表將資料匯入 AI Commerce Search。

如要將 Analytics 360 的首頁瀏覽事件匯入 AI Commerce Search，請按照下列步驟操作：

建立 BigQuery 資料集，或確認您有可新增資料表的 BigQuery 資料集。

這個資料集可以位於 AI Commerce Search 專案，也可以位於 Analytics 360 資料所在的專案。這是目標資料集，您會將 Analytics 360 首頁瀏覽事件複製到這個資料集。
在資料集中建立 BigQuery 資料表，步驟如下：
1. 請按照下列方式，替換下列 SQL 程式碼中的變數。
  - target_project_id：步驟 1 中的資料集所在專案。
  - target_dataset：步驟 1 中的資料集名稱。
```
CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
 eventType STRING NOT NULL,
 visitorId STRING NOT NULL,
 userId STRING,
 eventTime STRING NOT NULL
);
```
2. 複製 SQL 程式碼範例。
3. 在 Google Cloud 控制台中開啟 BigQuery 頁面。
  
  前往 BigQuery 頁面
4. 如果尚未選取，請選取目標專案。
5. 在「Editor」(編輯器) 窗格中，貼上 SQL 程式碼範例。
6. 按一下「執行」，然後等待查詢執行完畢。
執行這段程式碼會建立 target_project_id:target_dataset.ga_homepage_YYYYMMDD 格式的表格，例如 my-project:view_events.ga_homepage_20230115。
將 Analytics 360 首頁瀏覽事件從 Analytics 360 資料表複製到上一個步驟 2 建立的表格。
1. 請按照下列方式，替換下列 SQL 範例程式碼中的變數：
  - source_project_id：專案 ID，該專案含有 BigQuery 表格中的 Analytics 360 資料。
  - source_dataset：來源專案中的資料集，內含 BigQuery 資料表中的 Analytics 360 資料。
  - source_table：來源專案中包含 Analytics 360 資料的資料表。
  - target_project_id：與上述步驟 2 中的目標專案 ID 相同。
  - target_dataset：與上一個步驟中的目標資料集相同。
  - 路徑：這是首頁的路徑。通常是 /，例如首頁是 example.com/。不過，如果首頁類似 examplepetstore.com/index.html，路徑就是 /index.html。
```
INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`

SELECT
  "home-page-view" as eventType,
  clientId as visitorId,
  userId,
  CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime

FROM
  `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits

WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;
```
2. 複製 SQL 程式碼範例。
3. 在 Google Cloud 控制台中開啟 BigQuery 頁面。
  
  前往 BigQuery 頁面
4. 如果尚未選取，請選取目標專案。
5. 在「Editor」(編輯器) 窗格中，貼上 SQL 程式碼範例。
6. 按一下「執行」，然後等待查詢執行完畢。
按照「從 BigQuery 匯入使用者事件」一文中的操作說明，從目標資料表匯入首頁瀏覽事件。選取結構定義時，如果使用管理中心匯入，請選取「零售使用者事件結構定義」；如果使用 userEvents.import 匯入，請為 dataSchema 值指定 user_event。
刪除您在步驟 1 和 2 中建立的資料表和資料集。

透過 BigQuery 匯入 Google Analytics 4 使用者事件

如果您已將 Google Analytics 4 與 BigQuery 整合，並使用 Google Analytics 電子商務，即可匯入 Google Analytics 4 使用者事件。

下列程序假設您熟悉如何使用 BigQuery 和 Google Analytics 4。

事前準備

繼續下一個步驟前，請確認下列事項：

你正在使用 Google Analytics 電子商務。
您已將 BigQuery 連結至 Google Analytics 4。

檢查資料來源

如要確保使用者事件資料已準備就緒，可供匯入，請按照下列步驟操作。

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

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

請確認您要匯入的使用者事件資料格式正確，且位於您有權存取的 BigQuery 資料表中。
- 資料集應命名為 analytics_PROPERTY_ID。
- 資料表應命名為 events_YYYYMMDD。
如要瞭解資料表名稱和格式，請參閱 Google Analytics 說明文件。
在 BigQuery Google Cloud 控制台中，從「Explorer」面板選取資料集，然後找出要匯入的使用者事件資料表。

請確認下列事項：
1. event_params.key 欄有 currency 鍵，且相關聯的字串值為有效貨幣代碼。
  
  注意： AI Commerce Search API purchase-complete 事件類型需要貨幣代碼。如果您要匯入購買事件 (部分 AI 電子商務搜尋模型需要這類事件)，請更新事件報表，加入幣別代碼。
2. 如要匯入 search 事件，請確認 event.event_params.key 欄有 search_term 鍵和相關聯的值。
  
  雖然 AI Commerce Search 需要 searchQuery 和 productDetails 才能傳回搜尋結果清單，但 Google Analytics 4 不會在單一事件中同時儲存搜尋查詢和產品曝光。如要使用 AI 商業搜尋，您需要在資料層或 JavaScript 像素中建立代碼，才能從 Google Analytics 來源匯入這兩種使用者事件：
  - searchQuery，可從 search_term 參數或 view_search_results 事件讀取。
  - productDetails，即從 view_item_list 事件的 items 參數讀取的產品曝光。
  如要瞭解 Google Analytics 4 中的 search，請參閱 Google Analytics 說明文件中的search。

檢查上傳的目錄和 Google Analytics 4 使用者事件資料表中的商品 ID 是否一致。

如要確認 Google Analytics 4 使用者資料表中的產品也位於上傳的目錄中，請從 BigQuery 資料表預覽畫面中的 event.items.item_id 欄複製產品 ID，並使用 product.get 方法檢查該產品 ID 是否位於上傳的目錄中。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

   curl \
     -v \
     -X GET \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

匯入 Google Analytics 4 事件

您可以使用 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search，或 userEvents.import 方法匯入 Google Analytics 4 事件。

使用控制台

前往 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search「資料」頁面。

前往「資料」頁面
按一下「匯入」開啟「匯入資料」面板。
選擇「使用者事件」。
選取「BigQuery」BigQuery做為資料來源。
選取資料架構。
- Google Analytics 4：用於 Google Analytics 4 事件。
- Google Analytics 360：用於 Google Analytics 360 事件，除非您只從 Google Analytics 360 匯入首頁瀏覽事件 (在這種情況下，請使用零售業使用者事件結構定義)。
- 零售業使用者事件結構定義：用於從 Google Analytics 以外的來源匯入事件，以及僅從 Google Analytics 360 匯入首頁瀏覽事件。
輸入資料所在的 BigQuery 資料表。
選用：在專案中輸入 Cloud Storage bucket 的位置，做為資料的暫時位置。
如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
選用：在 顯示進階選項 下方，輸入專案中 Cloud Storage bucket 的位置，做為資料的暫時位置。

如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
按一下「匯入」。

使用 API

在對 userEvents.import 方法的呼叫中加入事件資料，即可匯入使用者事件。請參閱 userEvents.import API 參考資料。

請將 dataSchema 替換為 user_event_ga4 值。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

內嵌匯入使用者事件

您可以在呼叫 userEvents.import 方法時加入事件資料，以內嵌方式匯入使用者事件。

最簡單的做法是將使用者事件資料放入 JSON 檔案，然後提供給 curl。

如要瞭解使用者事件類型的格式，請參閱「關於使用者事件」。

curl

建立 JSON 檔案：

{
  "inputConfig": {
    "userEventInlineSource": {
      "userEvents": [
        \{
          "<userEvent1>"
        \},
        \{
          "<userEvent2>"
        \},
        \....
      \]
    \}
  }
}

呼叫 POST 方法：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"

Java

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

歷來目錄資料

您也可以匯入歷史使用者事件中顯示的目錄資料。這類目錄資料很有幫助，因為系統可使用過去的產品資訊來增補使用者事件擷取作業，進而提升模型準確度。

詳情請參閱「匯入歷來目錄資料」。

查看匯入的事件

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

前往「資料」頁面

A/B 測試評估

視測試目標而定，A/B 測試會套用下列參數：

如要以點閱率 (CTR) 為目標，您必須有至少 21 天的使用者事件，或達到特定事件量。例如超過 200 萬個搜尋事件和超過 50 萬次搜尋點擊次數。
如要設定轉換率或收益目標，您必須累積至少 28 天的使用者事件，或達到特定事件量。例如，超過 400 萬個搜尋事件、超過 100 萬次搜尋點擊次數、每個可搜尋產品超過 0.5 個購買事件。

如要進一步瞭解 A/B 測試和最佳做法，請參閱「A/B 測試」頁面。

後續步驟

開始記錄使用者事件。
管理使用者事件。

匯入歷來的使用者事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

匯入事件的注意事項

大小限制

將搜尋事件連結至使用者互動

使用者互動的重要性

最佳化資料品質門檻

使用 BigQuery 或 Cloud Storage 大量匯入

從 Cloud Storage 匯入使用者事件

控制台

curl

從 BigQuery 匯入使用者事件

設定 BigQuery 存取權

從 BigQuery 匯入使用者事件

控制台

curl

使用 BigQuery 匯入 Analytics 360 使用者事件

事前準備

檢查資料來源

控制台

REST

Java

使用 BigQuery 匯入 Analytics 360 首頁瀏覽次數

透過 BigQuery 匯入 Google Analytics 4 使用者事件

事前準備

檢查資料來源

匯入 Google Analytics 4 事件

使用控制台

使用 API

內嵌匯入使用者事件

curl

Java

歷來目錄資料

查看匯入的事件

A/B 測試評估

後續步驟

匯入歷來的使用者事件