自訂應用程式的使用者事件簡介

本頁說明自訂搜尋和建議應用程式的使用者事件，包括使用者事件類型、需求條件，以及使用者事件類型範例。

雖然自訂應用程式不一定要有使用者事件，但我們強烈建議您提供。

為確保資料品質良好，Google 建議至少每天上傳事件。匯入過往事件時，請確保資料分布偏向最新的時間戳記。最後時間戳記日期的事件數應等於或大於每日平均事件數。

如需記錄使用者事件的說明，請參閱記錄即時使用者事件。如要大量匯入過去的使用者事件，請參閱「匯入歷來的使用者事件」。

使用者事件類型

使用者瀏覽或搜尋網站時，您可以記錄下列類型的使用者事件：

使用者事件名稱 使用者操作
view-item-list 查看文件面板或文件清單。
view-item 查看文件詳細資料。
view-home-page 查看首頁。
search 搜尋應用程式。

如要瞭解使用者事件物件的詳細資料，請參閱 UserEvent API 參考說明文件。

使用者事件類型範例和結構定義

本節提供自訂應用程式支援的各個事件類型資料格式。我們提供 JavaScript Pixel 的範例，如果是 BigQuery，系統會提供每種型別的完整資料表結構定義。

對於所有使用者事件類型，userId 為選用項目。

注意事項：

  • 只有在執行 A/B 實驗時，才需要 tagIds 欄位。

  • attributionToken 欄位為選填，用於評估成效。search 和 view-item 事件是從建議點擊次數產生，因此應含有歸因符記，以便將事件連結回產生這些事件的建議。

如要進一步瞭解使用者事件物件，請參閱 UserEvent API 參考資料說明文件。

view-item

以下顯示 view-item 使用者事件資料格式。

瀏覽項目事件的搜尋最佳化規定

如要讓搜尋功能根據整體使用者趨勢自動調整搜尋體驗，請上傳下列資料。

請至少每天上傳事件，最遲不得超過 24 小時。

事件指標 事件量/頻率 說明
view-item 個事件 25 萬個檢視項目

至少需要 25 萬個瀏覽項目，才能根據擷取的事件最佳化搜尋體驗。

必要的最少 view_item 物件

下列範例只會顯示 view-item 使用者事件格式的必要欄位。

在大多數情況下，documents 包含相關聯文件的詳細資料。

JavaScript 像素

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

BigQuery

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

必要欄位的模式設為 REQUIRED 或 REPEATED。選用欄位的模式設為 NULLABLE。

請注意，使用 BigQuery 匯入事件時，必須有 eventTime。eventTime 是時間戳記格式的字串。 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-home-page

以下顯示 view-home-page 使用者事件格式。

所需「查看首頁」物件數量下限

下列範例只會顯示 view-home-page 使用者事件格式的必要欄位。

JavaScript 像素

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

BigQuery

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

必要欄位的模式設為 REQUIRED 或 REPEATED。選用欄位的模式設為 NULLABLE。

請注意，使用 BigQuery 匯入事件時，必須有 eventTime。eventTime 是時間戳記格式的字串。 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

以下顯示 search 使用者事件格式。

搜尋事件的搜尋最佳化規定

如要讓搜尋功能根據整體使用者趨勢自動調整搜尋體驗，請上傳下列資料。

請至少每天上傳事件，最遲不得超過 24 小時。

事件指標 事件量/頻率 說明
search 個事件 10 萬次搜尋

至少需要 10 萬次搜尋，才能根據擷取的事件最佳化搜尋體驗。

必要搜尋物件下限

下列範例只會顯示 search 使用者事件格式的必要欄位。

至少須填寫 searchQuery 或 pageCategory 欄位：

  • 針對使用者輸入文字查詢的搜尋事件提供 searchQuery。

  • 使用者透過瀏覽 (即點選類別，而非輸入文字查詢) 找到感興趣的項目時，請提供 pageCategory。

attributionToken 會與搜尋查詢或瀏覽結果一起傳回。

documents 應包含搜尋結果網頁中向使用者顯示的文件 ID 清單。

JavaScript 像素

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "pageInfo": {
    "pageCategory": "CATEGORY_1 > CATEGORY_2",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

BigQuery

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

必要欄位的模式設為 REQUIRED 或 REPEATED。選用欄位的模式設為 NULLABLE。

請注意，使用 BigQuery 匯入事件時，必須有 eventTime。eventTime 是時間戳記格式的字串。 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

關於使用者資訊

userPseudoId 代表不重複的使用者 ID，記錄使用者事件時必須提供這項 ID。

記錄使用者事件時，系統會一併記錄使用者資訊 (UserInfo)，其中包含 userPseudoId 值，以及 (如有的話) userId 值。userId 為選用參數，使用者登入網站時，可做為跨裝置的永久專屬 ID。記錄使用者的 userId後， 搜尋和推薦應用程式 就能為同一位使用者在多部裝置 (例如行動裝置和網頁瀏覽器) 上，產生更個人化的結果。

關於時間戳記

記錄使用者事件時，請務必加入事件發生時間的準確時間戳記。準確的時間戳記可確保事件以正確順序儲存。系統會自動記錄使用 JavaScript 像素收集的事件時間戳記。匯入事件時，您必須在 eventTime 欄位中提供時間戳記，格式須符合 RFC 3339 規定。

後續步驟