本文件定義了 YouTube Reporting API 支援的維度。這個 API 可擷取內含頻道或內容擁有者 YouTube 數據分析資料的大量報表。
維度是常見的資料匯總條件,例如使用者活動發生的日期或使用者所在的國家/地區。
每份大量報表都支援預先定義的維度清單,而在任何報表中,每列的資料都有一組不重複的維度值。因此,每一列的維度值的組合將成為該列的主鍵。您不需要指定或指定報表要納入的維度。
核心維度
雖然 YouTube Reporting API 受到《服務條款》中定義的「淘汰政策」,但非核心維度 (和非核心指標) 不受政策影響。本頁定義會明確指明任何屬於核心維度的維度。
以下清單列出 API 的核心維度。這些維度也是 YouTube Analytics API 的核心維度。
詳情請參閱受廢止政策適用的 YouTube API 清單。
尺寸
以下各節將定義 YouTube Reporting API 大量報表中使用的維度。除非另有註明,否則這些維度會用於頻道和內容擁有者報表。
資源
這些維度對應至 YouTube 頻道和內容擁有者管理的資源:
- video_id (核心維度)
- YouTube 影片的 ID。在 YouTube Data API 中,這是
video
資源的id
屬性值。This is a core dimension and is subject to the Deprecation Policy. - playlist_id
- YouTube 播放清單的 ID。在 YouTube Data API 中,這是
playlist
資源的id
屬性值。 - channel_id (核心維度)
- YouTube 頻道的 ID。在 YouTube Data API 中,這是
channel
資源的id
屬性值。This is a core dimension and is subject to the Deprecation Policy. - asset_id (僅適用於內容擁有者報表)
- YouTube Content ID 系統所管理的資產 ID。資產代表您的智慧財產。您可以瀏覽 YouTube 網站,並透過 YouTube 內容管理工具找出資產 ID。您也可以使用 YouTube Content ID API 擷取這些資料。
地理區域
這些維度會識別與使用者活動、廣告成效或預估收益指標相關的地理區域。
- country_code (核心維度)
- 與報表列中的指標相關聯的國家/地區。維度值是兩個字母的 ISO-3166-1 國家/地區代碼,例如
US
、CN
(中國) 或FR
(法國)。國家/地區代碼ZZ
用於回報 YouTube 無法識別相關國家/地區的指標。This is a core dimension and is subject to the Deprecation Policy. - province_code
- 與報表列中的指標相關聯的美國州別或地域。維度值是 ISO 3166-2 代碼,用於識別美國的州或哥倫比亞特區,例如
US-MI
(密西根) 或US-TX
(德州)。州/省代碼US-ZZ
用於回報 YouTube 無法辨別相關美國州別的指標。注意:這個維度不支援用於識別美國外地區域的 ISO 3166-2 值,因為這些領域也有專屬的 ISO 3166-1 國家/地區代碼。也不支援美國以外的子行政區。
時間範圍
- date (核心維度)
- 這個維度會指出與每個報表列中的指標相關聯的日期。在大量報表中,日期指的是從太平洋時間凌晨 12 點開始,到指定的日期、月份和年度晚間 11 點 59 分結束的期間。視當地時間而定,太平洋時間為 UTC-7 或 UTC-8。
請注意,雖然日期通常代表的是 24 小時,但向日光節約時間調整時鐘的日期代表 23 小時,而時鐘往後調整的日期則代表 25 小時。 This is a core dimension and is subject to the Deprecation Policy.
播放位置
您可以透過這些維度深入瞭解使用者活動的網頁或應用程式。
- playback_location_type
-
這個維度會指出發生使用者活動的網頁或應用程式類型。下表列出維度值:
值 0
這項資料的統計依據為在影片的 YouTube 觀賞頁面或 YouTube 官方應用程式 (例如 YouTube Android 應用程式) 中發生的活動。 1
這項資料適用於透過 <iframe>
或<object>
嵌入式嵌入影片的另一個網站或應用程式中的活動。2
這項資料與 YouTube 頻道頁面發生的活動有關。 5
這些資料與無法分類為上述任一其他地區類型的指標相關。 7
這類觀看次數會計入 YouTube 首頁或主畫面、使用者的訂閱內容動態消息,或其他 YouTube 瀏覽功能的觀看次數。 8
這項資料適用於直接顯示在 YouTube 搜尋結果網頁上的觀看次數。 10
這項資料的計算依據為 YouTube Shorts 動態中影片的觀看次數, - playback_location_detail
- 這個維度會指出播放位置的網址或應用程式。這項維度僅適用於嵌入式播放器中發生的觀看次數,也就是說,只有維度值為
1
的資料列才會填入維度值。在其他列中,這個維度的值會是空白。
播放詳細資料
- live_or_on_demand
- 這個維度會指出資料列中的使用者活動指標是否與現場直播的觀看次數相關。這個維度的資料開始日期為 2014 年 4 月 1 日。
下表列出維度值:
值 live
列的資料則描述現場直播期間的使用者活動。 onDemand
而資料列的資料則說明非在現場直播期間發生的使用者活動。 - subscribed_status
- 這個維度指出資料列中的使用者活動指標,是否與訂閱影片或播放清單頻道的觀眾相關。
可能的值為
subscribed
和unsubscribed
。
請注意,維度值是使用者活動發生時產生的正確資料。例如,假設使用者未訂閱某個頻道,但在觀看該頻道影片後,於同一天訂閱了該頻道,觀看另一部影片。 管道報表指出,一項檢視畫面的subscribed_status
值為subscribed
,而一項檢視畫面的subscribed_status
值為unsubscribed
。
流量來源
- traffic_source_type
- 這個維度會指出與使用者活動指標相關聯的參照網址類型。參照網址類型是指使用者到達與報表中資料列相關的影片或頻道的方法。下表列出維度值:
值 0
直接或不明
這個值包含直接流量到網頁以及參照網址不明的網頁。在查詢報表中,這個流量來源類型會識別為NO_LINK_OTHER
或UNKNOWN_MOBILE_OR_DIRECT
。1
YouTube 廣告
觀眾透過廣告介紹影片。在流量來源報表中,如果這個維度的值是1
,則 traffic_source_detail 維度會指出觀眾所看到的廣告類型。在查詢報表中,這個流量來源類型會識別為ADVERTISING
。可能的值包括:值 ctp_engagement_ad
隨點即播參與廣告 engagement_ad
參與式廣告 googlemediaads
Google 搜尋廣告 insearch_display
TrueView 搜尋結果廣告和多媒體廣告 instream
TrueView 串流內廣告 instream-select
已保留的可略過串流內廣告 unknown
未分類的 YouTube 廣告 video_wall
影片牆 yva
首頁影片廣告 3
瀏覽功能
觀眾透過會前往影片或頻道的 YouTube 頁面,在流量來源報表中,如果這個維度的值是3
,則「traffic_source_detail」traffic_source_detail維度會指出帶來流量的特徵。在查詢報表中,這個流量來源類型會識別為SUBSCRIBER
。可能的值包括:值 explore
兒童:探索 learning
兒童:學習 music
音樂動態消息 my-history
觀看記錄 my-subscriptions
我的訂閱內容 my-uploads
我的上傳內容 podcasts
Podcast 到達網頁 shows
兒童:節目 watch-later
稍後觀看 what-to-watch
推薦內容 4
YouTube 頻道
觀眾來自 YouTube 頻道頁面。在流量來源報表中,如果這個維度的值是4
,則「traffic_source_detail」traffic_source_detail維度會指定該管道的管道 ID。在查詢報表中,這個流量來源類型會識別為YT_CHANNEL
。5
YouTube 搜尋
觀眾來自 YouTube 搜尋結果。在流量來源報表中,如果這個維度的值是5
,則「traffic_source_detail」traffic_source_detail維度可指定相關搜尋字詞。在查詢報表中,這個流量來源類型會識別為YT_SEARCH
。7
建議的影片
觀眾來自其他影片觀賞頁面的相關影片資訊。在流量來源報表中,如果這個維度的值是7
,則 traffic_source_detail 維度會指出該影片的影片 ID。在查詢報表中,這個流量來源類型會識別為RELATED_VIDEO
或YT_RELATED
。8
其他 YouTube 功能
觀眾所推薦的 YouTube 頁面,不屬於任何其他所列流量來源類型。在流量來源報表中,如果這個維度的值是8
,則 traffic_source_detail 維度會指出網頁網址。在查詢報表中,這個流量來源類型會識別為YT_OTHER_PAGE
。可能的值包括:值 g-crec
推薦頻道 offline
離線 promotion
合作夥伴宣傳計劃 unknown
不明 widget
Android 主畫面小工具 youtu.be
youtu.be ytremote
YouTube 遙控器 9
外部
觀眾透過其他網站的連結推薦。這個流量來源包含來自 Google 搜尋結果的參照連結網址。在流量來源報表中,如果這個維度的值是9
,則 traffic_source_detail 維度會指出外部網頁。在查詢報表中,這個流量來源類型會識別為EXT_URL
。11
影片資訊卡和註解
觀眾點按其他影片中的註解或資訊卡來轉介觀眾。在查詢報表中,這個流量來源類型會識別為ANNOTATION
。14
播放清單
影片在播放清單中播放時的觀看次數。這個流量來源類型在查詢報表中會標示為「PLAYLIST
」。
請注意,這個流量來源與來源類型18
不同,後者代表觀看次數來自列出播放清單中所有影片的頁面。17
通知
觀眾來自 YouTube 的電子郵件或通知。在查詢報表中,這個流量來源類型會識別為NOTIFICATION
。可能的值包括:值 inbox
push
sdig
來自訂閱者摘要通知的觀看次數 uploaded_other
來自非推播通知、電子郵件或收件匣通知等非推播通知帶來的觀看次數,在影片上傳時傳送給訂閱者 uploaded_push
影片上傳時傳送給訂閱者的推播通知的觀看次數 18
播放清單頁面
來自列出播放清單中所有影片的頁面的觀看次數。這個流量來源類型在查詢報表中會標示為「YT_PLAYLIST_PAGE
」。
請注意,這個流量來源與來源類型「14
」不同,後者代表影片在播放清單中播放時產生的觀看次數。19
版權內容的節目規劃
這些觀看次數來自已聲明版權的使用者上傳影片,也就是內容擁有者用來宣傳已觀看的內容。在查詢報表中,這個流量來源標識為CAMPAIGN_CARD
。只有內容擁有者報表才支援這個流量來源。20
互動式影片片尾
來自另一部影片的片尾的觀看次數。在查詢報表中,這個流量來源類型會識別為END_SCREEN
。23
短片故事
觀眾在短片故事中的觀看體驗中,以垂直滑動的方式從上一部影片中切換過。24
Shorts
觀眾在 Shorts 觀看體驗中,以垂直滑動的方式從上一部影片來來是指他們。25
產品頁面
產品頁面上的影片將觀眾帶往其他頻道。26
主題標記頁面
來自隨選影片主題標記頁面或 Shorts 主題標記分類頁面的觀看次數。27
音效使用頁面
來自 Shorts 音效分類頁面的觀看次數。28
直播重新導向
來自直播重新導向的觀看次數。30
重混影片
來自 Shorts 播放器中的重混影片連結的觀看次數。31
直向直播影片
來自直向直播影片的觀看次數。32
相關影片
來自 Shorts 播放器中相關影片連結的觀看次數。 - traffic_source_detail
- 這個維度提供了資料列的 traffic_source_type 維度值流量來源的詳細資料。系統會為下列 traffic_source_type 維度值填入這個維度值:
1
- 維度值代表向觀眾放送的廣告類型。如需可能值的清單,請參閱 traffic_source_type 定義。3
- 維度值代表帶來轉介流量的 YouTube 功能。如需可能值的清單,請參閱 traffic_source_type 定義。4
- 維度值會指定使用者招攬到的頻道 ID。5
- 維度值會指定吸引轉介流量的搜尋字詞。7
- 維度值代表吸引觀眾收看的影片。8
- 維度值代表帶來廣告流量的 YouTube 網頁類型。如需可能值的清單,請參閱 traffic_source_type 定義。9
- 維度值代表產生流量的外部網頁。17
- 維度值會指出吸引轉介流量的通知類型。如需可能值的清單,請參閱 traffic_source_type 定義。19
- 維度值代表吸引觀眾收看的影片。20
- 維度值代表吸引觀眾收看的影片。25
- 維度值代表產品 ID,也就是 Google 知識圖譜 ID。26
- 維度值會識別吸引到流量的主題標記。27
- 維度值代表吸引觀眾收看的影片。28
- 維度值會指定透過直播重新導向引介觀眾的頻道 ID。30
- 尺寸值會指定系統推薦觀眾的影片。
裝置
- device_type
- 這個維度可識別影片播放時裝置的實際板型規格。
下表列出有效的維度值:
值 100
不明 101
電腦 102
電視 103
遊戲主機 104
手機 105
平板電腦 - operating_system
- 這個維度可識別影片播放時裝置的軟體系統。
下表列出有效的維度值:
值 1
其他 2
Windows 3
Windows Mobile 4
Android 5
iOS 6
Symbian 7
Blackberry 9
Macintosh 10
PlayStation 11
Bada 12
WebOS 13
Linux 14
Hiptop 15
MeeGo 16
Wii 17
Xbox 18
PlayStation Vita 19
智慧型電視 20
任天堂 3DS 21
Chromecast 22
Tizen 23
Firefox 24
RealMedia 25
KaiOS 26
Roku 27
Nintendo Switch 28
Apple tvOS 29
Fire OS 30
ChromeOS 31
Vidaa
客層
客層維度有助於瞭解觀眾的年齡層和性別分佈情形。如要進一步瞭解 YouTube Analytics 報表中的客層資料,請造訪 YouTube 說明中心。
- age_group (核心維度)
- 這個維度可識別與報表資料相關聯的登入使用者年齡層。API 使用下列年齡層:
AGE_13_17
AGE_18_24
AGE_25_34
AGE_35_44
AGE_45_54
AGE_55_64
AGE_65_
- gender (核心維度)
- 這個維度會指出與報表資料相關的已登入使用者性別。
有效值為
FEMALE
、MALE
和GENDER_OTHER
。This is a core dimension and is subject to the Deprecation Policy.
參與度和內容分享
- sharing_service (核心維度)
- 這個維度代表用於分享影片的服務。你可以使用「分享」按鈕在 YouTube (或透過 YouTube 播放器) 分享影片。This is a core dimension and is subject to the Deprecation Policy.
下表列出有效的維度值:
值 0
不明 1
迪格 4
reddit 5
StumbleUpon 6
mixi 7
Yahoo! 日本 8
goo 9
Ameba 10
Facebook 11
Myspace 12
NUjij 18
鐘乳石 20
男性 21
威科普 22
天空藍 25
福卡 28
hi5 31
Twitter 32
變色世界 34
Blogger 36
VKontakte (hackerонтакте) 37
樂天 (天城) 38
LiveJournal 39
Odnoklasniki (estдноклассники) 40
tumblr. 42
LinkedIn 43
Google+ 44
微博 45
Pinterest 46
電子郵件 47
Facebook Messenger 49
WhatsApp 50
Hangouts 51
Gmail 52
Kakao (Kakao Talk) 53
其他 55
複製到剪貼簿 59
Embed 60
簡訊 61
Android 訊息應用程式 62
Verizon 訊息 63
HTC 簡訊 64
Sony 會話 65
傳送簡訊 66
LGE 電子郵件 67
折線圖 68
Viber 69
Kik 70
Skype 71
黑莓傳訊器 72
WeChat 73
KAKAO 的案例 74
Dropbox 75
Telegram 76
Facebook 專頁 77
GroupMe 78
Android 電子郵件 79
Motorola 訊息 80
鄰近分享 81
Naver 82
iOS 系統活動對話方塊 83
Google 收件匣 84
Android Messenger 85
YouTube Music 86
YouTube Gaming 87
YouTube Kids 88
YouTube TV
詳情請參閱說明文件。
備註
- annotation_type
- 這個維度會指出註解在影片播放期間的顯示方式。下表列出可能的維度值:
值 0
不明 1
注意事項 3
焦點 4
標題 8
對話圖示 9
唱片公司 10
品牌浮水印 11
精選影片 12
精選播放清單 30
行動號召 - annotation_id
- YouTube 用來識別註解的 ID。
資訊卡
- card_type
- 這項維度識別向使用者顯示的資訊卡類型。下表列出可能的維度值:
值 0
不明 60
連結 61
募款活動 62
影片 63
播放清單 65
粉絲贊助 66
一般商品 68
關聯網站 69
管道 - card_id
- YouTube 用來識別卡片的 ID。
結束畫面
- end_screen_element_type
- 這個維度會指出向使用者顯示的片尾元素類型。下表列出片尾元素類型和值:
值 501
影片 - 此元素可宣傳其他 YouTube 影片。 502
Playlist - 此元素可用來宣傳 YouTube 播放清單。 503
網站 - 元素會連結至關聯網站。 504
頻道 - 元素會連結至其他頻道。 505
訂閱 - 這個元素可鼓勵觀眾訂閱您的頻道。 506
相關聯 507
群眾募資 - 該元素會連結至核准的群眾募資網站。 508
商品:元素連結至核准的商品網站。 509
最近上傳的影片 - 該元素會連結至頻道最新上傳的影片。 510
最符合觀眾喜好 - end_screen_element_id
- YouTube 用來識別片尾元素的 ID。
字幕
- subtitle_language
- 這個維度會指出使用者在觀看期間最長的隱藏式輔助字幕語言。如果大多數觀眾關閉了隱藏式輔助字幕,系統不會計入該影片的觀看次數。如要進一步瞭解含有這個維度的報表,請參閱頻道報表或內容擁有者報表的說明文件。
- subtitle_language_autotranslated
- 這個維度會指出使用者觀看影片期間最長的自動翻譯字幕語言。如果大多數觀眾關閉了隱藏式輔助字幕,系統不會計入該影片的觀看次數。如要進一步瞭解含有這個維度的報表,請參閱頻道報表或內容擁有者報表的說明文件。
廣告成效
- ad_type
- 廣告成效報表會使用「
ad_type
」維度,根據影片播放期間放送的廣告類型匯總要求的指標。 下表列出可能的維度值。如要進一步瞭解 YouTube 廣告格式,請參閱 YouTube 說明中心。
值 說明 查詢報表中的值 1
可略過的影片廣告 (競價) auctionTrueviewInstream
2
多媒體廣告 (競價) auctionDisplay
3
不可略過的影片廣告 (競價) auctionInstream
5
多媒體廣告 (預訂) reservedDisplay
6
不可略過的影片廣告 (預訂) reservedInstream
13
不明 unknown
15
可略過的影片廣告 (預訂) reservedInstreamSelect
19
串場廣告 (競價) auctionBumperInstream
20
串場廣告 (預訂) reservedBumperInstream
注意:先前在 YouTube 上使用的其他廣告類型,查詢報表可能會傳回這些類型。
內容擁有者維度
下列維度僅適用於內容擁有者報表。
- Claim_status (僅適用於內容擁有者報表)
- 這個維度代表的資料列只包含已聲明版權內容的指標。這個維度的唯一有效值是
claimed
。透過「uploader_type
」維度定義中的表格,進一步瞭解這個維度的使用方式。
- 上傳者類型 (核心維度) (僅適用於內容擁有者報表)
- 這個維度代表資料列是否含有特定內容擁有者所上傳內容和/或第三方上傳內容 (例如使用者上傳的影片) 的指標。有效值為
self
和thirdParty
。這是核心維度,必須遵守《廢止政策》。
下表列出claimed_status
和uploader_type
支援的維度組合:
claimed_status
值uploader_type
值說明 [未設定] 自己 這個資料列會針對內容擁有者上傳且未聲明版權的內容,顯示相關的 YouTube 數據分析資料。 已聲明著作權 自己 這個資料列含有內容擁有者已上傳的已聲明版權內容資料。 已聲明著作權 thirdParty 內含第三方上傳內容的已聲明版權內容資料。