Pod Serving API는 사용자 대상 HLS 또는 MPEG-DASH 미디어 재생목록에 직접 연결할 수 있도록 준비된 적응형 비트 전송률 동영상 광고 모음에 대한 액세스를 제공합니다.
이 가이드에서는 VOD 스트림을 위한 기본 Pod 게재 매니페스트 조작 서버를 구현하는 방법을 중점적으로 설명합니다.
스트림 매니페스트 요청 수신
매니페스트 조작기는 동영상 플레이어 클라이언트 앱의 매니페스트 요청을 리슨하는 API 엔드포인트를 제공해야 합니다. 이 엔드포인트는 최소한 클라이언트 플레이어 앱에서 스트림 ID를 수집해야 합니다. 이 스트림 ID는 광고 모음 요청에서 Ad Manager로의 스트리밍 세션을 식별하는 데 사용됩니다.
또한 적절한 콘텐츠 스트림을 식별하기 위해 콘텐츠 ID와 같은 기타 정보를 수집해야 합니다.
매니페스트 요청 엔드포인트 예시
GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
| 경로 매개변수 | |||||
|---|---|---|---|---|---|
stream_id |
클라이언트 동영상 플레이어 앱의 Ad Manager 스트림 ID입니다. | ||||
content_id |
시스템의 콘텐츠 동영상에 해당하는 가상의 ID입니다. | ||||
format |
스트림 형식에 해당하는 가상 매개변수입니다. 다음 중 하나:
|
||||
콘텐츠 스트림 가져오기
매니페스트 요청에서 수집된 콘텐츠 ID를 사용하여 광고와 연결할 콘텐츠 스트림을 선택합니다.
광고 모음 매니페스트 요청
Ad Manager에서 광고를 요청하려면 서버에서 광고 모음 엔드포인트에 POST 요청을 보내고 요청된 인코딩 프로필과 광고 태그를 전달해야 합니다. 이 요청에는 1단계에서 수집한 스트림 ID도 포함됩니다.
대가로 게시자 광고 태그에서 요청한 광고 모음의 매니페스트 파일과 콘텐츠에 광고 모음을 삽입해야 하는 시점과 위치에 관한 정보가 포함된 광고 모음 객체 목록을 수신합니다.
POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
| 경로 매개변수 | |
|---|---|
network_code |
게시자의 Ad Manager 360 네트워크 코드입니다. |
stream_id |
클라이언트 동영상 플레이어 앱의 스트림 ID입니다. |
JSON 본문
| 본문 파라미터 | ||
|---|---|---|
encoding_profiles |
Required |
광고 시점마다 수신하려는 인코딩 프로필의 JSON 표현 목록입니다. 세부정보는 아래를 참고하세요
재생을 최대한 원활하게 하려면 콘텐츠 스트림에 사용되는 인코딩 프로필 세트와 일치해야 합니다. |
ad_tag |
Required |
VMAP 광고를 요청하는 광고 태그입니다. |
cuepoints |
Optional |
미드롤 광고 시점이 삽입될 콘텐츠 스트림 내 큐 포인트 목록입니다. 큐 포인트는 부동 소수점 초 단위로 측정됩니다.
위치 시차를 사용하는 미드롤이 포함된 VMAP 응답에만 필요합니다. 이는 흔치 않은 경우입니다. |
content_duration_seconds |
Optional |
콘텐츠 길이(초)입니다.
비율 시간 오프셋을 사용하는 미드롤이 포함된 VMAP 응답에만 필요합니다. 이는 흔치 않은 경우입니다. |
manifest_type |
Optional |
요청된 광고 스트림의 형식(hls 또는 dash)입니다. 기본값은 hls입니다.
|
dai_options |
Optional |
매니페스트가 렌더링되는 방식의 측면을 제어하는 추가 옵션입니다. 세부정보는 아래를 참고하세요 |
인코딩 프로필 | ||
profile_name |
Required |
이 인코딩 프로필의 식별자입니다. 이 값은 선택한 임의의 문자열이 될 수 있지만 동일한 스트림에 동일한 이름의 인코딩 프로필을 여러 개 가질 수는 없습니다. |
type |
Required |
이 인코딩 프로필에 의해 설명되는 스트림의 인코딩 유형입니다. 콘텐츠 유형은 media, iframe, subtitles입니다.
|
container_type |
Required |
이 인코딩 프로필에 사용되는 컨테이너 형식입니다. 컨테이너 형식은 mpeg2ts, fmp4cmaf, hls_packed_audio입니다.
|
video_settings |
Optional |
인코딩 프로필 유형이 iframe인 경우 필수입니다. 그 외의 경우 미디어 유형에 동영상이 포함된 경우에만 허용됩니다. 아래 세부정보 참고 |
audio_settings |
Optional |
인코딩 프로필에 오디오가 포함된 경우 필수입니다. 유형이 미디어인 경우에만 허용됩니다. 세부정보는 아래를 참고하세요 |
subtitle_settings |
Optional |
인코딩 프로필에 자막이 포함된 경우 필수입니다. 세부정보는 아래를 참고하세요 |
동영상 설정 | ||
codec |
Required |
RFC6381 코덱 문자열입니다.
예: |
bitrate |
Required |
이 프로필의 최대 동영상 비트 전송률을 초당 바이트 단위로 나타내는 정수입니다. |
frames_per_second |
Required |
동영상의 부동 소수점 FPS입니다. |
resolution |
Required |
동영상의 `width` 및 `height`(단위: 픽셀)를 포함하는 JSON으로 인코딩된 값입니다.
예: |
오디오 설정 | ||
codec |
Required |
RFC6381 코덱 문자열입니다.
예: |
bitrate |
Required |
이 프로필의 최대 오디오 비트 전송률을 초당 바이트 단위로 나타내는 정수입니다.
예: |
channels |
Required |
저주파 채널을 포함한 오디오 채널 수를 나타내는 정수입니다. |
sample_rate |
Required |
오디오 샘플링 레이트를 헤르츠 단위로 나타내는 정수입니다.
예: |
자막 설정 | ||
format |
Required |
인밴드 자막에서 사용하는 파일 형식입니다. 지원되는 값은 webvtt 또는 ttml입니다.
|
language |
Optional |
자막 언어를 RFC5646 언어 문자열로 지정합니다. 이 값은 제공되는 경우 DASH 렌더링에만 사용됩니다.
예: |
DAI 옵션 | ||
dash_profile |
Optional |
광고 모음 매니페스트에 적용할 MPEG-DASH 프로필입니다. 이 설정은 DASH 매니페스트에만 사용됩니다. 허용되는 값은 live 또는 on-demand입니다. 기본값은 on-demand입니다.
|
ad_pod_timeout |
Optional |
광고를 선택하고 광고 모음을 만드는 데 사용할 수 있는 최대 시간(부동 소수점 초)입니다. 이 시간이 지나면 Ad Manager는 ad_pods 응답에서 이미 선택된 광고를 반환하고 처리를 중지합니다.
|
sam_id |
Optional |
라이브 스트림 활동 모니터링 도구에서 세션을 조회하는 데 사용할 수 있는 대체 디버그 키를 지정합니다. |
응답
| 응답 매개변수 | |
|---|---|
valid_for |
이러한 광고 모음 재생목록이 유효한 기간입니다(dhms(일, 시간, 분, 초) 형식).
|
valid_until |
이러한 광고 모음 재생목록이 유효한 날짜 및 시간으로, ISO8601 날짜/시간 문자열이며 yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 형식입니다.
|
ad_pods |
이 스트림에 대해 선택된 광고 모음의 목록입니다. |
| 광고 모음 | |
manifest_uris |
HLS 스트림에만 해당합니다. 인코딩 프로필 ID를 HLS 매니페스트 URI에 매핑하는 맵입니다. |
mpd_uri |
DASH 스트림에만 해당합니다. DASH MPD의 URI입니다. |
type |
광고 모음의 유형입니다. 광고 모음 유형은 pre, mid 또는 post입니다.
|
start |
미드롤 광고 모음만 해당합니다. 이 광고 모음을 삽입해야 하는 스트림의 위치입니다(부동 소수점 초). |
duration |
이 광고 모음의 길이(부동 소수점 초)입니다. |
midroll_index |
미드롤 광고 모음만 해당합니다. 현재 미드롤 광고 모음의 색인입니다. 색인은 1로 시작합니다.
|
요청 예시(cURL)
curl -X POST \
-d '@request-body.json' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods
요청 본문 예시:
위의 cURL 호출에서 참조된 request-body.json의 콘텐츠입니다.
{
"encoding_profiles": [
{
"profile_name": "1080p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000c",
"bitrate": 5000000,
"frames_per_second": 30.0,
"resolution": {
"width": 1920,
"height": 1080
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 300000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "360p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000d",
"bitrate": 1000000,
"frames_per_second": 30.0,
"resolution": {
"width": 640,
"height": 360
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 64000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "subtitles-webvtt",
"type": "subtitles",
"subtitle_settings": {
"format": "webvtt"
}
}
],
"ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
"manifest_type": "hls"
}
응답 예
{
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00",
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
},
"type": "post",
"duration": 10.0
}
]
}
콘텐츠에 광고 모음 병합
광고 모음을 콘텐츠 스트림에 연결하는 프로세스는 구현, 스트림 형식, 형식 사양에서 구현할 기능에 따라 다릅니다. 다음 워크플로는 이 프로세스를 처리하는 방법에 관한 제안사항입니다. 구현의 정확한 세부정보는 비즈니스 요구사항과 콘텐츠 스트림에 따라 다를 수 있습니다.
HLS 스트림
HLS 형식으로 스트림을 스티칭하는 경우 콘텐츠 스트림은 인코딩 프로필별로 하나씩 별도의 스트림 매니페스트 링크로 구성된 다양한 버전의 재생목록이 됩니다. 광고 포드는 이러한 각 대안 매니페스트에 삽입되어야 합니다. 이를 위한 한 가지 방법은 모든 변형 매니페스트를 준비하고 호스팅을 위해 콘텐츠 전송 네트워크 (CDN)에 전달하는 것입니다. 최종 다중 변형 재생목록은 이러한 CDN 호스팅 매니페스트로 연결되는 링크 모음입니다.
인코딩 프로필 반복
인코딩 프로필별로 Ad Manager 응답에서 연결된 모든 광고 모음 매니페스트와 연결된 시작 시간을 수집합니다. 프리롤 광고 모음의 경우 시작 시간을 0로 설정합니다. 포스트롤의 경우 콘텐츠 재생 시간을 광고 모음의 시작 시간으로 사용합니다. 각 인코딩 프로필의 오디오 및 동영상 설정과 일치하는 대안 스트림을 대안 플래이리스트에 식별합니다.
광고 모음 배열의 예
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
},
"type": "post",
"duration": 10.0
}
]
다중 변형 콘텐츠 재생목록의 예
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8
수집된 옵션 데이터의 예
Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://{...}/pod/0/profile/1080p.m3u8
15 -> https://{...}/pod/1/profile/1080p.m3u8
600 -> https://{...}/pod/2/profile/1080p.m3u8
각 대안 매니페스트에 광고 삽입
각 대안 스트림의 경우 콘텐츠 매니페스트의 세그먼트를 살펴보고 경과된 콘텐츠 시간을 누적합니다. 광고 모음의 시작 위치에 도달하면 광고 모음의 매니페스트에서 세그먼트 목록을 추출하고, 세그먼트 목록을 두 개의 #EXT-X-DISCONTINUITY 태그로 래핑한 후 콘텐츠 매니페스트의 현재 위치에 목록을 삽입합니다. 모든 광고 모음 및 대안 스트림이 처리될 때까지 이 프로세스를 계속합니다.
결과 매니페스트는 HLS 표준을 준수해야 합니다. 따라서 콘텐츠 매니페스트에 통합된 사양의 기능에 따라 결합된 매니페스트를 최종적으로 한 번 더 확인하여 미디어 시퀀스 번호, 콘텐츠 길이, 불연속 시퀀스 번호, 새 광고 세그먼트를 고려하여 업데이트해야 하는 기타 태그를 수정해야 할 수 있습니다. 표준과의 불일치가 수정되면 각 사용자별 대안 매니페스트를 호스팅을 위해 CDN에 푸시합니다.
콘텐츠 매니페스트가 암호화된 경우 현재 광고 모음이 시작되기 전에 찾은 마지막 암호화 키를 #EXT-X-KEY 태그에 저장해야 합니다. 그런 다음 각 광고 모음의 첫 번째 세그먼트 앞에 #EXT-X-KEY:METHOD=NONE 태그를 추가하여 암호화를 삭제해야 합니다. 마지막으로 콘텐츠 암호화를 복원하려면 각 광고 모음 뒤의 콘텐츠 첫 번째 세그먼트 앞에 저장된 #EXT-X-KEY 태그의 사본을 추가해야 합니다.
수집된 옵션 데이터의 예
Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8
콘텐츠 매니페스트 예시
수집된 옵션 데이터에 나열된 https://{...}/1080p.m3u8 매니페스트의 콘텐츠입니다.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
광고 포드 매니페스트의 예
수집된 옵션 데이터에 나열된 https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 매니페스트의 콘텐츠입니다.
#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
꿰맨 변형 매니페스트의 예
이는 CDN에 전달되고 https://cdn.{...}/{userid}/1080p.m3u8에서 호스팅되는 결과로 생성된 스티치된 변형 매니페스트입니다.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
다중 변형 재생목록 빌드
완료된 각 변형 매니페스트의 CDN 주소와 일치하는 인코딩 프로필 세부정보를 수집하고 결과를 새 다중 변형 매니페스트로 조합합니다. 이 사용자별 매니페스트는 1단계에서 수신한 매니페스트 요청에 대한 응답으로 반환됩니다.
최종 다중 변형 재생목록의 예
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8
MPEG DASH 스트림
MPEG DASH 형식의 스트림을 스티칭하는 경우 단일 파일만 생성하면 됩니다. 이렇게 하면 DASH 스트림을 HLS보다 쉽게 스티치할 수 있습니다.
올바르게 준비된 MPEG DASH 미디어 프레젠테이션 설명 (MPD) 파일은 각각 여러 표현을 포함하는 여러 기간으로 구성되어야 합니다. 각 표현은 인코딩 프로필 중 하나와 일치해야 합니다. Ad Manager에서 반환된 각 광고 포드는 일치하는 표현이 포함된 기간 시퀀스가 포함된 MPD 파일입니다.
이러한 MPD 파일을 연결하려면 먼저 각 광고 모음의 시작 시간을 기록합니다. 프리롤의 경우 콘텐츠 기간 전에 프리롤 광고 모음 기간을 삽입합니다. 포스트롤의 경우 모든 콘텐츠 기간 뒤에 포스트롤 광고 모음 기간을 삽입합니다. 콘텐츠 MPD의 기간을 반복하여 처리된 모든 콘텐츠 기간의 경과된 재생 시간을 추적합니다. 광고 모음의 시작 시간에 해당하는 기간 사이의 경계에 도달하면 일치하는 미드롤 광고 모음의 MPD 파일에서 해당 경계에 기간을 삽입합니다.
최종으로 꿰맨 MPD 파일은 MPEG_DASH 사양을 완전히 준수해야 하므로 최종 파일을 한 번 더 반복하여 기간 시작 시간을 수정하고, 새로 삽입된 광고 기간을 고려하도록 미디어 프레젠테이션 시간을 수정하고, 꿰매기 프로세스에서 발생할 수 있는 다른 충돌을 해결해야 할 수 있습니다.
콘텐츠 MPD 예
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
광고 모음 JSON 예시
[{
"mpd_uri": "https://{...}pod/1.mpd",
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
}]
광고 모음 MPD의 예
위의 광고 모음 JSON에서 mpd_uri의 콘텐츠입니다.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Ad Pod 1</Title>
</ProgramInformation>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
...
</MPD>
MPD 꿰매기 예시
이 매니페스트를 초기 스트림 매니페스트 요청에 대한 응답으로 제공합니다.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
추가 리소스
- IMA SDK를 사용하여 광고 모음을 재생하는 방법은 다음과 같습니다.
- DAI API를 사용한 광고 모음 게재 재생