Layanan YouTube API - Fungsi Minimum yang Diperlukan

Catatan: Mematuhi Kebijakan Developer YouTube memberikan panduan dan contoh untuk membantu Anda memastikan bahwa klien API Anda mematuhi bagian tertentu dari Persyaratan dan Kebijakan Layanan YouTube API (TOS API). Panduan ini memberikan insight tentang cara YouTube menerapkan aspek tertentu dari TOS API, tetapi tidak menggantikan dokumen yang ada.

Dokumen ini mendefinisikan persyaratan fungsional minimum untuk klien API yang menerapkan atau menyediakan akses ke fitur tertentu layanan YouTube API ("Klien API").

Persyaratan dan pedoman ini memastikan bahwa klien API memberikan pengalaman pengguna yang konsisten yang melindungi kepentingan pengguna, pemilik konten, dan pengiklan YouTube. Aturan ini merupakan bagian integral dari Persyaratan Layanan YouTube API dan harus dipatuhi dalam pengembangan dan penerapan Klien API apa pun.

Anda harus bersiap bahwa persyaratan dalam dokumen ini akan berubah sehingga kami dapat memastikan pengalaman pengguna yang lebih baik dengan fitur YouTube yang ada. Perubahan ini juga akan terjadi sebagai respons terhadap fitur YouTube baru dan yang diperbarui. Terkadang, perubahan tersebut mungkin mengharuskan Anda memperbarui Klien API untuk memenuhi persyaratan baru. Histori revisi Persyaratan Layanan akan mencatat setiap perubahan, jadi periksa dokumen tersebut secara berkala, atau berlangganan feed RSS-nya, untuk memastikan Anda dapat mempelajari dengan cepat perubahan yang dapat memengaruhi Klien API Anda.

Selain persyaratan dalam dokumen ini, sebaiknya Anda mengikuti praktik terbaik yang dijelaskan dalam Kebijakan Layanan API YouTube dan dibahas di tempat lain dalam dokumentasi layanan API YouTube. Meskipun tidak benar-benar diperlukan, praktik ini membantu Klien API Anda memulihkan diri dari error dengan lebih cepat dan mengoptimalkan penggunaan kuota jika mereka menggunakan layanan YouTube API yang mengalokasikan kuota. Pada saat yang sama, praktik ini membantu memastikan kesehatan ekosistem YouTube dan, yang terpenting, memberikan pengalaman terbaik kepada pengguna Klien API Anda dan Aplikasi YouTube.

Pemutar tersemat YouTube dan pemutaran video

Persyaratan di bagian ini secara khusus terkait dengan pemutar YouTube yang disematkan. Kebijakan Layanan YouTube API juga mencakup beberapa kebijakan yang relevan dengan Klien API yang memutar konten audiovisual YouTube.

Identitas dan Kredensial Klien API

Klien API yang menggunakan pemutar sematan YouTube (termasuk YouTube IFrame Player API) harus memberikan identifikasi melalui header permintaan HTTP Referer. Di beberapa lingkungan, browser akan otomatis menyetel HTTP Referer, dan Klien API hanya perlu memastikan bahwa mereka tidak menyetel Referrer-Policy dengan cara yang menekan nilai Referer. YouTube merekomendasikan penggunaan strict-origin-when-cross-origin Referrer-Policy, yang sudah menjadi default di banyak browser.

Demikian pula, jika mengintegrasikan pemutar sematan YouTube di jendela yang dibuat menggunakan JavaScript window.open, Klien API tidak boleh menggunakan fitur noreferrer, yang menekan nilai Referer.

Menetapkan Perujuk

Di lingkungan tempat HTTP Referer kosong secara default dan tidak ditetapkan secara otomatis oleh browser, Klien API harus mengambil tindakan untuk memberikan identitas mereka melalui cara alternatif. Dalam integrasi WebView seperti aplikasi seluler atau aplikasi desktop, HTTP Referer kosong secara default dan Referer biasanya ditetapkan menggunakan salah satu teknik berikut:

  • Aplikasi seluler dengan pemutar di dalam file HTML lokal

    Dalam konfigurasi ini, pemutar dimuat dalam file HTML yang dibundel dengan aplikasi. Saat memuat file HTML ini, menyetel parameter baseUrl akan menyetel Referer.

  • Aplikasi seluler tanpa file HTML lokal

    Dalam konfigurasi ini, pemutar dimuat langsung dari https://www.youtube.com/embed/VIDEO_ID tanpa file HTML penutup. Anda menetapkan Referer dengan menambahkannya sebagai Header HTTP:

    • Android loadUrl dengan Header HTTP Referer ditambahkan ke parameter additionalHttpHeaders

    • iOS loadRequest: dengan Header HTTP Referer yang ditambahkan ke permintaan. Contoh:

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

  • Aplikasi seluler dengan pemutar di dalam tab browser native

    • Android CustomTabs

      Gunakan Intent.EXTRA_REFERRER untuk menetapkan perujuk. Pastikan untuk menggunakan skema android-app://, bukan https:// saat membuat Uri. Contoh:

      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 tidak mendukung penyetelan Referer. Dalam hal ini, tetapkan parameter pemutar origin.

  • Aplikasi desktop

    Dalam konfigurasi ini, tetapkan Referer dengan menambahkannya sebagai Header HTTP:

Untuk platform lain yang HTTP Referer-nya kosong secara default, tetapkan nilai Referer dengan mengonfigurasi WebView tempat pemutar dimuat. Teknik persisnya dapat bervariasi menurut platform.

Jika Anda adalah pemilik library, framework, plugin, layanan, atau wrapper yang digunakan oleh developer untuk mengintegrasikan pemutar sematan YouTube, Anda harus mengambil ID aplikasi dari lingkungan (hal ini mungkin tidak dapat dilakukan, bergantung pada platform) atau mengizinkan developer untuk meneruskan ID aplikasi mereka sehingga Referer (dan parameter pemutar widget_referrer, jika sesuai) dapat ditetapkan seperti yang dijelaskan di atas.

Format perujuk

Jika Anda secara eksplisit memberikan Referer dengan menyetel parameter WebView atau menambahkan Header HTTP, formatnya biasanya adalah URL yang sepenuhnya memenuhi syarat. Tentukan HTTPS sebagai protokol. Dalam URL, nama domain harus berupa ID aplikasi ("ID aplikasi") yang terdaftar di toko yang mendistribusikan aplikasi Anda kepada pengguna akhir. Jika aplikasi Anda diberikan kepada pengguna melalui saluran distribusi alternatif, gunakan ID aplikasi yang terdaftar di sistem operasi selama penginstalan aplikasi. Biasanya, ID aplikasi Anda akan berupa nama domain terbalik (juga dikenal sebagai "format DNS terbalik"), seperti com.google.android.youtube. Contoh representatif:

Di beberapa platform, ID aplikasi bukan nama domain terbalik. Dalam kasus ini, gunakan ID aplikasi unik yang ditetapkan oleh app store yang mendistribusikan aplikasi. Jika ID aplikasi app store adalah string alfanumerik yang dibuat (ditetapkan oleh app store atau alat pengembangan, bukan dipilih oleh developer aplikasi), sertakan nama tampilan aplikasi (ganti spasi dengan tanda hubung) dan ID aplikasi app store, yang dibatasi dengan titik. Misalnya: <my-app-name>.<AppID>. Nilai ini harus stabil di seluruh perubahan versi aplikasi. Jika aplikasi tidak dihosting di toko, gunakan ID aplikasi yang terdaftar di sistem operasi selama penginstalan aplikasi; biasanya berupa ID unik dalam manifes aplikasi. Kecualikan detail apa pun tentang versi aplikasi dan arsitektur yang didukung. Contoh representatif:

  • Chrome Web Store: dihosting di toko

    ID aplikasi store biasanya merupakan bagian terakhir dari jalur di URL aplikasi https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Gunakan nama aplikasi yang dihubungkan dengan tanda hubung dan ID aplikasi di Play Store untuk membuat string <my-app-name>.<AppID> yang dijelaskan di atas.

  • Windows: dihosting di toko

    ID aplikasi store biasanya merupakan bagian terakhir dari jalur di URL aplikasi https://apps.microsoft.com/detail/<AppID>. Gunakan ID aplikasi Play Store untuk membuat string <my-app-name>.<AppID> yang dijelaskan di atas. Nama aplikasi dengan tanda hubung juga harus disertakan.

  • Windows: distribusi non-toko

    Aplikasi Windows berisi identitas paket dalam manifes aplikasi: Name_Version_Architecture_ResourceID_PublisherID. Gunakan atribut Name saja.

  • Xbox: dihosting di toko

    ID aplikasi store biasanya merupakan bagian terakhir dari jalur di URL aplikasi https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Gunakan nama aplikasi yang dihubungkan dengan tanda hubung dan ID aplikasi di Play Store untuk membuat string <my-app-name>.<AppID> yang dijelaskan di atas.

Untuk Klien API dengan jumlah permintaan yang tinggi ke YouTube (lihat Penggunaan dan Kuota), kredensial tambahan mungkin diperlukan untuk mengakses pemutar sematan YouTube.

Jika persyaratan ini tidak dipenuhi, fungsionalitas di pemutar tersemat YouTube mungkin akan berkurang.

Jenis WebView

Saat mengintegrasikan pemutar sematan YouTube di WebView, gunakan salah satu jenis WebView yang disediakan OS jika tersedia. Contoh:

Ukuran Pemutar YouTube tersemat

Pemutar sematan harus memiliki area pandang berukuran minimal 200x200 piksel. Jika pemutar menampilkan kontrol, kontrol tersebut harus cukup besar untuk menampilkan kontrol sepenuhnya tanpa mengecilkan area tampilan di bawah ukuran minimum. Sebaiknya gunakan pemutar 16:9 dengan lebar minimal 480 piksel dan tinggi 270 piksel.

Pemutaran otomatis dan pemutaran dengan skrip

Bagian ini membahas pemutaran otomatis. Kebijakan ini berlaku untuk pemutar sematan YouTube yang menggunakan parameter pemutar autoplay atau memulai pemutaran otomatis secara terprogram menggunakan layanan YouTube IFrame Player API atau layanan YouTube API lainnya.

  • Pemutar yang disematkan yang memutar video secara otomatis harus memulai pemutaran segera saat halaman dimuat atau segera setelah pemutar yang disematkan terlihat sepenuhnya. Namun, Klien API tidak boleh memulai pemutaran otomatis hingga pemutar terlihat dan lebih dari setengah pemutar terlihat di halaman atau layar.

  • Halaman atau layar tidak boleh memiliki lebih dari satu pemutar YouTube yang memutar konten secara otomatis secara bersamaan.

  • Thumbnail YouTube yang memulai pemutaran harus memiliki lebar minimal 120 piksel dan tinggi 70 piksel.

Atribut Pemutar YouTube

Atribut dan parameter pemutar YouTube – termasuk, misalnya, tampilan branding YouTube di pemutar – ditentukan dalam dokumentasi dan spesifikasi YouTube API (https://developers.google.com/youtube). Anda tidak boleh melakukan perubahan pada pemutar YouTube yang tidak dijelaskan secara eksplisit oleh dokumentasi API.

Overlay dan frame

Anda tidak boleh menampilkan overlay, frame, atau elemen visual lainnya di depan bagian mana pun dari pemutar sematan YouTube, termasuk kontrol pemutar. Demikian pula, Anda tidak boleh menggunakan overlay, frame, atau elemen visual lainnya untuk menutupi bagian mana pun dari pemutar yang disematkan, termasuk kontrol pemutar.

Arahan kursor

Anda tidak boleh menggunakan peristiwa mengarahkan kursor atau sentuh pada pemutar YouTube untuk memulai tindakan apa pun atas nama pengguna, seperti membuka jendela atau berlangganan channel.

Mengupload video

Jika Klien API mengizinkan pengguna mengupload konten ke beberapa platform, pengguna harus dapat memilih dan membatalkan pilihan platform tempat mereka ingin mengupload video.

Persyaratan data

Klien API yang memungkinkan pengguna mengupload video ke YouTube harus mengizinkan pengguna untuk menetapkan nilai dalam daftar berikut. Semua properti yang tidak tercantum bersifat opsional.

  Nama Deskripsi
Properti resource
snippet.title Wajib diisi. Judul video. YouTube akan menampilkan error jika nilai melebihi 100 karakter. YouTube mendukung semua karakter UTF-8 yang valid kecuali < dan >.

snippet.description Wajib diisi. Deskripsi video. YouTube akan menampilkan error jika nilai melebihi 5.000 byte. YouTube mendukung semua karakter UTF-8 yang valid kecuali < dan >.
status.privacyStatus Wajib diisi. Setelan privasi video. Pengguna harus dapat memilih apakah video yang diupload akan bersifat publik, pribadi, atau tidak publik.
Parameter permintaan
onBehalfOfContentOwnerChannel Wajib bersyarat. Jika kredensial otorisasi permintaan mengidentifikasi pemilik konten dan parameter onBehalfOfContentOwner ditetapkan, pengguna API juga harus dapat menentukan channel YouTube tempat video diupload.

Menampilkan komentar

  Nama Deskripsi
Properti resource
snippet.textDisplay Wajib diisi. Teks komentar. Klien API harus (a) menampilkan teks lengkap komentar atau balasan komentar, atau (b) memangkas teks dan menyediakan cara bagi penonton untuk mengakses teks lengkap dengan mudah dari versi yang dipangkas.

Persyaratan ini berlaku untuk semua komentar dan balasan komentar, terlepas dari jenis resource yang terkait dengan komentar (video, channel, dll.).

Perhatikan bahwa nilai properti snippet.topLevelComment resource commentThread adalah resource comment dan properti replies.comments[] adalah daftar resource comment. Oleh karena itu, persyaratan ini juga berlaku untuk properti snippet.topLevelComment.snippet.textDisplay dan replies.comments[].snippet.textDisplay.
snippet.title
(channel)		 Wajib (saran). Judul channel.
  • Jika komentar berkaitan dengan channel, klien API harus menampilkan nama channel.
  • Jika komentar berkaitan dengan video, klien API harus menampilkan nama channel yang mengupload video tersebut.
snippet.title
(video)		 Wajib bersyarat (saran). Judul video. Nilai ini harus ditampilkan jika komentar berkaitan dengan video.
snippet.moderationStatus Wajib bersyarat. Jika nilai parameter moderationStatus dalam permintaan API adalah heldForReview atau likelySpam, tampilan harus mengidentifikasi status tersebut dengan jelas menggunakan nilai properti, bahasa yang serupa (misalnya, "Komentar ini sedang ditahan untuk ditinjau"), header (misalnya, "Ditahan untuk ditinjau"), atau bahasa lain yang tidak ambigu. Metode commentThreads.list mendukung kemampuan untuk mengambil komentar berdasarkan status moderasinya.

Menambahkan komentar

  Nama Deskripsi
Properti resource
snippet.title
(channel)		 Wajib diisi. Judul channel.
  • Jika pengguna menambahkan komentar tentang channel, klien API harus menampilkan nama channel.
  • Jika pengguna menambahkan komentar tentang video, klien API harus menampilkan nama channel yang mengupload video tersebut.
snippet.title
(video)		 Wajib diisi. Jika pengguna menambahkan komentar tentang video, klien API harus menampilkan judul video.
Persyaratan lainnya
Comment author's channel name Wajib diisi. Klien API harus mengidentifikasi dengan jelas akun pengguna YouTube yang akan dikaitkan dengan komentar tersebut. Jika kredensial otorisasi permintaan mengidentifikasi pemilik konten dan parameter onBehalfOfContentOwner ditetapkan, pengguna API juga harus dapat menentukan channel YouTube yang akan dikaitkan dengan komentar.

Menambahkan balasan komentar

  Nama Deskripsi
Properti resource
snippet.textDisplay Wajib diisi. Teks komentar. Klien API harus menampilkan teks komentar yang dibalas pengguna sesuai dengan aturan yang ditentukan di bagian Menampilkan komentar dalam dokumen ini.
snippet.title
(channel)		 Wajib diisi. Judul channel.
  • Jika pengguna membalas komentar tentang channel, klien API harus menampilkan nama channel.
  • Jika pengguna membalas komentar tentang video, klien API harus menampilkan nama channel yang mengupload video tersebut.
snippet.title
(video)		 Wajib diisi. Jika pengguna membalas komentar tentang video, klien API harus menampilkan judul video.
Persyaratan lainnya
Comment author's channel name Wajib diisi. Klien API harus mengidentifikasi dengan jelas akun pengguna YouTube yang akan dikaitkan dengan balasan komentar. Jika kredensial otorisasi permintaan mengidentifikasi pemilik konten dan parameter onBehalfOfContentOwner ditetapkan, pengguna API juga harus dapat menentukan channel YouTube yang akan dikaitkan dengan balasan komentar.

Mengedit atau menghapus balasan komentar

  Nama Deskripsi
Properti resource
snippet.textDisplay Wajib diisi. Teks komentar. Klien API harus menampilkan teks komentar yang sedang diedit atau dihapus pengguna sesuai dengan aturan yang ditentukan di bagian Menampilkan komentar dalam dokumen ini.
snippet.title
(channel)		 Wajib diisi. Judul channel.
  • Jika pengguna mengedit atau menghapus komentar tentang channel, klien API harus menampilkan nama channel.
  • Jika pengguna mengedit atau menghapus komentar tentang video, klien API harus menampilkan nama channel yang mengupload video tersebut.
snippet.title
(video)		 Wajib diisi. Jika pengguna mengedit atau menghapus komentar tentang video, klien API harus menampilkan judul video.
Persyaratan lainnya
Comment author's channel name Wajib diisi. Klien API harus mengidentifikasi dengan jelas akun pengguna YouTube yang menjadi tujuan atribusi komentar.

Memblokir pengguna dari live chat (atau menghapus pemblokiran)

  Nama Deskripsi
Properti resource
snippet.title
(channel)		 Wajib diisi. Nama channel YouTube yang diblokir atau tidak diblokir. Selain itu, nama harus ditautkan ke channel atau URL channel juga harus ditampilkan.
Persyaratan lainnya
Nama channel penulis komentar Wajib diisi. Klien API harus mengidentifikasi dengan jelas akun pengguna YouTube yang digunakan untuk menambahkan atau menghapus larangan.