本頁面由 Cloud Translation API 翻譯而成。

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 用戶端相關政策。

API 用戶端身分和憑證

使用 YouTube 嵌入式播放器 (包括 YouTube IFrame Player API) 的 API 用戶端，必須透過 HTTP Referer 要求標頭提供識別資訊。在某些環境中，瀏覽器會自動設定 HTTP Referer，API 用戶端只需要確保不會以抑制 Referer 值的方式設定 Referrer-Policy 即可。YouTube 建議使用 strict-origin-when-cross-origin Referrer-Policy，許多瀏覽器已預設採用這項政策。

同樣地，如果要在使用 JavaScript window.open 建立的視窗中整合 YouTube 嵌入式播放器，API 用戶端就不得使用 noreferrer 功能，因為這項功能會抑制 Referer 值。

設定 Referer

在 HTTP Referer 預設為空白且瀏覽器不會自動設定的環境中，API 用戶端必須採取行動，透過其他方式提供身分。在行動應用程式或電腦應用程式等 WebView 整合中，HTTP Referer 預設為空白，Referer 通常會使用下列其中一種技術設定：

行動應用程式，播放器位於本機 HTML 檔案中

在這個設定中，播放器會載入與應用程式一併封裝的 HTML 檔案。載入這個 HTML 檔案時，設定 baseUrl 參數會設定 Referer。
- Android 裝置 loadDataWithBaseURL
- iOS loadHTMLString:baseURL:

沒有本機 HTML 檔案的行動應用程式

在此設定中，播放器會直接從 https://www.youtube.com/embed/VIDEO_ID 載入，不含任何封閉的 HTML 檔案。您可將 Referer 新增為 HTTP 標頭，藉此設定該標記：

Android loadUrl，且 Referer HTTP 標頭已新增至 additionalHttpHeaders 參數

iOS loadRequest:，要求中已新增 Referer HTTP 標頭。例如：

NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
NSString *referrer = [[NSString stringWithFormat:@"https://%@", bundleId] lowercaseString];
NSURL *referrerUrl = [NSURL URLWithString:referrer];

NSString *destination = @"https://www.youtube.com/embed/VIDEO_ID";
NSURL *destinationUrl = [NSURL URLWithString:destination];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:destinationUrl];
[request addValue:referrerUrl forHTTPHeaderField:@"Referer"];

// Create an instance of WKWebView (omitted for simplicity), then load the NSMutableURLRequest.
[webView loadRequest:request];

行動應用程式，播放器位於原生瀏覽器分頁中
- Android CustomTabs
  
  使用 �Intent.EXTRA_REFERRER 設定參照網址。建立 Uri 時，請務必使用 android-app:// 配置，而非 https://。例如：
```
String destinationUrl = "https://www.youtube.com/embed/VIDEO_ID";
CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build()
customTabsIntent.intent.putExtra(Intent.EXTRA_REFERRER, Uri.parse("android-app://" + context.getPackageName()));
customTabsIntent.launchUrl(this, Uri.parse(destinationUrl));
```
- iOS SFSafariViewController
  
  SFSafariViewController 不支援設定 Referer。在此情況下，請改為設定 origin 播放器參數。
電腦版應用程式

在這項設定中，請將 Referer 新增為 HTTP 標頭：
- Microsoft .NET - 使用 HttpRequestHeaders.Referrer 或 CoreWebView2HttpRequestHeaders.SetHeader
- macOS - 按照上述 iOS 行動應用程式的操作說明進行

如果其他平台預設為空白，請設定 Referer 值，方法是在載入播放器的 WebView 中進行設定。HTTP Referer確切技術可能因平台而異。

如果您是程式庫、架構、外掛程式、服務或包裝函式的擁有者，開發人員會使用這些項目整合 YouTube 嵌入式播放器，您必須從環境中擷取應用程式 ID (視平台而定，這可能無法達成)，或允許開發人員傳遞應用程式 ID，以便如上所述設定 Referer (以及 widget_referrer 播放器參數，視情況而定)。

參照網址格式

如果您透過設定 WebView 參數或新增 HTTP 標頭明確提供 Referer，格式通常是完整網址。將通訊協定指定為 HTTPS。網址中的網域名稱必須是您向商店註冊的應用程式 ID，該商店會將應用程式發布給使用者。如果應用程式是透過其他發行管道提供給使用者，請使用應用程式安裝期間向作業系統註冊的應用程式 ID。在多數情況下，應用程式 ID 會是反向網域名稱 (也稱為「反向 DNS 格式」)，例如 com.google.android.youtube。代表性示例：

ChromeOS 上的 Android 作業系統和 Android 應用程式：應用程式 ID
Apple 平台，包括 iOS、iPadOS、macOS：軟體包 ID
Samsung Tizen：應用程式 ID
Linux 發行版本：
- Fedora：應用程式 ID
- Gnome：應用程式 ID
- Ubuntu：應用程式 ID

在某些平台上，應用程式 ID 並非反向網域名稱。在這些情況下，請使用發布應用程式的商店指派的專屬應用程式 ID。如果商店應用程式 ID 是產生的英數字元字串 (由商店或開發工具指派，而非由應用程式開發人員選擇)，請同時加入應用程式顯示名稱 (以半形連字號取代空格) 和商店應用程式 ID，並以半形句號分隔。例如：<my-app-name>.<AppID>。這個值在應用程式版本變更時應保持不變。如果應用程式並非託管於商店，請使用應用程式安裝期間向作業系統註冊的應用程式 ID，這通常是應用程式資訊清單中的專屬 ID。請勿提供應用程式版本和支援架構的詳細資料。代表性示例：

Chrome 線上應用程式商店：商店代管

商店應用程式 ID 通常是應用程式網址 https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID> 路徑的最後一部分。使用連字號分隔的應用程式名稱和商店應用程式 ID，建構上述 <my-app-name>.<AppID> 字串。
Windows：商店代管

商店應用程式 ID 通常是應用程式網址 https://apps.microsoft.com/detail/<AppID> 路徑的最後一部分。使用商店應用程式 ID 建構上述 <my-app-name>.<AppID> 字串。也必須包含連字號分隔的應用程式名稱。
Windows：非市集發布

Windows 應用程式在應用程式資訊清單中包含套件身分：Name_Version_Architecture_ResourceID_PublisherID。只使用 Name 屬性。
Xbox：商店代管

商店應用程式 ID 通常是應用程式網址 https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID> 路徑的最後一部分。使用連字號分隔的應用程式名稱和商店應用程式 ID，建構上述 <my-app-name>.<AppID> 字串。

如果 API 用戶端對 YouTube 的要求數量較多 (請參閱「用量和配額」)，可能需要額外憑證才能存取 YouTube 嵌入式播放器。

否則 YouTube 嵌入式播放器的功能可能會減少。

WebView 類型

在 WebView 中整合 YouTube 嵌入式播放器時，請盡可能使用作業系統提供的 WebView 類型。例如：

Android 作業系統：WebView 或 CustomTabs
Apple 平台，包括 iOS、iPadOS、macOS：WKWebView 或 SFSafariViewController

嵌入式 YouTube 播放器大小

內嵌播放器的可視區域必須至少為 200 像素 x 200 像素。如果播放器顯示控制項，必須夠大，才能完整顯示控制項，且不會將檢視區塊縮小至低於最小尺寸。建議 16:9 播放器的寬度至少為 480 像素，高度至少為 270 像素。

自動播放和指令碼播放

本節將說明自動播放功能。這項政策適用於使用 autoplay 播放器參數，或透過 YouTube IFrame Player API 服務或其他 YouTube API 服務，以程式輔助方式啟動自動播放功能的 YouTube 嵌入式播放器。

自動播放影片的內嵌播放器應在網頁載入時或內嵌播放器完全顯示時，立即開始播放影片。不過，API 用戶端必須等到播放器顯示在網頁或畫面上，且超過一半的播放器在可視區域中，才能啟動自動播放功能。
一個網頁或畫面不得有多個 YouTube 播放器同時自動播放內容。
任何會啟動播放的 YouTube 縮圖，寬度至少要有 120 像素，高度至少要有 70 像素。

YouTube 播放器屬性

YouTube 播放器的屬性和參數 (包括播放器中 YouTube 品牌宣傳的顯示方式) 均在 YouTube API 文件和規格 (https://developers.google.com/youtube) 中指定。您不得對 YouTube 播放器進行 API 說明文件未明確說明的變更。

疊加層和影格

不得在 YouTube 嵌入式播放器的任何部分 (包括播放器控制項) 前方顯示疊加層、框架或其他視覺元素。同樣地，您不得使用疊加層、框架或其他視覺元素，遮蓋內嵌播放器的任何部分，包括播放器控制項。

滑鼠指向次數

您不得在 YouTube 播放器上使用滑鼠懸停或觸控事件，代表使用者發起任何動作，例如開啟視窗或訂閱頻道。

上傳影片

如果 API 用戶端允許使用者將內容上傳至多個平台，使用者應可選取及取消選取要上傳影片的平台。

資料條件

API 用戶端必須允許使用者設定下列清單中的值，才能上傳影片至 YouTube。未列出的屬性皆為選填。

	名稱	說明
資源屬性
	`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) 截斷文字，並提供方法讓觀眾從截斷版本輕鬆存取全文。這項規定適用於所有留言和留言回覆，無論留言與哪種資源 (影片、頻道等) 相關聯。請注意，`commentThread` 資源的 `snippet.topLevelComment` 屬性值是 `comment` 資源，而 `replies.comments[]` 屬性是 `comment` 資源的清單。因此，這項規定也適用於 `snippet.topLevelComment.snippet.textDisplay` 和 `replies.comments[].snippet.textDisplay` 屬性。
	`snippet.title` (`channel`)	必要 (建議)。頻道的標題。如果留言與頻道有關，API 用戶端必須顯示頻道名稱。如果留言與影片相關，API 用戶端必須顯示上傳影片的頻道名稱。
	`snippet.title` (`video`)	有條件限制的必要項目 (建議)。影片的標題。如果留言與影片相關，則必須顯示這個值。
	`snippet.moderationStatus`	必要 (有條件)。如果 API 要求中的 `moderationStatus` 參數值為 `heldForReview` 或 `likelySpam`，顯示畫面必須使用屬性值、類似的用語 (例如「這則留言正在接受審查」)、標題 (例如「待審查」) 或其他明確的用語，清楚指出該狀態。`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 使用者帳戶。

YouTube API 服務 - 基本必要功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。