關於使用者事件

本頁說明自訂搜尋和推薦應用程式的使用者事件，包括使用者事件類型、相關規定和使用者事件類型的範例。

雖然自訂應用程式不需要使用者事件，但我們強烈建議您使用這類事件。

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

使用者事件類型

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

使用者事件名稱 使用者操作
add-feedback 新增使用者意見回饋。
view-item-list 查看面板或排序的文件清單。
view-category-page 查看類別頁面，例如「首頁」>「電視」>「戲劇」或「首頁」>「電影」>「動作片」。
view-item 查看文件詳細資料。
view-home-page 查看首頁。
search 搜尋資料儲存庫。

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

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

本節將說明自訂應用程式支援的每種事件類型所支援的資料格式。我們提供 JavaScript Pixel 的範例。針對 BigQuery，系統會提供每個類型的完整資料表結構定義。

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

注意事項：

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

  • attributionToken 欄位為選填欄位，用於評估效能。由推薦內容點擊產生的 search 和 view-item 事件應包含歸因符記，以便將事件連結回產生這些事件的推薦內容。

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

view-category-page

以下是 view-category-page 使用者事件格式。

必要的最低 view-category-page 物件

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

雖然網頁通常只會與一個類別相關聯，但 pageCategories 欄位也支援類別階層，您可以提供清單形式的階層。

JavaScript 像素

var user_event = {
  "eventType": "view-category-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "pageInfo": {
    "pageCategory": "category1 > category2"
  }
};

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": "pageCategory",
        "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-item

以下是 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 物件

以下範例只會顯示 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，在記錄使用者事件時必須使用。

記錄使用者事件時所包含的使用者資訊 (UserInfo) 包含 userPseudoId 值，以及 (如有) userId 值。userId 屬於選用項目，可用於跨裝置識別使用者，只要使用者登入網站，即可使用此 ID。為使用者記錄 userId 後，搜尋和推薦應用程式就能在多部裝置 (例如行動裝置和網路瀏覽器) 上，為使用者產生更個人化的結果。

關於時間戳記

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

後續步驟