Google DAI 광고 모음 게재 API를 사용하면 서버 측 광고 삽입을 Google Ads에서 제공합니다.
이 가이드에서는 Pod Serving API와 상호작용하여 유사한 기능을 제공합니다. 다음에 관한 구체적인 질문이 있는 경우: 자세히 알아보려면 Google 계정 관리자에게 문의하세요.
Pod Serving API는 HLS 또는 MPEG-DASH에서 포드 서빙 스트림을 지원합니다. 스트리밍 프로토콜입니다. 이 가이드에서는 HLS 스트림을 중점적으로 설명하고 주요 기능을 설명합니다. 특정 단계에서의 HLS와 MPEG-DASH 간의 차이를 보여줍니다.
VOD 스트림을 위해 Pod Serving API를 앱에 통합하려면 다음 단계를 따르세요.
Ad Manager에 스트림 등록 요청 보내기
스트림 등록 엔드포인트에 POST 요청을 보냅니다. 사용자는 매니페스트 조작으로 전송할 스트림 ID가 포함된 JSON 응답 포드 서빙 API 엔드포인트를 사용할 수 있습니다
API 엔드포인트
POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json
경로 매개변수
{network_code} |
Google Ad Manager 360 네트워크 코드 |
JSON 본문 매개변수
targeting_parameters |
콘텐츠 소스 ID (cmsid), 동영상 ID (vid) 및 광고 타겟팅 매개변수와 동일합니다. 필수 항목 |
응답 JSON
media_verification_url |
재생 추적 이벤트를 핑하는 기준 URL입니다. 이 기준 URL에 광고 이벤트 ID를 추가하면 완전한 미디어 인증 URL이 구성됩니다. |
metadata_url |
광고 모음 메타데이터를 요청하는 URL입니다. |
stream_id |
현재 스트림 세션을 식별하는 데 사용되는 문자열입니다. |
valid_for |
현재 스트림 세션이 만료될 때까지 남은 시간입니다(dhms(일, 시간, 분, 초) 형식). 예를 들어 2h0m0.000s는 2시간 기간을 나타냅니다.
|
valid_until |
현재 스트림 세션이 만료되는 시간으로, yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 형식의 ISO 8601 날짜/시간 문자열입니다.
|
요청 예시(cURL)
curl -X POST \
-d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration
응답 예시
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
오류가 발생하면 JSON 응답 본문 없이 표준 HTTP 오류 코드가 반환됩니다.
JSON 응답을 파싱하고 관련 값을 저장합니다.
매니페스트 조작기에서 스트림 매니페스트 요청
각 매니페스트 조작기의 요청 및 응답 형식은 서로 다릅니다. 연락처 조종사 제공업체에 문의하여 구체적인 요구사항을 파악하세요. 만약 매니페스트 조작자를 구현하는 방법은 매니페스트 조작기 가이드를 참고하여 이 구성요소의 요구사항도 확인할 수 있습니다
일반적으로 매니페스트 조작기에 등록 엔드포인트를 추가하여 세션별 매니페스트를 참조하세요 매니페스트에 명시적으로 언급되지 않은 경우 매니페스트 요청에 대한 응답은 광고를 모두 게재할 수 있습니다.
요청 예시(cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
응답 예 (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
스트림 재생
매니페스트 조작 서버에서 수신한 매니페스트를 재생을 시작할 수 있습니다.
Ad Manager에서 광고 모음 메타데이터 요청
1단계에서 받은 metadata_url에 GET 요청을 실행합니다. 이
병합된 매니페스트를 받은 후에 이 단계가 수행되어야 합니다.
작동됩니다. 그러면 다음이 포함된 JSON 객체가 수신됩니다.
매개변수:
tags |
페이지에 표시되는 모든 광고 이벤트를 포함하는 키-값 쌍
있습니다. 키는 광고 이벤트의 처음 17자 또는
스트림의 시간이 지정된 메타데이터에 표시되거나 이벤트의 경우 표시되는 ID입니다.
progress 유형의 전체 광고 이벤트 ID입니다.
각 값은 다음 매개변수를 포함하는 객체입니다.
|
||||||||||||||||||
ads |
스트림에 표시되는 모든 광고를 설명하는 키-값 쌍 집합입니다. 이
키는 tags 객체에 있는 값과 일치하는 광고 ID입니다.
를 참조하세요. 각 값은 다음 매개변수를 포함하는 객체입니다.
|
||||||||||||||||||
ad_breaks |
스트림에 표시되는 모든 광고 시점을 설명하는 키-값 쌍 세트입니다.
키는 tags에 있는 값과 일치하는 광고 시점 ID입니다.
및 위에 나열된 ads 객체입니다. 각 값은
다음 매개변수를 포함합니다.
|
동영상 내의 시간이 지정된 메타데이터 이벤트와 연결하려면 이러한 값을 저장하세요. 있습니다.
요청 예시(cURL)
curl https://dai.google.com/.../metadata
응답 예
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
광고 이벤트 수신 대기
오디오/동영상 스트림에서 트리거된 광고 이벤트를 통해 시간이 지정된 메타데이터 수신 설정할 수 있습니다.
MPEG-TS 스트림의 경우 메타데이터가 대역 내 ID3 v2.3 태그로 표시됩니다. 각
메타데이터 태그의 ID는 TXXX이며 값은 google_ 문자열로 시작합니다.
이어서 일련의 문자가 이어집니다 이 값이 광고 이벤트 ID입니다.
TXXX의 XXX는 자리표시자가 아닙니다. 문자열 TXXX는 ID3 태그 ID입니다.
'사용자 정의 텍스트'용으로 예약되어 있습니다.
예시 ID3 태그
TXXXgoogle_1234567890123456789
MP4 스트림의 경우 ID3 v2.3을 에뮬레이션하는 대역 내 emsg 이벤트로 전송됩니다.
태그 사이에 있어야 합니다. 각 관련 이메일 상자에는 다음 중 하나의 scheme_id_uri 값이 있습니다.
https://aomedia.org/emsg/ID3 또는
https://developer.apple.com/streaming/emsg-id3 및 message_data 값
ID3TXXXgoogle_(으)로 시작합니다. 이 message_data 값은
ID3TXXX 접두사는 광고 이벤트 ID입니다.
이메일 상자 예
데이터 구조는 미디어 플레이어 라이브러리에 따라 다를 수 있습니다.
광고 이벤트 ID가 google_1234567890123456789인 경우 응답은 다음과 같습니다.
다음과 같습니다.
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
일부 미디어 플레이어 라이브러리가 ID3을 에뮬레이션하는 emsg 이벤트를 자동으로 표시 태그를 네이티브 ID3 태그로 전달합니다. 이 경우 MP4 스트림에는 동일한 ID3 태그가 표시됩니다. MPEG_TS 형식으로 캡처됩니다.
클라이언트 동영상 플레이어 앱의 UI 업데이트
각 광고 이벤트 ID를 4단계의 tags 객체의 키와 일치시킬 수 있습니다.
이러한 값을 일치시키는 작업은 두 단계로 이루어집니다.
tags객체에서 전체 광고 이벤트 ID와 일치하는 키를 확인합니다. 만약 일치 항목이 발견되면 이벤트 유형 및 연결된ad를 검색합니다.ad_break객체. 이러한 이벤트는progress유형이어야 합니다.전체 광고 이벤트 ID와 일치하는 항목을 찾을 수 없는 경우
tags를 확인하세요. 광고 이벤트 ID의 처음 17자(영문 기준)와 일치하는 키의 객체를 반환합니다. 이벤트 유형 및 연결된ad및ad_break객체를 가져옵니다. 그러면progress이외의 유형의 모든 이벤트가 검색됩니다.가져온 정보를 사용하여 플레이어의 UI를 업데이트합니다. 예를 들어
start또는 첫 번째progress이벤트를 수신하는 경우 플레이어의 탐색을 숨깁니다. 컨트롤을 표시하고 광고 내의 현재 광고 위치를 설명하는 오버레이를 광고 시점(예: 'Ad 1/3')
광고 이벤트 ID의 예
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
예시 태그 객체
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
미디어 인증 핑 보내기
광고 이벤트가 발생할 때마다 미디어 인증 핑을 Ad Manager로 전송해야 합니다.
progress가 아닌 유형이 수신됩니다.
광고 이벤트의 전체 미디어 인증 URL을 생성하려면 전체
광고 이벤트 ID를 스트림 등록의 media_verification_url 값으로 대체합니다.
있습니다.
전체 URL을 포함하여 GET 요청을 실행합니다. 인증 요청이
성공하면 상태 코드 202가 포함된 HTTP 응답이 수신됩니다.
그러지 않으면 HTTP 오류 코드 404이 표시됩니다.
요청 예시(cURL)
curl https://{...}/media/google_5555555555123456789
성공적인 응답의 예
HTTP/1.1 202 Accepted