關於媒體使用者事件

本頁說明媒體搜尋和推薦應用程式的使用者事件,包括使用者事件類型、相關規定和使用者事件類型的範例。媒體應用程式需要使用者事件。

如要瞭解媒體搜尋和推薦內容的一般資訊,請參閱「媒體搜尋和推薦內容簡介」。

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

使用者事件類型

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

使用者事件名稱 使用者操作
view-category-page 查看類別頁面,例如「首頁」>「電視」>「戲劇」或「首頁」>「電影」>「動作片」。
view-item 查看文件詳細資料。
view-home-page 查看首頁。
search 搜尋資料儲存庫。
media-play 點按媒體項目的播放按鈕。
media-complete 停止播放媒體項目,表示觀看結束。

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

媒體搜尋和推薦功能的事件需求

如要判斷需要收集哪些使用者事件,請參閱下表。

您需要的使用者事件類型取決於應用程式是搜尋應用程式還是推薦應用程式、目標 (點閱率、轉換率或觀看時間),以及 (僅限推薦應用程式) 您選擇的模型類型。如要進一步瞭解推薦模型類型和最佳化目標,請參閱「關於媒體應用程式推薦類型」。

事件 search view-home-page view-category-page view-item media-play media-complete
搜尋用途
必填
必填

必填
必填 必填 必填
依目標區分,推薦的「為您推薦」模型類型
點閱率
必填
首頁背景資訊必須提供

一般背景資訊不必提供

必填
您必須使用 view-itemmedia-play 其中之一 強烈
建議

如果已開啟記錄降級功能,則為必要
連續錄影
必填
首頁背景資訊必須提供

一般背景資訊不必提供

必填
您必須使用 view-itemmedia-play 其中之一 必填
觀看時間
必填
首頁背景資訊必須提供

一般背景資訊不必提供

必填
您必須使用 view-itemmedia-play 其中之一 必填
「你可能會喜歡的其他項目」模型類型,依目標劃分
點閱率
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 強烈
建議

如果已開啟記錄降級功能,則為必要
連續錄影
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 必填
觀看時間
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 必填
More Like This 模型類型 (依目標劃分)
點閱率
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 如果已啟用歷史記錄降級功能,則為必要設定
連續錄影
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 必填
觀看時間
必填

必填

必填
您必須使用 view-itemmedia-play 其中之一 必填
按目標區分最受歡迎的模型類型
點閱率
必填

必填

必填
必須提供 view-itemmedia-play 其中之一
必填
連續錄影
必填

必填

必填

必填

必填
必填

媒體使用者事件的必要條件

請確認使用者事件符合下列規定,以便媒體應用程式產生優質結果。

事件類型 需求 影響
所有活動

請勿加入合成資料或重複事件。

合成或重複事件會對結果品質造成負面影響,甚至可能導致應用程式無法部署。重複事件可能會導致指標值不正確。

每個擷取的事件類型至少包含 100 個不重複使用者虛擬 ID。

這樣一來,媒體推薦應用程式就能取得足夠的資料,產生優質結果。

在事件匯入或事件記錄和媒體推薦要求中,使用者匿名 ID 的格式必須完全相同。

使用一致的使用者匿名 ID 格式,有助於媒體推薦應用程式正確識別訪客模式,並根據使用者行為提供品質更佳的結果。

所有文件都必須提供 DocumentInfo.name 欄位或 DocumentInfo.id 欄位。

媒體推薦應用程式無法使用包含未含 DocumentInfo.name 欄位或 DocumentInfo.id 欄位的文件。

事件中包含的文件應存在於資料儲存庫中。

未連結事件的比率應盡可能維持在低水準。高比率可能會對結果品質造成負面影響。

部分使用者事件應具有相同的使用者虛擬 ID。

如要建構有效的行為序列記錄,媒體推薦應用程式必須能夠查看使用相同使用者假名 ID 的多個事件。

舉例來說,visitor123 查看了五個項目,並點選其中兩個項目的播放按鈕。如果這些事件提供相同且格式一致的使用者匿名 ID,媒體推薦應用程式就能在結果中考量該行為序列。

view-item

每個活動最多只能包含一份文件。

如果沒有文件,就無法使用這項事件。如果包含多個文件,事件就會格式錯誤,無法使用。

search

加入 attributionTokensearch 方法會傳回 attributionToken,以及搜尋或瀏覽結果。

attributionToken 可讓 Vertex AI Search 將搜尋事件正確歸因至特定搜尋回應。

media-play

每個活動最多只能包含一份文件。

如果包含多份文件,事件就會格式錯誤,無法使用。

A/B 測試的使用者事件代碼

如果您進行 A/B 測試,請務必在收集到的所有使用者事件中加入代碼 ID,並為每個測試群組新增一個代碼。

舉例來說,您可以將標記 "tagIds": ["original"] 新增至目前模型的使用者事件,並將標記 "tagIds": ["google"] 新增至 Vertex AI Search for media 的使用者事件。

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

本節將說明媒體推薦功能支援的每種事件類型資料格式。我們提供 JavaScript Pixel 的範例。針對 BigQuery,系統會提供每個類型的完整資料表結構定義。

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

如要進一步瞭解使用者事件物件,請參閱 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 中為此使用者事件類型建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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 中為此使用者事件類型建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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 中為此使用者事件類型建立資料表時,請指定這個結構定義。

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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

系統會隨搜尋查詢結果傳回 attributionToken

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

JavaScript 像素

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

BigQuery

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

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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"
      }
    ]
  }
]

media-play

以下是 media-play 使用者事件格式。

最低必要的媒體播放物件

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

JavaScript 像素

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

BigQuery

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

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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"
          }
        ]
      }
    ]
  }
]

media-complete

以下是 media-complete 使用者事件格式。

必要的媒體完成物件

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

JavaScript 像素

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.2
  }
};

BigQuery

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

必要欄位的模式會設為 REQUIREDREPEATED。選用欄位的模式設為 NULLABLE

請注意,使用 BigQuery 匯入事件時,必須使用 eventTimeeventTime 是採用時間戳記格式的字串。

[
  {
    "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"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

自訂屬性

您可以為使用者事件加入其他自訂屬性和功能。這麼做可為使用者提供更精確的結果。如要新增自訂屬性,請在記錄使用者事件時使用 attributes

如果您為攝入的使用者事件提供自訂屬性,請務必將這些屬性納入與推薦和搜尋要求相關聯的使用者事件。匯入的事件和透過要求提供的事件之間,自訂屬性的格式必須一致。這樣一來,媒體應用程式就能使用這些自訂屬性來提升品質。

您可以使用 text 欄位提供自訂文字值,也可以使用 numbers 欄位提供自訂數值。

舉例來說,以下是記錄使用者事件的要求中 attributes 區段的內容:

  attributes: {
    user_age: {text: ["teen", "young adult"]},
    user_location: {text: ["CA"]},
    user_zip: {numbers: [90210]}
  }

關於使用者資訊

userPseudoId 代表不重複的使用者 ID,在記錄使用者事件時必須使用。

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

關於時間戳記

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

後續步驟