Trang này được dịch bởi Cloud Translation API.

Dịch vụ API YouTube – Chức năng tối thiểu bắt buộc

Lưu ý: Việc tuân thủ Chính sách dành cho nhà phát triển của YouTube cung cấp hướng dẫn và ví dụ để giúp bạn đảm bảo rằng các ứng dụng API của bạn tuân thủ một số phần cụ thể trong Điều khoản và Chính sách (API TOS) của Dịch vụ API YouTube. Hướng dẫn này cung cấp thông tin chi tiết về cách YouTube thực thi một số khía cạnh nhất định của Điều khoản dịch vụ API, nhưng không thay thế bất kỳ tài liệu hiện có nào.

Tài liệu này xác định các yêu cầu tối thiểu về chức năng đối với những ứng dụng API triển khai hoặc cung cấp quyền truy cập vào các tính năng cụ thể của dịch vụ API YouTube ("Ứng dụng API").

Các yêu cầu và nguyên tắc này đảm bảo rằng các ứng dụng API mang đến trải nghiệm nhất quán cho người dùng, đồng thời bảo vệ lợi ích của người dùng YouTube, chủ sở hữu nội dung và nhà quảng cáo. Các quy tắc này là một phần không thể thiếu trong Điều khoản dịch vụ của API YouTube và bạn phải tuân thủ khi phát triển cũng như triển khai mọi Ứng dụng API.

Bạn nên lưu ý rằng các yêu cầu trong tài liệu này có thể thay đổi để chúng tôi có thể đảm bảo trải nghiệm tốt hơn cho người dùng với các tính năng hiện có của YouTube. Các nguyên tắc này cũng sẽ thay đổi khi YouTube ra mắt các tính năng mới hoặc cập nhật các tính năng hiện có. Đôi khi, những thay đổi như vậy có thể yêu cầu bạn cập nhật API Client để đáp ứng các yêu cầu mới. Nhật ký sửa đổi Điều khoản dịch vụ sẽ ghi lại mọi thay đổi. Vì vậy, vui lòng thường xuyên kiểm tra tài liệu đó hoặc đăng ký RSS feed của tài liệu để đảm bảo bạn có thể nhanh chóng tìm hiểu về những thay đổi có thể ảnh hưởng đến API Client của bạn.

Ngoài các yêu cầu trong tài liệu này, bạn nên làm theo các phương pháp hay nhất được mô tả trong Chính sách của Dịch vụ API YouTube và được thảo luận ở những nơi khác trong tài liệu về dịch vụ API YouTube. Ngay cả khi không bắt buộc, những phương pháp này vẫn giúp Ứng dụng API của bạn khắc phục lỗi nhanh hơn và tối ưu hoá việc sử dụng hạn mức nếu ứng dụng đó sử dụng các dịch vụ API YouTube có phân bổ hạn mức. Đồng thời, những phương pháp này giúp đảm bảo sự lành mạnh của hệ sinh thái YouTube và trên hết là mang đến trải nghiệm tốt nhất có thể cho người dùng API Client và Ứng dụng YouTube của bạn.

Trình phát nhúng của YouTube và chế độ phát video

Các yêu cầu trong phần này liên quan cụ thể đến trình phát YouTube được nhúng. Chính sách của Dịch vụ API YouTube cũng bao gồm một số chính sách liên quan đến Ứng dụng API phát nội dung nghe nhìn trên YouTube.

Thông tin nhận dạng và thông tin đăng nhập của ứng dụng API

Ứng dụng API sử dụng trình phát được nhúng của YouTube (bao gồm cả YouTube IFrame Player API) phải cung cấp thông tin nhận dạng thông qua tiêu đề yêu cầu HTTP Referer. Trong một số môi trường, trình duyệt sẽ tự động đặt HTTP Referer và API Client chỉ cần đảm bảo rằng chúng không đặt Referrer-Policy theo cách ngăn chặn giá trị Referer. YouTube khuyến khích bạn sử dụng strict-origin-when-cross-origin Referrer-Policy (Chính sách về thông tin giới thiệu). Đây vốn là chế độ mặc định trong nhiều trình duyệt.

Tương tự, nếu tích hợp trình phát YouTube được nhúng trong một cửa sổ được tạo bằng JavaScript window.open, thì các API Client không được sử dụng tính năng noreferrer. Tính năng này sẽ chặn giá trị Referer.

Đặt tiêu đề Referer

Trong những môi trường mà HTTP Referer trống theo mặc định và không được trình duyệt tự động đặt, Ứng dụng khách API phải thực hiện hành động để cung cấp danh tính của mình thông qua các phương tiện thay thế. Trong các hoạt động tích hợp WebView (chẳng hạn như ứng dụng di động hoặc ứng dụng dành cho máy tính), HTTP Referer sẽ trống theo mặc định và Referer thường được thiết lập bằng một trong những kỹ thuật sau:

Ứng dụng di động có trình phát bên trong tệp HTML cục bộ

Trong cấu hình này, trình phát được tải trong một tệp HTML đi kèm với ứng dụng. Khi tải tệp HTML này, việc đặt tham số baseUrl sẽ đặt Referer.
- Android loadDataWithBaseURL
- iOS loadHTMLString:baseURL:

Ứng dụng di động không có tệp HTML cục bộ

Trong cấu hình này, trình phát được tải trực tiếp từ https://www.youtube.com/embed/VIDEO_ID mà không có tệp HTML nào đi kèm. Bạn thiết lập Referer bằng cách thêm thẻ này làm Tiêu đề HTTP:

Android loadUrl có Tiêu đề HTTP Referer được thêm vào tham số additionalHttpHeaders

iOS loadRequest: có Tiêu đề HTTP Referer được thêm vào yêu cầu. Ví dụ:

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];

Ứng dụng di động có trình phát bên trong thẻ trình duyệt gốc
- Android CustomTabs
  
  Sử dụng Intent.EXTRA_REFERRER để đặt giá trị liên kết giới thiệu. Hãy nhớ sử dụng lược đồ android-app:// thay vì https:// khi tạo Uri. Ví dụ:
```
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 không hỗ trợ việc đặt Referer. Trong trường hợp này, hãy đặt tham số trình phát origin.
Ứng dụng dành cho máy tính

Trong cấu hình này, hãy đặt Referer bằng cách thêm Referer làm Tiêu đề HTTP:
- Microsoft .NET – sử dụng HttpRequestHeaders.Referrer hoặc CoreWebView2HttpRequestHeaders.SetHeader
- macOS – làm theo hướng dẫn tương tự như hướng dẫn ở trên dành cho ứng dụng di động iOS

Đối với các nền tảng khác mà HTTP Referer trống theo mặc định, hãy đặt giá trị Referer bằng cách định cấu hình WebView mà trình phát được tải. Kỹ thuật chính xác có thể khác nhau tuỳ theo nền tảng.

Nếu là chủ sở hữu của một thư viện, khung, trình bổ trợ, dịch vụ hoặc trình bao bọc mà nhà phát triển sử dụng để tích hợp trình phát được nhúng của YouTube, bạn phải truy xuất mã nhận dạng ứng dụng từ môi trường (điều này có thể không thực hiện được, tuỳ thuộc vào nền tảng) hoặc cho phép nhà phát triển truyền mã nhận dạng ứng dụng của họ để có thể đặt Referer (và tham số trình phát widget_referrer, nếu thích hợp) như mô tả ở trên.

Định dạng giá trị giới thiệu

Khi bạn cung cấp Referer một cách rõ ràng bằng cách đặt một tham số WebView hoặc thêm một Tiêu đề HTTP, định dạng thường là một URL đủ điều kiện. Chỉ định HTTPS làm giao thức. Trong URL, tên miền phải là mã nhận dạng ứng dụng ("mã ứng dụng") mà bạn đã đăng ký với cửa hàng phân phối ứng dụng cho người dùng cuối. Nếu bạn cung cấp ứng dụng cho người dùng thông qua một kênh phân phối thay thế, hãy sử dụng mã ứng dụng đã đăng ký với hệ điều hành trong quá trình cài đặt ứng dụng. Trong hầu hết các trường hợp, mã ứng dụng của bạn sẽ là tên miền đảo ngược (còn gọi là "định dạng DNS đảo ngược"), chẳng hạn như com.google.android.youtube. Ví dụ minh hoạ:

Hệ điều hành Android và ứng dụng Android trên ChromeOS: Mã ứng dụng
Các nền tảng của Apple, bao gồm iOS, iPadOS, macOS: Mã nhận dạng gói
Samsung Tizen: Mã ứng dụng
Các bản phân phối Linux:
- Fedora: Mã ứng dụng
- GNOME: Mã ứng dụng
- Ubuntu: Mã ứng dụng

Trên một số nền tảng, mã ứng dụng không phải là tên miền đảo ngược. Trong những trường hợp này, hãy sử dụng mã nhận dạng ứng dụng duy nhất do cửa hàng phân phối ứng dụng chỉ định. Khi mã nhận dạng ứng dụng trên cửa hàng là một chuỗi chữ và số được tạo (do cửa hàng hoặc công cụ phát triển chỉ định, chứ không phải do nhà phát triển ứng dụng chọn), hãy thêm cả tên hiển thị của ứng dụng (thay thế dấu cách bằng dấu gạch ngang) và mã nhận dạng ứng dụng trên cửa hàng, phân tách bằng dấu chấm. Ví dụ: <my-app-name>.<AppID>. Giá trị này phải ổn định khi có thay đổi về phiên bản ứng dụng. Nếu ứng dụng không được lưu trữ trên một cửa hàng, hãy sử dụng mã nhận dạng ứng dụng đã đăng ký với hệ điều hành trong quá trình cài đặt ứng dụng; đây thường là một giá trị nhận dạng riêng biệt trong tệp kê khai ứng dụng. Loại trừ mọi thông tin chi tiết về phiên bản ứng dụng và cấu trúc được hỗ trợ. Ví dụ minh hoạ:

Cửa hàng Chrome trực tuyến: được lưu trữ trên cửa hàng

Mã nhận dạng ứng dụng cửa hàng thường là phần cuối cùng của đường dẫn trong URL ứng dụng https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Sử dụng tên ứng dụng có dấu gạch ngang và mã ứng dụng trên cửa hàng để tạo chuỗi <my-app-name>.<AppID> như mô tả ở trên.
Windows: store-hosted

Mã nhận dạng ứng dụng cửa hàng thường là phần cuối cùng của đường dẫn trong URL ứng dụng https://apps.microsoft.com/detail/<AppID>. Sử dụng mã nhận dạng ứng dụng trên cửa hàng để tạo chuỗi <my-app-name>.<AppID> như mô tả ở trên. Bạn cũng phải thêm tên ứng dụng có dấu gạch ngang.
Windows: phân phối bên ngoài cửa hàng

Các ứng dụng Windows chứa một package identity (danh tính gói) trong tệp kê khai ứng dụng: Name_Version_Architecture_ResourceID_PublisherID. Chỉ sử dụng thuộc tính Name.
Xbox: do cửa hàng lưu trữ

Mã nhận dạng ứng dụng cửa hàng thường là phần cuối cùng của đường dẫn trong URL ứng dụng https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Sử dụng tên ứng dụng có dấu gạch ngang và mã ứng dụng trên cửa hàng để tạo chuỗi <my-app-name>.<AppID> như mô tả ở trên.

Đối với những Ứng dụng API có số lượng yêu cầu lớn gửi đến YouTube (xem phần Mức sử dụng và hạn mức), bạn có thể phải cung cấp thêm thông tin xác thực để truy cập vào trình phát được nhúng của YouTube.

Nếu không tuân thủ các yêu cầu này, trình phát được nhúng của YouTube có thể bị giảm chức năng.

Loại WebView

Khi tích hợp trình phát được nhúng của YouTube vào WebView, hãy sử dụng một trong các loại WebView do hệ điều hành cung cấp (nếu có). Ví dụ:

Hệ điều hành Android: WebView hoặc CustomTabs
Các nền tảng của Apple, bao gồm iOS, iPadOS, macOS: WKWebView hoặc SFSafariViewController

Kích thước của trình phát YouTube được nhúng

Trình phát được nhúng phải có khung hiển thị tối thiểu là 200 x 200 pixel. Nếu trình phát hiển thị các nút điều khiển, thì trình phát đó phải đủ lớn để hiển thị đầy đủ các nút điều khiển mà không làm giảm kích thước khung hiển thị xuống dưới kích thước tối thiểu. Bạn nên sử dụng trình phát có tỷ lệ khung hình 16:9 với chiều rộng tối thiểu là 480 pixel và chiều cao tối thiểu là 270 pixel.

Tự động phát và phát theo kịch bản

Phần này đề cập đến tính năng phát tự động. Chính sách này áp dụng cho trình phát được nhúng của YouTube sử dụng tham số trình phát autoplay hoặc khởi chạy chế độ phát tự động theo cách có lập trình bằng dịch vụ YouTube IFrame Player API hoặc một dịch vụ API khác của YouTube.

Trình phát được nhúng tự động phát video phải bắt đầu phát ngay khi trang tải hoặc ngay khi trình phát được nhúng hiển thị đầy đủ. Tuy nhiên, Ứng dụng API không được bắt đầu phát tự động cho đến khi trình phát xuất hiện và hơn một nửa trình phát xuất hiện trên trang hoặc màn hình.
Một trang hoặc màn hình không được có nhiều trình phát YouTube tự động phát nội dung cùng lúc.
Mọi hình thu nhỏ trên YouTube bắt đầu quá trình phát đều phải có chiều rộng tối thiểu là 120 pixel và chiều cao tối thiểu là 70 pixel.

Thuộc tính của Trình phát YouTube

Các thuộc tính và thông số của trình phát YouTube (ví dụ: giao diện của thương hiệu YouTube trong trình phát) được chỉ định trong tài liệu và quy cách của API YouTube (https://developers.google.com/youtube). Bạn không được phép thay đổi trình phát YouTube theo cách không được mô tả rõ ràng trong tài liệu API.

Lớp phủ và khung hình

Bạn không được hiển thị lớp phủ, khung hoặc các phần tử trực quan khác ở phía trước bất kỳ phần nào của trình phát được nhúng của YouTube, kể cả các nút điều khiển trình phát. Tương tự, bạn không được sử dụng lớp phủ, khung hình hoặc các phần tử trực quan khác để che khuất bất kỳ phần nào của trình phát được nhúng, kể cả các nút điều khiển trình phát.

Số lần di chuột qua

Bạn không được sử dụng sự kiện di chuột hoặc sự kiện chạm trên trình phát YouTube để thay mặt người dùng thực hiện bất kỳ hành động nào, chẳng hạn như mở cửa sổ hoặc đăng ký kênh.

Tải video lên

Nếu Ứng dụng API cho phép người dùng tải nội dung lên nhiều nền tảng, thì người dùng phải có thể chọn và bỏ chọn những nền tảng mà họ muốn tải video lên.

Yêu cầu dữ liệu

Các ứng dụng API cho phép người dùng tải video lên YouTube phải cho phép người dùng đặt các giá trị trong danh sách sau. Mọi thuộc tính không có trong danh sách đều là thuộc tính không bắt buộc.

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.title`	Bắt buộc. Tiêu đề của video. YouTube sẽ trả về lỗi nếu giá trị này vượt quá 100 ký tự. YouTube hỗ trợ tất cả ký tự UTF-8 hợp lệ, ngoại trừ `<` và `>`.
	`snippet.description`	Bắt buộc. Nội dung mô tả video. YouTube sẽ trả về lỗi nếu giá trị vượt quá 5.000 byte. YouTube hỗ trợ tất cả ký tự UTF-8 hợp lệ, ngoại trừ `<` và `>`.
	`status.privacyStatus`	Bắt buộc. Chế độ cài đặt quyền riêng tư của video. Người dùng phải có thể chọn chế độ công khai, riêng tư hoặc không công khai cho video tải lên.
Tham số yêu cầu
	`onBehalfOfContentOwnerChannel`	Bắt buộc trong một số điều kiện. Nếu thông tin uỷ quyền của yêu cầu xác định một chủ sở hữu nội dung và tham số `onBehalfOfContentOwner` được đặt, thì người dùng API cũng phải có thể chỉ định kênh YouTube mà video đang được tải lên.

Hiển thị bình luận

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.textDisplay`	Bắt buộc. Văn bản của bình luận. Ứng dụng API phải (a) hiển thị toàn bộ nội dung của một bình luận hoặc câu trả lời bình luận, hoặc (b) cắt bớt nội dung và cung cấp cho người xem cách dễ dàng truy cập vào toàn bộ nội dung từ phiên bản bị cắt bớt. Yêu cầu này áp dụng cho tất cả bình luận và câu trả lời bình luận, bất kể loại tài nguyên mà bình luận được liên kết (video, kênh, v.v.). Xin lưu ý rằng giá trị thuộc tính `snippet.topLevelComment` của tài nguyên `commentThread` là một tài nguyên `comment` và thuộc tính `replies.comments[]` là một danh sách các tài nguyên `comment`. Do đó, yêu cầu này cũng áp dụng cho các thuộc tính `snippet.topLevelComment.snippet.textDisplay` và `replies.comments[].snippet.textDisplay`.
	`snippet.title` (`channel`)	Bắt buộc (đề xuất). Tiêu đề của kênh. Nếu bình luận liên quan đến một kênh, thì ứng dụng API phải hiển thị tên của kênh đó. Nếu bình luận liên quan đến một video, thì ứng dụng API phải hiển thị tên của kênh đã tải video đó lên.
	`snippet.title` (`video`)	Bắt buộc có điều kiện (đề xuất). Tiêu đề của video. Bạn phải hiển thị giá trị này nếu bình luận liên quan đến một video.
	`snippet.moderationStatus`	Bắt buộc trong một số điều kiện. Nếu giá trị tham số `moderationStatus` trong yêu cầu API là `heldForReview` hoặc `likelySpam`, thì màn hình hiển thị phải xác định rõ trạng thái đó bằng cách sử dụng giá trị thuộc tính, ngôn ngữ tương tự (ví dụ: "Bình luận này đang được giữ lại để xem xét"), tiêu đề (ví dụ: "Giữ lại để xem xét") hoặc ngôn ngữ rõ ràng khác. Phương thức `commentThreads.list` hỗ trợ khả năng truy xuất bình luận dựa trên trạng thái kiểm duyệt của bình luận.

Thêm bình luận

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.title` (`channel`)	Bắt buộc. Tiêu đề của kênh. Nếu người dùng đang thêm bình luận về một kênh, thì ứng dụng API phải hiển thị tên của kênh đó. Nếu người dùng đang thêm bình luận về một video, thì ứng dụng API phải hiển thị tên của kênh đã tải video đó lên.
	`snippet.title` (`video`)	Bắt buộc. Nếu người dùng đang thêm bình luận về một video, thì ứng dụng API phải hiển thị tiêu đề của video đó.
Các yêu cầu khác
	`Comment author's channel name`	Bắt buộc. Ứng dụng API phải xác định rõ tài khoản người dùng YouTube mà bình luận sẽ được ghi nhận. Nếu thông tin uỷ quyền của yêu cầu xác định một chủ sở hữu nội dung và tham số `onBehalfOfContentOwner` được đặt, thì người dùng API cũng phải có thể chỉ định kênh YouTube mà bình luận sẽ được gán cho.

Thêm câu trả lời cho bình luận

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.textDisplay`	Bắt buộc. Văn bản của bình luận. Ứng dụng API phải hiển thị văn bản của bình luận mà người dùng đang trả lời theo các quy tắc được xác định trong phần Hiển thị bình luận của tài liệu này.
	`snippet.title` (`channel`)	Bắt buộc. Tiêu đề của kênh. Nếu người dùng đang trả lời một bình luận về một kênh, thì ứng dụng API phải hiển thị tên của kênh đó. Nếu người dùng đang trả lời một bình luận về video, thì ứng dụng API phải hiển thị tên của kênh đã tải video đó lên.
	`snippet.title` (`video`)	Bắt buộc. Nếu người dùng đang trả lời một bình luận về video, thì ứng dụng API phải hiển thị tiêu đề của video đó.
Các yêu cầu khác
	`Comment author's channel name`	Bắt buộc. Ứng dụng API phải xác định rõ tài khoản người dùng YouTube mà câu trả lời bình luận sẽ được ghi nhận. Nếu thông tin uỷ quyền của yêu cầu xác định một chủ sở hữu nội dung và tham số `onBehalfOfContentOwner` được đặt, thì người dùng API cũng phải có thể chỉ định kênh YouTube mà câu trả lời bình luận sẽ được gán cho.

Chỉnh sửa hoặc xoá câu trả lời cho bình luận

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.textDisplay`	Bắt buộc. Văn bản của bình luận. Ứng dụng API phải hiển thị văn bản của bình luận mà người dùng đang chỉnh sửa hoặc xoá theo các quy tắc được xác định trong phần Hiển thị bình luận của tài liệu này.
	`snippet.title` (`channel`)	Bắt buộc. Tiêu đề của kênh. Nếu người dùng đang chỉnh sửa hoặc xoá một bình luận về một kênh, thì ứng dụng API phải hiển thị tên của kênh đó. Nếu người dùng đang chỉnh sửa hoặc xoá một bình luận về video, thì ứng dụng API phải hiển thị tên của kênh đã tải video đó lên.
	`snippet.title` (`video`)	Bắt buộc. Nếu người dùng đang chỉnh sửa hoặc xoá một bình luận về video, thì ứng dụng API phải hiển thị tiêu đề của video đó.
Các yêu cầu khác
	`Comment author's channel name`	Bắt buộc. Ứng dụng API phải xác định rõ tài khoản người dùng YouTube mà bình luận được ghi nhận.

Cấm người dùng tham gia cuộc trò chuyện trực tiếp (hoặc xoá lệnh cấm)

	Tên	Mô tả
Thuộc tính tài nguyên
	`snippet.title` (`channel`)	Bắt buộc. Tên của kênh YouTube đang bị cấm hoặc được gỡ bỏ lệnh cấm. Ngoài ra, tên này phải liên kết đến kênh hoặc URL của kênh cũng phải xuất hiện.
Các yêu cầu khác
	Tên kênh của người bình luận	Bắt buộc. Ứng dụng API phải xác định rõ tài khoản người dùng YouTube đang được dùng để thêm hoặc xoá lệnh cấm.

Dịch vụ API YouTube – Chức năng tối thiểu bắt buộc Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.