Google DAI 광고 모음 게재 API를 사용하면 자체 동영상 연결을 제어하면서 Google Ads에서 제공하는 서버 측 광고 삽입을 실행할 수 있습니다.
이 가이드에서는 Pod 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 |
광고 타겟팅 매개변수가 포함된 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":{"url":"http://example.com"}}' \
-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 이벤트로 전송됩니다. 각 관련 emsg 상자에는 https://aomedia.org/emsg/ID3 또는 https://developer.apple.com/streaming/emsg-id3의 scheme_id_uri 값과 ID3TXXXgoogle_로 시작하는 message_data 값이 있습니다. 이 message_data 값은 ID3TXXX 접두어 없이 광고 이벤트 ID입니다.
emsg 상자 예시
데이터 구조는 미디어 플레이어 라이브러리에 따라 다를 수 있습니다.
광고 이벤트 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을 생성하려면 전체 광고 이벤트 ID를 스트림 등록 응답의 media_verification_url 값에 추가합니다.
전체 URL을 사용하여 GET 요청을 실행합니다. 인증 요청이 성공하면 상태 코드 202가 포함된 HTTP 응답이 수신됩니다.
그러지 않으면 HTTP 오류 코드 404가 표시됩니다.
요청 예시(cURL)
curl https://{...}/media/google_5555555555123456789
성공적인 응답의 예시
HTTP/1.1 202 Accepted