Pod Serving API는 준비된 적응형 비트 전송률 동영상 광고 모음에 대한 액세스를 제공합니다. 사용자에게 표시되는 HLS에 직접 연결하거나 MPEG-DASH 미디어 재생목록입니다.
이 가이드에서는 기본적인 광고 모음 게재 매니페스트 조작을 구현하는 데 중점을 둡니다. 제공합니다
스트림 매니페스트 요청 수신
매니페스트 조작기는 매니페스트를 수신 대기하는 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 |
스트림 형식에 해당하는 가상의 매개변수입니다. 다음 중 하나입니다.
|
콘텐츠 스트림 가져오기
매니페스트 요청에서 수집한 Content ID를 사용하여 콘텐츠 선택 광고를 연결할 수 있습니다.
광고 모음 매니페스트 요청
Ad Manager에서 광고를 요청하려면 서버가 광고에 POST 요청을 해야 합니다. 광고 모음 엔드포인트에서 요청된 인코딩 프로필, 광고 태그, 매개변수입니다. 이 요청에는 단계에서 수집한 스트림 ID도 포함됩니다. 1.
대신 광고 모음에 속한 광고 모음의 목록인 게시자의 광고 태그에서 요청한 광고 모음 및 콘텐츠에 삽입해야 할 위치를 지정할 수 있습니다
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 응답에만 필요합니다. percentage 시간 오프셋. 드문 경우입니다. |
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 |
오디오 샘플링 레이트(Hz)를 나타내는 정수입니다.
예: |
자막 설정 | ||
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 형식으로 연결하는 경우 콘텐츠 스트림은 다중 변수 재생목록 각 인코딩 프로필에 하나씩, 별도의 스트림 매니페스트에 대한 링크를 제공합니다. 광고 포드를 각 변형 매니페스트에 삽입해야 합니다. 한 가지 방법은 이렇게 하면 모든 변형 매니페스트를 준비하여 Content 전송 네트워크 (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>
추가 리소스
- 광고 모음에 광고를 게재하는 경우 <ph type="x-smartling-placeholder">
- DAI로 재생 중인 광고 모음 API