關於使用者事件

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

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

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

使用者事件類型

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

使用者事件名稱 使用者操作
add-feedback 新增使用者意見回饋。
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 使用者事件資料格式。

所需檢視項目物件下限

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

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

JavaScript 像素

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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",
  "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": "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 使用者事件格式。

必要搜尋物件下限

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

至少須填寫 searchQuery 或 pageCategory 欄位：

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

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

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

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

JavaScript 像素

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  pageInfo: {
    pageCategory: "category1 > category2",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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 指定的格式提供時間戳記。

後續步驟