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: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
경로 매개변수
{network_code} |
Google Ad Manager 360 네트워크 코드 |
{custom_asset} |
Google Ad Manager에서 이 이벤트와 연결된 맞춤 식별자입니다. |
양식으로 인코딩된 본문 매개변수
양식으로 인코딩된 타겟팅 매개변수 의 집합입니다(선택사항).
응답 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 \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
응답 예
{
"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