Google DAI Pod Serving API를 사용하면 자체 동영상 연결을 제어하면서 Google Ads에서 제공하는 서버 측 광고 삽입을 실행할 수 있습니다.
이 가이드에서는 광고 모음 Serving API와 상호작용하고 IMA DAI SDK로 유사한 기능을 실행하는 방법을 설명합니다. 지원되는 기능에 대한 구체적인 질문은 Google 계정 관리자에게 문의하세요.
Pod Serving API는 HLS 또는 MPEG-DASH 스트리밍 프로토콜의 포드 제공 스트림을 지원합니다. 이 가이드에서는 HLS 스트림을 중점적으로 설명하며 특정 단계에서 HLS와 MPEG-DASH의 주요 차이점을 보여줍니다.
VOD 스트림을 위해 Pod Serving API를 앱에 통합하려면 다음 단계를 완료하세요.
Ad Manager에 스트림 등록 요청하기
스트림 등록 엔드포인트에 POST 요청을 합니다. 그러면 매니페스트 조작 서버 및 연결된 Pod Serving API 엔드포인트로 전송할 스트림 ID가 포함된 JSON 응답을 받게 됩니다.
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 객체입니다. 필수 항목 |
응답 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 응답을 파싱하고 관련 값을 저장합니다.
매니페스트 조작기에서 스트림 매니페스트 요청
매니페스트 조작기마다 요청 및 응답 형식이 다릅니다. 구체적인 요구사항을 알아보려면 조작기 제공업체에 문의하세요. 자체 매니페스트 조작기를 구현하는 경우 매니페스트 조작기 가이드를 참고하여 이 구성요소의 요구사항을 알아보세요.
일반적으로 세션별 매니페스트를 빌드하려면 위의 등록 엔드포인트에서 반환된 스트림 ID를 매니페스트 조작기에 전달해야 합니다. 매니페스트 조작기가 명시적으로 명시하지 않는 한 매니페스트 요청에 대한 응답은 콘텐츠와 광고를 모두 포함하는 동영상 스트림입니다.
예시 요청 (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 |
스트림에 표시되는 모든 광고 이벤트를 포함하는 키-값 쌍 세트. 키는 스트림의 시간이 지정된 메타데이터에 표시되는 광고 이벤트 ID의
처음 17자(영문 기준)이거나 progress 유형인 이벤트의 경우
전체 광고 이벤트 ID입니다.
각 값은 다음 매개변수를 포함하는 객체입니다.
|
||||||||||||||||||
ads |
스트림에 표시되는 모든 광고를 설명하는 키-값 쌍 집합입니다. 키는 위에 나열된 tags 객체에 있는 값과 일치하는 광고 ID입니다. 각 값은 다음 매개변수를 포함하는 객체입니다.
|
||||||||||||||||||
ad_breaks |
스트림에 표시되는 모든 광고 시점을 설명하는 키-값 쌍 집합입니다.
키는 위에 나열된 tags 및 ads 객체에 있는 값과 일치하는 광고 시점 ID입니다. 각 값은 다음 매개변수를 포함하는 객체입니다.
|
이러한 값을 저장하여 동영상 스트림 내에서 시간이 지정된 메타데이터 이벤트와 연결합니다.
예시 요청 (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)과 ID3TXXXgoogle_로 시작하는 message_data 값이 있습니다. ID3TXXX 접두사가 없는 이 message_data 값이
광고 이벤트 ID입니다.
이메일 상자 예
데이터 구조는 미디어 플레이어 라이브러리에 따라 다를 수 있습니다.
광고 이벤트 ID가 google_1234567890123456789인 경우 응답은 다음과 같습니다.
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
일부 미디어 플레이어 라이브러리는 ID3 태그를 네이티브 ID3 태그로 에뮬레이션하는 emsg 이벤트를 자동으로 표시합니다. 이 경우 MP4 스트림은 MPEG_TS와 동일한 ID3 태그를 제공합니다.
클라이언트 동영상 플레이어 앱의 UI 업데이트
각 광고 이벤트 ID는 4단계의 tags 객체 키와 일치할 수 있습니다.
이러한 값을 일치시키는 작업은 두 단계로 이루어집니다.
tags객체에서 전체 광고 이벤트 ID와 일치하는 키를 확인합니다. 일치하는 항목이 있으면 이벤트 유형 및 연결된ad및ad_break객체를 검색합니다. 이러한 이벤트는progress유형이어야 합니다.전체 광고 이벤트 ID와 일치하는 항목이 없으면
tags객체에서 광고 이벤트 ID의 처음 17자(영문 기준)와 일치하는 키가 있는지 확인하세요. 이벤트 유형 및 연결된ad및ad_break객체를 검색합니다. 이렇게 하면progress이외의 유형의 모든 이벤트가 검색됩니다.가져온 정보를 사용하여 플레이어의 UI를 업데이트합니다. 예를 들어
start또는 첫 번째progress이벤트를 수신하면 플레이어의 탐색 컨트롤을 숨기고 광고 시점에서 현재 광고의 위치를 설명하는 오버레이를 표시합니다(예: '광고 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"
},
...
}
미디어 확인 핑 전송
progress 이외의 유형의 광고 이벤트가 수신될 때마다
Ad Manager에 미디어 인증 핑을 전송해야 합니다.
광고 이벤트의 전체 미디어 인증 URL을 생성하려면 스트림 등록 응답의 media_verification_url 값에 전체 광고 이벤트 ID를 추가합니다.
전체 URL을 포함하여 GET 요청을 합니다. 인증 요청이 성공하면 상태 코드가 202인 HTTP 응답이 차례로 수신됩니다.
그러지 않으면 HTTP 오류 코드 404이 표시됩니다.
예시 요청 (cURL)
curl https://{...}/media/google_5555555555123456789
성공적인 응답 예
HTTP/1.1 202 Accepted