YouTube API 服務 - 基本功能需求

注意事項:新版《遵守 YouTube 開發人員政策》指南提供了相關指南和範例,可協助您確保 API 用戶端符合 YouTube API 服務條款政策 (API 服務條款) 的特定部分。本指南提供深入說明 YouTube 如何落實 API 服務條款的特定部分,但不會取代任何現有的文件。

本文件定義 API 用戶端的基本功能要求 (實作或提供 YouTube API 服務的特定功能,以下簡稱「API 用戶端」)。

這些規定和規範旨在確保 API 用戶端提供一致的使用者體驗,以保護 YouTube 使用者、內容擁有者和廣告客戶。這些規則是《YouTube API 服務條款》的重要一環,在開發和實作任何 API 用戶端時都必須遵守。

這份文件中的相關規定應會有所變動,以確保現有的 YouTube 功能能帶給使用者更好的體驗。也會因應新的和更新版 YouTube 功能而改變。有時您可能必須更新 API 用戶端,以符合新的需求。《服務條款修訂記錄》會記錄所有變更,因此請經常查看或訂閱 RSS 資訊提供,確保您能快速瞭解可能會影響您 API 用戶端的變更。

除了本文件所述規定之外,我們極力建議您遵循《YouTube API 服務政策》所述的最佳做法,並在 YouTube API 服務說明文件的其他地方討論相關事項。即使非嚴格要求,這些做法也能協助 API 用戶端在發生錯誤時更快地恢復錯誤,並且針對使用配額的 YouTube API 服務將配額用量最佳化。同時,這些做法有助於確保 YouTube 生態系統的健全,最重要的是為 API 用戶端和 YouTube 應用程式的使用者提供最佳體驗。

YouTube 內嵌播放器和影片播放

本節規定僅適用於內嵌 YouTube 播放器。另外《YouTube API 服務政策》中也制定了多項政策,用於規範播放 YouTube 影音內容的 API 用戶端。

內嵌 YouTube 播放器大小

內嵌播放器的可視區域必須至少為 200 x 200 像素。如果播放器顯示控制項,其大小必須足以完整顯示控制項,且不會縮小到最小尺寸以下的畫面。我們建議 16:9 播放器的寬度至少 480 像素,高度至少 270 像素。

自動播放與事先擬好腳本的播放

這個部分會說明自動播放。適用於 autoplay 播放器參數的 YouTube 內嵌播放器,或利用 YouTube IFrame Player API 服務、YouTube Android Player API 服務或其他 YouTube API 服務,以程式輔助方式自動播放。

  • 嵌入式播放器會在網頁載入時,或在使用者完全顯示內嵌播放器時,立即開始播放。然而,API 用戶端不得在自動播放時顯示播放器,且在播放器或畫面中顯示一半以上的播放器。

  • 一個網頁或畫面不得有多個 YouTube 播放器同時自動播放內容。

  • 任何 YouTube 縮圖如果開始播放,都必須為寬度至少 120 像素、高度至少 70 像素。

YouTube 播放器屬性

您可以在 YouTube API 說明文件和規格 (https://developers.google.com/youtube) 中指定 YouTube 播放器的屬性和參數,例如播放器中的 YouTube 品牌外觀。不得變更「API」文件未明確描述的 YouTube 播放器。

疊加層與畫格

您不得在 YouTube 內嵌播放器的任何部分 (包括播放器控制項) 顯示重疊元素、頁框或其他視覺元素。同樣地,您不得使用重疊元素、頁框或其他視覺元素來遮蓋內嵌播放器的任何部分,包括播放器控制項。

滑鼠指向次數

不得使用 YouTube 播放器的滑鼠遊標懸停事件或觸控事件來代表使用者執行任何動作,例如開啟視窗或訂閱頻道。

上傳影片

如果 API 用戶端允許使用者將內容上傳到多個平台,則使用者應該能夠選取並取消選取要上傳影片的平台。

資料條件

允許使用者將影片上傳至 YouTube 的 API 用戶端,必須讓 users 能設定下列清單的值。任何未列出的屬性均為選填。

  名稱 說明
資源屬性
snippet.title 必備。影片的標題。如果值超過 100 個字元,YouTube 就會傳回錯誤。YouTube 支援所有有效的 UTF-8 字元 (<> 除外)。

snippet.description 必備。影片的說明。如果值超過 5000 位元組,YouTube 就會傳回錯誤。YouTube 支援所有有效的 UTF-8 字元 (<> 除外)。
status.privacyStatus 必備。影片的隱私設定。使用者必須能選擇上傳影片、公開、私人或不公開。
要求參數
onBehalfOfContentOwnerChannel 必要 (有條件)。如果請求的授權憑證可識別內容擁有者,並且設定了 onBehalfOfContentOwner 參數,API 使用者還需要能夠指定要上傳影片的 YouTube 頻道。

顯示註解

  名稱 說明
資源屬性
snippet.textDisplay 必備。留言文字。API 用戶端必須 (a) 顯示註解或評論回覆的全文,或 (b) 截斷文字,並允許檢視者輕鬆從截斷版本中存取完整文字。

這項規定適用於所有留言和留言回覆,無論留言類型的資源類型為何 (影片、頻道等)。comment因此,這項規定也適用於 snippet.topLevelComment.snippet.textDisplayreplies.comments[].snippet.textDisplay 屬性。
snippet.title
(channel)
必填 (建議)頻道的標題。
  • 如果留言與頻道相關,API 用戶端必須顯示該頻道的名稱。
  • 如果留言與影片相關,API 用戶端必須顯示上傳影片的頻道名稱。
snippet.title
(video)
必要 (有條件)影片的標題。如果留言與影片相關,則必須顯示這個值。
snippet.moderationStatus 必要 (有條件)。如果 API 要求中的 moderationStatus 參數值為 heldForReviewlikelySpam,顯示內容就必須使用屬性值、類似的語言 (例如「將留言留待審核」) 或標題 (例如「留待審核」等) 或其他清楚易懂的用語。commentThreads.list 方法可支援根據其管理狀態擷取留言的功能。

新增註解

  名稱 說明
資源屬性
snippet.title
(channel)
必備。頻道的標題。
  • 當使用者要添加關於某個頻道的評論時,API 用戶端必須顯示該頻道的名稱。
  • 如果使用者要對影片發表留言,API 用戶端必須顯示上傳影片的頻道名稱。
snippet.title
(video)
必備。如果使用者要對影片發表留言,API 用戶端必須顯示影片的標題。
其他規定
Comment author's channel name 必備。API 用戶端必須清楚指明留言所屬的 YouTube 使用者帳戶。如果要求的授權憑證能識別內容擁有者,並且設定了 onBehalfOfContentOwner 參數,API 使用者還需要能夠指定要將留言歸入哪個 YouTube 頻道。

新增註解回覆

  名稱 說明
資源屬性
snippet.textDisplay 必備。留言文字。API 用戶端必須依照本文件「顯示註解」一節中定義的規則,顯示使用者回覆的留言文字。
snippet.title
(channel)
必備。頻道的標題。
  • 如果使用者回覆了有關頻道的評論,API 用戶端必須顯示該頻道的名稱。
  • 使用者在回覆影片的留言時,API 用戶端必須顯示上傳影片的頻道名稱。
snippet.title
(video)
必備。使用者在回覆影片評論時,API 用戶端必須顯示影片標題。
其他規定
Comment author's channel name 必備。API 用戶端必須清楚標示留言回覆所屬的 YouTube 使用者帳戶。如果要求的授權憑證可識別內容擁有者,並且設定了 onBehalfOfContentOwner 參數,API 使用者還需要能夠指定留言留言的 YouTube 頻道來源。

編輯或刪除留言回覆

  名稱 說明
資源屬性
snippet.textDisplay 必備。留言文字。API 用戶端必須依照本文件「顯示註解」一節中定義的規則,顯示使用者正在編輯或刪除的註解文字。
snippet.title
(channel)
必備。頻道的標題。
  • 如果使用者編輯或刪除管道留言,API 用戶端必須顯示該頻道的名稱。
  • 如果使用者編輯或刪除影片留言,API 用戶端必須顯示上傳影片的頻道名稱。
snippet.title
(video)
必備。如果使用者編輯或刪除影片留言,API 用戶端必須顯示影片的標題。
其他規定
Comment author's channel name 必備。API 用戶端必須清楚標示留言的來源 YouTube 使用者帳戶。

在聊天室中將使用者停權 (或移除停權)

  名稱 說明
資源屬性
snippet.title
(channel)
必備。遭停權或解除停權的 YouTube 頻道名稱。此外,該名稱必須連結至頻道,否則也必須顯示頻道網址。
其他規定
評論作者的頻道名稱 必備。API 用戶端必須清楚指明用於新增或移除停權的 YouTube 使用者帳戶。