이 페이지는 Cloud Translation API를 통해 번역되었습니다.

YouTube API 서비스 - 필수 최소 기능

참고: YouTube 개발자 정책 준수에서는 API 클라이언트가 YouTube API 서비스 약관 및 정책 (API TOS)의 특정 부분을 준수하도록 지원하는 가이드와 예를 제공합니다. 이 가이드에서는 YouTube가 API 서비스 약관의 특정 측면을 시행하는 방법을 설명하지만 기존 문서를 대체하지는 않습니다.

이 문서에서는 YouTube API 서비스의 특정 기능을 구현하거나 액세스 권한을 제공하는 API 클라이언트 ('API 클라이언트')의 최소 기능 요구사항을 정의합니다.

이러한 요구사항과 가이드라인은 API 클라이언트가 YouTube 사용자, 콘텐츠 소유자, 광고주의 이익을 보호하는 일관된 사용자 환경을 제공하도록 보장합니다. 이러한 규칙은 YouTube API 서비스 약관의 필수적인 부분이며 모든 API 클라이언트의 개발 및 구현 시 준수해야 합니다.

기존 YouTube 기능으로 더 나은 사용자 환경을 제공할 수 있도록 이 문서의 요구사항이 변경될 수 있습니다. 또한 새 YouTube 기능 및 업데이트된 YouTube 기능에 따라 변경됩니다. 이러한 변경사항으로 인해 새로운 요구사항을 해결하기 위해 API 클라이언트를 업데이트해야 할 수 있습니다. 서비스 약관 수정 내역에 변경사항이 문서화되므로 이 문서를 자주 확인하거나 RSS 피드를 구독하여 API 클라이언트에 영향을 줄 수 있는 변경사항을 빠르게 파악하세요.

이 문서의 요구사항 외에도 YouTube API 서비스 정책에 설명되어 있고 YouTube API 서비스 문서의 다른 곳에서 논의된 권장사항을 따르는 것이 좋습니다. 엄격하게 요구되지 않더라도 이러한 관행은 API 클라이언트가 오류에서 더 빠르게 복구하고 할당량을 할당하는 YouTube API 서비스를 사용하는 경우 할당량 사용을 최적화하는 데 도움이 됩니다. 이러한 관행은 YouTube 생태계의 건전성을 보장하고 무엇보다 API 클라이언트 및 YouTube 애플리케이션 사용자에게 최상의 환경을 제공하는 데 도움이 됩니다.

YouTube 내장 플레이어 및 동영상 재생

이 섹션의 요구사항은 특히 삽입된 YouTube 플레이어와 관련이 있습니다. YouTube API 서비스 정책에는 YouTube 시청각 콘텐츠를 재생하는 API 클라이언트와 관련된 여러 정책도 포함되어 있습니다.

API 클라이언트 ID 및 사용자 인증 정보

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 클라이언트는 Referer 값을 억제하는 noreferrer 기능을 사용해서는 안 됩니다.

Referer 설정

HTTP Referer가 기본적으로 비어 있고 브라우저에서 자동으로 설정되지 않는 환경에서 API 클라이언트는 대체 수단을 통해 ID를 제공하기 위한 조치를 취해야 합니다. 모바일 앱이나 데스크톱 앱과 같은 WebView 통합에서 HTTP Referer는 기본적으로 비어 있으며 Referer는 일반적으로 다음 기법 중 하나를 사용하여 설정됩니다.

로컬 HTML 파일 내에 플레이어가 있는 모바일 앱

이 구성에서 플레이어는 앱과 번들로 제공되는 HTML 파일에 로드됩니다. 이 HTML 파일을 로드할 때 baseUrl 매개변수를 설정하면 Referer이 설정됩니다.
- Android loadDataWithBaseURL
- iOS loadHTMLString:baseURL:

로컬 HTML 파일이 없는 모바일 앱

이 구성에서는 플레이어가 HTML 파일 없이 https://www.youtube.com/embed/VIDEO_ID에서 직접 로드됩니다. HTTP 헤더로 추가하여 Referer를 설정합니다.

additionalHttpHeaders 매개변수에 추가된 Referer HTTP 헤더가 있는 Android loadUrl

요청에 Referer HTTP 헤더가 추가된 iOS loadRequest: 예를 들면 다음과 같습니다.

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를 만들 때는 https:// 대신 android-app:// 스키마를 사용해야 합니다. 예를 들면 다음과 같습니다.
```
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 플레이어 매개변수를 대신 설정하세요.
데스크톱 앱

이 구성에서는 HTTP 헤더로 추가하여 Referer를 설정합니다.
- Microsoft .NET - HttpRequestHeaders.Referrer 또는 CoreWebView2HttpRequestHeaders.SetHeader 사용
- macOS - iOS 모바일 앱에 대해 위에 설명된 것과 동일한 안내를 따릅니다.

HTTP Referer가 기본적으로 비어 있는 다른 플랫폼의 경우 플레이어가 로드되는 WebView를 구성하여 Referer 값을 설정합니다. 정확한 기술은 플랫폼에 따라 다를 수 있습니다.

개발자가 YouTube 삽입 플레이어를 통합하는 데 사용하는 라이브러리, 프레임워크, 플러그인, 서비스 또는 래퍼의 소유자인 경우 환경에서 앱 ID를 가져오거나 (플랫폼에 따라 불가능할 수 있음) 개발자가 앱 ID를 전달할 수 있도록 허용하여 위에 설명된 대로 Referer (및 적절한 경우 widget_referrer 플레이어 매개변수)를 설정해야 합니다.

리퍼러 형식

WebView 매개변수를 설정하거나 HTTP 헤더를 추가하여 Referer를 명시적으로 제공하는 경우 형식은 일반적으로 정규화된 URL입니다. HTTPS를 프로토콜로 지정합니다. URL 내에서 도메인 이름은 최종 사용자에게 앱을 배포한 스토어에 등록된 애플리케이션 식별자 ('앱 ID')여야 합니다. 앱이 대체 배포 채널을 통해 사용자에게 제공되는 경우 앱 설치 중에 운영체제에 등록된 앱 ID를 사용하세요. 대부분의 경우 앱 ID는 com.google.android.youtube와 같은 역순 도메인 이름('역순 DNS 형식'이라고도 함)입니다. 대표적인 예:

ChromeOS의 Android OS 및 Android 앱: 앱 ID
iOS, iPadOS, macOS를 비롯한 Apple 플랫폼: 번들 ID
Samsung Tizen: 앱 ID
Linux 배포판:
- Fedora: 앱 ID
- Gnome: 앱 ID
- Ubuntu: 앱 ID

일부 플랫폼에서는 앱 ID가 역순 도메인 이름이 아닙니다. 이 경우 앱을 배포하는 스토어에서 할당한 고유 앱 ID를 사용하세요. 스토어 앱 ID가 생성된 영숫자 문자열 (앱 개발자가 선택한 것이 아니라 스토어 또는 개발 도구에서 할당한 것)인 경우 앱 표시 이름 (공백을 하이픈으로 대체)과 스토어 앱 ID를 모두 포함하고 마침표로 구분하세요. 예: <my-app-name>.<AppID> 이 값은 앱 버전이 변경되어도 안정적이어야 합니다. 앱이 스토어에 호스팅되지 않는 경우 앱 설치 중에 운영체제에 등록된 앱 ID를 사용합니다. 이는 일반적으로 앱 매니페스트의 고유 식별자입니다. 앱 버전 및 지원되는 아키텍처에 관한 세부정보는 제외합니다. 대표적인 예:

Chrome 웹 스토어: 스토어 호스팅

스토어 앱 ID는 일반적으로 앱 URL https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>의 경로 중 마지막 부분입니다. 하이픈으로 연결된 앱 이름과 스토어 앱 ID를 사용하여 위에 설명된 <my-app-name>.<AppID> 문자열을 빌드합니다.
Windows: 스토어 호스팅

스토어 앱 ID는 일반적으로 앱 URL https://apps.microsoft.com/detail/<AppID>의 경로 중 마지막 부분입니다. 스토어 앱 ID를 사용하여 위에 설명된 <my-app-name>.<AppID> 문자열을 빌드합니다. 하이픈으로 연결된 앱 이름도 포함해야 합니다.
Windows: 스토어 외 배포

Windows 앱에는 앱 매니페스트에 패키지 ID(Name_Version_Architecture_ResourceID_PublisherID)가 포함되어 있습니다. Name 속성만 사용합니다.
Xbox: 스토어 호스팅

스토어 앱 ID는 일반적으로 앱 URL https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>의 경로 중 마지막 부분입니다. 하이픈으로 연결된 앱 이름과 스토어 앱 ID를 사용하여 위에 설명된 <my-app-name>.<AppID> 문자열을 빌드합니다.

YouTube에 대한 요청 수가 많은 API 클라이언트 (사용량 및 할당량 참고)의 경우 YouTube 삽입 플레이어에 액세스하려면 추가 사용자 인증 정보가 필요할 수 있습니다.

이러한 요구사항을 준수하지 않으면 YouTube 삽입 플레이어의 기능이 축소될 수 있습니다.

WebView 유형

WebView에 YouTube 삽입 플레이어를 통합할 때는 OS에서 제공하는 WebView 유형을 사용하세요(사용 가능한 경우). 예를 들면 다음과 같습니다.

Android OS: WebView 또는 CustomTabs
iOS, iPadOS, macOS를 비롯한 Apple 플랫폼: WKWebView 또는 SFSafariViewController

삽입된 YouTube 플레이어 크기

내장 플레이어에는 200x200픽셀 이상의 표시 영역이 있어야 합니다. 플레이어에 컨트롤이 표시되는 경우에는 표시 영역이 최소 크기 미만으로 축소되지 않고 컨트롤이 완전히 표시될 만큼 커야 합니다. 16:9 플레이어의 경우 가로 480픽셀, 세로 270픽셀 이상으로 지정하는 것이 좋습니다.

자동 재생 및 스크립트 기반 재생

이 섹션에서는 자동 재생을 다룹니다. autoplay 플레이어 매개변수를 사용하거나 YouTube IFrame Player API 서비스 또는 다른 YouTube API 서비스를 사용하여 프로그래매틱 방식으로 자동 재생을 시작하는 YouTube 삽입 플레이어에 적용됩니다.

동영상을 자동으로 재생하는 삽입된 플레이어는 페이지가 로드될 때 또는 삽입된 플레이어가 완전히 표시되는 즉시 재생을 시작해야 합니다. 하지만 API 클라이언트는 플레이어가 표시되고 페이지나 화면에 플레이어의 절반 이상이 표시될 때까지 자동 재생을 시작해서는 안 됩니다.
콘텐츠를 동시에 자동 재생하는 YouTube 플레이어가 페이지 또는 화면에 2개 이상 있어서는 안 됩니다.
재생을 시작하는 YouTube 썸네일은 너비가 120픽셀 이상이고 높이가 70픽셀 이상이어야 합니다.

YouTube 플레이어 속성

플레이어의 YouTube 브랜딩 모양을 비롯한 YouTube 플레이어의 속성과 매개변수는 YouTube API 문서 및 사양 (https://developers.google.com/youtube)에 명시되어 있습니다. API 문서에 명시적으로 설명되지 않은 YouTube 플레이어를 변경해서는 안 됩니다.

오버레이 및 프레임

플레이어 컨트롤을 비롯한 YouTube 삽입 플레이어의 일부 앞에 오버레이, 프레임 또는 기타 시각적 요소를 표시해서는 안 됩니다. 마찬가지로 오버레이, 프레임 또는 기타 시각적 요소를 사용하여 플레이어 컨트롤을 비롯한 포함된 플레이어의 일부를 가려서는 안 됩니다.

마우스오버

YouTube 플레이어에서 마우스 오버 또는 터치 이벤트를 사용하여 창을 열거나 채널을 구독하는 등 사용자를 대신하여 작업을 시작해서는 안 됩니다.

동영상 업로드하기

API 클라이언트를 통해 사용자가 여러 플랫폼에 콘텐츠를 업로드할 수 있는 경우 사용자는 동영상을 업로드할 플랫폼을 선택하거나 선택 해제할 수 있어야 합니다.

데이터 요구사항

사용자가 YouTube에 동영상을 업로드할 수 있도록 지원하는 API 클라이언트는 사용자가 다음 목록의 값을 설정할 수 있도록 해야 합니다. 나열되지 않은 속성은 선택사항입니다.

	이름	설명
리소스 속성
	`snippet.title`	필수사항: 동영상의 제목입니다. 값이 100자를 초과하면 YouTube에서 오류를 반환합니다. YouTube는 `<` 및 `>`을 제외한 모든 유효한 UTF-8 문자를 지원합니다.
	`snippet.description`	필수사항: 동영상이 설명입니다. 값이 5,000바이트를 초과하면 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 채널의 이름입니다. 또한 이름이 채널로 연결되어야 하며 채널 URL도 표시되어야 합니다.
기타 요구사항
	댓글 작성자의 채널 이름	필수사항: API 클라이언트는 차단을 추가하거나 삭제하는 데 사용되는 YouTube 사용자 계정을 명확하게 식별해야 합니다.

YouTube API 서비스 - 필수 최소 기능 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.