關於媒體使用者事件

本頁說明媒體搜尋和推薦應用程式的使用者事件，包括使用者事件類型、規定，以及使用者事件類型範例。媒體應用程式必須提供使用者事件。

如需媒體搜尋和推薦內容的一般資訊，請參閱「媒體搜尋和推薦內容簡介」。

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

使用者事件類型

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

使用者事件名稱	使用者操作
`view-item`	查看文件詳細資料。
`view-home-page`	查看首頁。
`search`	搜尋應用程式。
`media-play`	點按媒體項目的「播放」。
`media-complete`	停止播放媒體項目，表示觀看結束。

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

媒體搜尋和推薦功能的事件規定

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

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

事件	`search`	`view-home-page`	`view-item`	`media-play`	`media-complete`
搜尋用途
	必填	Not required	必填	必填	必填
「為您推薦」模型類型 (依目標)
點閱率	Not required	首頁內容必須提供一般內容則不需提供	您必須使用 `view-item` 或 `media-play` 其中之一。		強烈建議如果開啟了記錄降級功能，則為必填
CVR	Not required	首頁內容必須提供一般內容則不需提供	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
觀看時間長度	Not required	首頁內容必須提供一般內容則不需提供	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
「你可能喜歡的其他項目」模型類型 (依目標)
點閱率	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		強烈建議如果開啟了記錄降級功能，則為必要條件
CVR	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
觀看時間長度	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
依目標分類的「類似商品」模型類型
點閱率	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		如果已開啟記錄降級功能，則為必填欄位
CVR	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
觀看時間長度	Not required	Not required	您必須使用 `view-item` 或 `media-play` 其中之一。		必填
按目標顯示最熱門的模型類型
點閱率	Not required	Not required	請提供 `view-item` 或 `media-play` 其中之一		Not required
CVR	Not required	Not required	Not required	Not required	必填

媒體使用者事件的規定

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

事件類型	條件	影響
所有活動	請勿加入合成資料或重複事件。	合成或重複事件會對結果品質造成負面影響，且可能導致您無法部署應用程式。重複事件可能會導致指標值不正確。
	針對每種擷取的事件類型，至少要包含 100 個不重複的使用者虛擬 ID。	請加入這些 ID，讓媒體建議應用程式有足夠的資料，產生高品質的結果。
	在事件匯入/記錄和媒體推薦要求中，使用者虛擬 ID 的格式必須完全相同。	使用一致的使用者虛擬 ID 格式，有助於媒體推薦應用程式正確識別訪客模式，並根據使用者行為提供更優質的結果。
	所有文件都必須填寫 `DocumentInfo.name` 欄位或 `DocumentInfo.id` 欄位。	如果事件包含沒有 `DocumentInfo.name` 欄位或 `DocumentInfo.id` 欄位的文件，媒體建議應用程式就無法使用該事件。
	事件中包含的文件應存在於資料儲存庫中。	未加入活動的比例應盡可能降低。比例過高可能會對結果品質造成負面影響。
	部分使用者事件應具有相同的使用者虛擬 ID。	如要建構有效的行為序列記錄，媒體推薦應用程式必須能夠查看具有相同使用者虛擬 ID 的多個事件。舉例來說，`visitor123` 已觀看五個項目，並點選播放其中兩個項目。如果這些事件提供格式一致的使用者虛擬 ID，媒體推薦應用程式就能在結果中納入該行為序列。
`view-item`	每個活動只能包含一份文件。	如果沒有文件，就無法使用這個事件。如果包含多個文件，事件格式會錯誤，無法使用。
`search`	加入 `attributionToken`。 `attributionToken` 會與搜尋或瀏覽結果一併由 search 方法傳回。	`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-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"
  }],
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 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": "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-item 物件範例

下列範例包含 view-item 使用者事件的必要和選填欄位。

JavaScript 像素

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "visitor0",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "abc@example.com",
    "userAgent": "Mozilla/5.0",
  },
  "pageInfo": {
    "pageViewId": "currentPageUri",
    "uri": "http://example",
    "referrerUri": "https://google",
  },
  "attributionToken": "abcd",
  "documents": [
    {
      "id": "abcd",
    },
  ],
  "tagIds": ["Treatment_B"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"],
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345],
    },
  },
  "panels": [
         {
           "panelId": "HOME_RFY_1",
           "documents": [
             {
               "id": "123"
             },
             {
               "id": "456"
             }
           ],
           "panelPosition": 1,
           "totalPanels": 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": "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",
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 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": "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"
          }
        ]
      }
    ]
  }
]

如要瞭解 panels 物件，請參閱「關於面板」。

完整的 view-home-page 物件範例

下列範例包含 view-home-page 使用者事件的必要和選填欄位。

JavaScript 像素

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "visitor0",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "abc@example.com",
    "userAgent": "Mozilla/5.0",
  },
  "pageInfo": {
    "pageViewId": "currentPageUri",
    "uri": "http://example",
    "referrerUri": "https://google",
  },
  "attributionToken": "abcd",
  "documents": [
    {
      "id": "abcd",
      "quantity": 2,
    },
  ],
  "tagIds": ["Treatment_B"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"],
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345],
    },
  },
  "panels": [
         {
           "panelId": "HOME_RFY_1",
           "documents": [
             {
               "id": "123"
             },
             {
               "id": "456"
             }
           ],
           "panelPosition": 1,
           "totalPanels": 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": "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。

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",
  }, 
  "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"
      }
    ]
  }
]

media-play

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

媒體播放物件下限

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

JavaScript 像素

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

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

完整的媒體播放物件範例

下列範例包含 media-play 使用者事件的必要和選填欄位。

JavaScript 像素

var user_event = {
  "eventType": "media-play",
  "userPseudoId": "visitor0",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "abc@example.com",
    "userAgent": "Mozilla/5.0",
  },
  "pageInfo": {
    "pageViewId": "currentPageUri",
    "uri": "http://example",
    "referrerUri": "https://google",
  },
  "attributionToken": "abcd",
  "documents": [
    {
      "id": "abcd",
    },
  ],
  "tagIds": ["Treatment_B"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"],
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345],
    },
  },
};

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

media-complete

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

媒體完整物件的最低要求

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

JavaScript 像素

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.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": "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"
      }
    ]
  }
]

完整的媒體完整物件範例

下列範例包含 media-complete 使用者事件的必要和選填欄位。

JavaScript 像素

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "visitor0",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "abc@example.com",
    "userAgent": "Mozilla/5.0",
  },
  "pageInfo": {
    "pageViewId": "currentPageUri",
    "uri": "http://example",
    "referrerUri": "https://google",
  },
  "attributionToken": "abcd",
  "documents": [
    {
      "id": "abcd",
    },
  ],
  "tagIds": ["Treatment_B"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"],
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345],
    },
  },
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.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": "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，記錄使用者事件時必須提供這項 ID。

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

關於時間戳記

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

關於面板

首頁通常會有一或多個面板，例如「熱門趨勢」面板和「為你推薦」面板。詳細資料頁面也可能顯示面板，例如「你可能也會喜歡」。

使用者事件的面板資訊

view-home-page 和 view-item 類型的建議使用者事件需要面板資訊。如果首頁和詳細資料頁面顯示 Google 推薦的內容，就必須提供面板資訊。

如果您要對面板進行 A/B 測試，則無論來源為何，都必須記錄測試中所有內容的使用者事件和面板資訊。如果首頁和詳細資料頁面沒有 Google 生成的面板內容，建議 (但非必要) 在 view-home-page 和 view-item 事件中提供面板資訊。下表匯總了這些需求：

使用者事件來源 (`view-home-page` 和 `view-item`)	`PanelInfo` (必要)
包括 Google 推薦的內容	是
包括 Google 不建議使用的內容，以及用於 A/B 測試的內容	是
包括 Google 不建議的內容，以及未用於 A/B 測試的內容	否

面板資訊 (PanelInfo) 是一組欄位，用於說明面板的各種元素：

面板的 ID 號碼
顯示名稱
網頁上的面板位置 (例如網頁上的第一個面板 (1)，或網頁上的第三個面板 (3))
網頁上的面板總數
每個面板中顯示的文件清單 (DocumentInfo)

如要進一步瞭解 PanelInfo 物件，請參閱「PanelInfo」。

預先載入面板與延遲載入面板

在網頁或行動網頁上顯示建議內容的常見方法有兩種。您使用的方法會決定記錄的 view-home-page 使用者事件數量和內容。

預先載入：預先載入所有建議項目，使用者抵達頁面時即可看到。在此情況下，使用者載入首頁時，您會記錄一個view-home-page (或 view-item) 使用者事件，其中包含所有面板和文件。
延遲載入：使用者抵達網頁時，系統不會產生面板內容，而是會在使用者向下捲動至面板或向右捲動查看更多建議時，動態載入內容。在這種情況下，當使用者載入首頁時，您會記錄初始 view-home-page (或 view-item) 使用者事件，然後在使用者捲動以產生更多建議內容時，繼續記錄更多事件。在後續事件中，您只需要在 panels 陣列中加入顯示的文件增量。

範例情境

媒體公司的首頁顯示兩個建議面板：

由「最熱門」模型驅動的熱門趨勢面板。
正在進行 A/B 測試的個人化推薦面板。部分使用者會看到由「為你推薦」模型提供的建議面板 (A 組)，其他使用者則會看到公司專有模型提供的建議 (B 組)。

如果指派給 B 群組的使用者瀏覽這個首頁，JavaScript 像素格式的使用者事件會如下所示：

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "4003345673.123451357",
  "eventTime": "2025-07-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "jane.doe@example.com",
  },
  "tagIds": ["group-B"],
  "panels": [
    {
      "panelId": "panel-1",
      "displayId": "Trending Now",
      "documents": [
        {
          "id": "254722"
        },
        {
          "id": "2951"
        },
        ...
        {
          "id": "1201"
        }
      ],
      "panelPosition": 1,
      "totalPanels": 2
    },
    {
      "panelId": "panel-2",
      "displayId": "Recommended for You",
      "documents": [
        {
          "id": "79132"
        },
        {
          "id": "109487"
        },
        ...
        {
          "id": "164179"
        }
      ],
      "panelPosition": 2,
      "totalPanels": 2
    }
  ]
};

後續步驟

瞭解如何記錄使用者事件。

關於媒體使用者事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用者事件類型

媒體搜尋和推薦功能的事件規定

媒體使用者事件的規定

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

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

view-item

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

必要的最少 view_item 物件

JavaScript 像素

BigQuery

完整的 view-item 物件範例

JavaScript 像素

BigQuery

view-home-page

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

JavaScript 像素

BigQuery

完整的 view-home-page 物件範例

JavaScript 像素

BigQuery

搜尋

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

必要搜尋物件下限

JavaScript 像素

BigQuery

media-play

媒體播放物件下限

JavaScript 像素

BigQuery

完整的媒體播放物件範例

JavaScript 像素

BigQuery

media-complete

媒體完整物件的最低要求

JavaScript 像素

BigQuery

完整的媒體完整物件範例

JavaScript 像素

BigQuery

自訂屬性

關於使用者資訊

關於時間戳記

關於面板

使用者事件的面板資訊

預先載入面板與延遲載入面板

範例情境

後續步驟

關於媒體使用者事件