Dynamic Ad Insert API를 사용하면 DAI VOD 스트림을 요청하고 추적할 수 있습니다. HLS 및 DASH 스트림이 지원됩니다.
서비스: dai.google.com
stream
메서드의 경로는 https://dai.google.com
를 기준으로 합니다.
메서드: 스트림
방법 | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
지정된 콘텐츠 소스 및 동영상 ID에 대한 HLS DAI 스트림을 생성합니다.
지정된 콘텐츠 소스 및 동영상 ID에 관한 DASH DAI 스트림을 만듭니다. |
HTTP 요청
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
요청 헤더
매개변수 | |
---|---|
api‑key |
string 스트림을 만들 때 제공되는 API 키는 게시자의 네트워크에 대해 유효해야 합니다. API 키는 요청 본문에 제공하는 대신 다음과 같은 형식으로 HTTP 승인 헤더에 전달할 수 있습니다. Authorization: DCLKDAI key="<api-key>" |
경로 매개변수
매개변수 | |
---|---|
content-source |
string 스트림의 CMS ID입니다. |
video-id |
string 스트림의 동영상 ID입니다. |
요청 본문
요청 본문은 application/x-www-form-urlencoded
유형이며 다음 매개변수를 포함합니다.
매개변수 | ||
---|---|---|
dai-ssb |
선택사항 | 서버 측 비커닝 스트림을 만들려면 |
Google 타겟팅 매개변수 | 선택사항 | 추가 타겟팅 매개변수입니다. |
스트림 매개변수 재정의 | 선택사항 | 스트림 생성 매개변수의 기본값을 재정의합니다. |
HMAC 인증 | 선택사항 | HMAC 기반 토큰을 사용하여 인증합니다. |
응답 본문
성공하면 응답 본문에 새로운 Stream
가 포함됩니다. 서버 측 비커닝 스트림의 경우 이 Stream
에는 stream_id
및 stream_manifest
필드만 포함됩니다.
개방형 측정
Verifications
필드에는 서버 측 비커닝 스트림에 대한 Open Measurement 인증에 대한 정보가 포함됩니다.
Verifications
에는 서드 파티 측정 코드로 광고 소재 재생을 확인하는 데 필요한 리소스와 메타데이터가 나열된 하나 이상의 Verification
요소가 포함되어 있습니다.
JavaScriptResource
만 지원됩니다. 자세한 내용은 IAB Tech Lab 및 VAST 4.1 사양을 참고하세요.
방법: 미디어 인증
재생 중에 광고 미디어 식별자를 발견하면 즉시 stream
엔드포인트의 media_verification_url
를 사용하여 요청합니다. media_verification_url
는 절대 경로입니다.
서버가 미디어 인증을 시작하는 서버 측 비커닝 스트림에는 미디어 인증 요청이 필요하지 않습니다.
media verification
엔드포인트에 대한 요청에는 멱등성이 있습니다.
방법 | |
---|---|
media verification |
GET {media_verification_url}/{ad_media_id}
미디어 인증 이벤트를 API에 알립니다. |
HTTP 요청
GET {media-verification-url}/{ad-media-id}
응답 본문
media verification
는 다음 응답을 반환합니다.
- 미디어 인증이 성공하고 모든 핑이 전송되는 경우
HTTP/1.1 204 No Content
입니다. HTTP/1.1 404 Not Found
: 잘못된 URL 형식 또는 만료로 인해 요청에서 미디어를 확인할 수 없는 경우- 이 ID에 대한 이전 인증 요청에 성공한 경우
HTTP/1.1 404 Not Found
입니다. - 현재 다른 요청에서 이미 핑을 전송하고 있는 경우
HTTP/1.1 409 Conflict
입니다.
광고 미디어 ID (HLS)
광고 미디어 식별자는 '사용자 정의 텍스트 정보' 프레임용으로 예약된 TXXX
키를 사용하여 HLS 시간 메타데이터로 인코딩됩니다. 프레임의 콘텐츠는 암호화되지 않으며 항상 "google_"
텍스트로 시작합니다.
프레임의 전체 텍스트 콘텐츠는 각 광고 인증 요청의 media_verification_url에 추가되어야 합니다.
광고 미디어 ID (DASH)
광고 미디어 식별자는 DASH의 EventStream
요소를 통해 매니페스트에 삽입됩니다.
각 EventStream
에는 urn:google:dai:2018
의 스키마 ID URI가 있습니다.
여기에는 “google_”
로 시작하는 광고 미디어 ID가 포함된
messageData
속성이 있는 이벤트가 포함됩니다. messageData
속성의 전체 콘텐츠를 각 광고 인증 요청의 media_verification_url에 추가해야 합니다.
응답 데이터
스트림
스트림은 JSON 형식으로 새로 생성된 스트림에 대한 모든 리소스 목록을 렌더링하는 데 사용됩니다 .JSON 표현 |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
입력란 | |
---|---|
stream_id |
string 스트림 식별자. |
total_duration |
number 스트림 길이(초) |
content_duration |
number 광고 없는 콘텐츠 재생 시간(초)입니다. |
valid_for |
string 시간 스트림은 '00h00m00s' 형식으로 유효합니다. |
valid_until |
string 스트림이 유효한 날짜로, RFC 3339 형식입니다. |
subtitles |
[object(Subtitle)] 자막 목록. 비어 있으면 생략됩니다. HLS만 해당 |
hls_master_playlist |
string (지원 중단됨) HLS 마스터 재생목록 URL. Stream_manifest를 사용합니다. HLS만 해당 |
stream_manifest |
string 스트림의 매니페스트입니다. HLS의 마스터 재생목록과 DASH의 MPD에 해당합니다. 이는 서버 측 비커닝 스트림을 만들 때 응답에 있는 'stream_id' 외의 유일한 필드입니다. |
media_verification_url |
string 미디어 인증 URL |
apple_tv |
object(AppleTV) AppleTV 기기와 관련된 선택적 정보입니다. HLS만 해당 |
ad_breaks |
[object(AdBreak)] 광고 시점 목록. 비어 있으면 생략됩니다. |
AppleTV
AppleTV에는 Apple TV 기기와 관련된 정보가 포함되어 있습니다.JSON 표현 |
---|
{ "interstitials_url": string, } |
입력란 | |
---|---|
interstitials_url |
string 전면 광고 URL |
AdBreak
광고 시점은 스트림의 단일 광고 시점을 설명합니다. 여기에는 위치, 재생 시간, 유형 (중간/전/후) 및 광고 목록이 포함됩니다.JSON 표현 |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
입력란 | |
---|---|
type |
string 유효한 광고 시점 유형은 미드, 프리, 포스트입니다. |
start |
number 스트림에서 브레이크가 시작되는 위치(초)입니다. |
duration |
number 광고 시점 길이(초)입니다. |
ads |
[object(Ad)] 광고 목록. 비어 있으면 생략됩니다. |
광고
광고는 스트림의 광고를 설명합니다. 여기에는 광고 시점의 광고 위치, 광고 길이, 일부 선택적 메타데이터가 포함됩니다.JSON 표현 |
---|
{ "seq": number, "start": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
입력란 | |
---|---|
seq |
number 광고 시점의 광고 위치입니다. |
start |
number 스트림에서 광고가 시작되는 위치(초)입니다. |
duration |
number 광고의 재생 시간(초)입니다. |
title |
string 선택사항인 광고 제목입니다. |
description |
string 광고에 대한 설명입니다(선택사항). |
advertiser |
string 광고주 식별자(선택사항) |
ad_system |
string 선택적 광고 시스템 |
ad_id |
string 선택적 광고 ID |
creative_id |
string 광고 소재 ID(선택사항) |
creative_ad_id |
string 선택적 광고 소재 광고 ID입니다. |
deal_id |
string 거래 ID(선택사항)입니다. |
clickthrough_url |
string 클릭 후 연결 URL(선택사항) |
icons |
[object(Icon)] 아이콘 목록(비어 있으면 생략됨) |
wrappers |
[object(Wrapper)] 래퍼 목록. 비어 있으면 생략됩니다. |
events |
[object(Event)] 광고의 이벤트 목록 |
verifications |
[object(Verification)] 서드 파티 측정 코드를 실행하여 광고 소재 재생을 확인하는 데 필요한 리소스와 메타데이터가 나열된 선택적 Open Measurement 확인 항목 |
universal_ad_id |
object(UniversalAdID) 범용 광고 ID(선택사항) |
companions |
[object(Companion)] 이 광고와 함께 표시될 수 있는 선택적 컴패니언 |
interactive_file |
object(InteractiveFile) 광고를 재생하는 동안 표시되어야 하는 선택적 양방향 광고 소재 (SIMID) |
이벤트
Event에는 이벤트 유형과 이벤트의 프레젠테이션 시간이 포함됩니다.JSON 표현 |
---|
{ "time": number, "type": string, } |
입력란 | |
---|---|
time |
number 이 일정의 프레젠테이션 시간입니다. |
type |
string 이 이벤트의 유형입니다. |
부제목
자막은 동영상 스트림의 사이드카 자막 트랙을 설명합니다. 이 파일에는 TTML 및 WebVTT라는 두 가지 자막 형식이 저장됩니다. TTMLPath 속성에는 TTML 사이드카 파일의 URL이 포함되며, WebVTTPath 속성에는 WebVTT 사이드카 파일의 URL이 포함됩니다.JSON 표현 |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
입력란 | |
---|---|
language |
string 'en' 또는 'de'와 같은 언어 코드입니다. |
language_name |
string 언어를 설명하는 이름입니다. 동일한 언어에 여러 자막 세트가 있는 경우 특정 자막 세트를 구별합니다. |
ttml |
string TTML 사이드카 파일의 URL(선택사항) |
webvtt |
string WebVTT 사이드카 파일의 URL(선택사항) |
icon
아이콘에는 VAST 아이콘에 관한 정보가 포함되어 있습니다.JSON 표현 |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
입력란 | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
ClickData에는 아이콘 클릭연결에 대한 정보가 포함됩니다.JSON 표현 |
---|
{ "url": string, } |
입력란 | |
---|---|
url |
string |
FallbackImage
FallbackImage에는 VAST 대체 이미지에 대한 정보가 포함됩니다.JSON 표현 |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
입력란 | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
래퍼
래퍼에는 래퍼 광고에 대한 정보가 포함됩니다. 거래 ID가 없는 경우에는 거래 ID도 포함되지 않습니다.JSON 표현 |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
입력란 | |
---|---|
system |
string 광고 시스템 식별자 |
ad_id |
string 래퍼 광고에 사용되는 광고 ID |
creative_id |
string 래퍼 광고에 사용되는 광고 소재 ID입니다. |
creative_ad_id |
string 래퍼 광고에 사용되는 광고 소재 광고 ID |
deal_id |
string 래퍼 광고의 거래 ID(선택사항) |
인증
인증에는 서드 파티 조회가능성 및 인증 측정을 용이하게 하는 Open Measurement에 대한 정보가 포함됩니다. 현재는 JavaScript 리소스만 지원됩니다. https://iabtechlab.com/standards/open-measurement-sdk/를 참고하세요.JSON 표현 |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
입력란 | |
---|---|
vendor |
string 인증 공급업체 |
java_script_resources |
[object(JavaScriptResource)] 확인을 위한 JavaScript 리소스 목록입니다. |
tracking_events |
[object(TrackingEvent)] 확인을 위한 추적 이벤트 목록입니다. |
parameters |
string 부트스트랩 인증 코드로 전달된 불투명 문자열입니다. |
JavaScriptResource
JavaScriptResource에는 JavaScript를 통한 확인을 위한 정보가 포함되어 있습니다.JSON 표현 |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
입력란 | |
---|---|
script_url |
string JavaScript 페이로드의 URI입니다. |
api_framework |
string APIFramework는 인증 코드를 실행하는 동영상 프레임워크의 이름입니다. |
browser_optional |
boolean 이 스크립트를 브라우저 외부에서 실행할 수 있는지 여부입니다. |
TrackingEvent
TrackingEvent에는 특정 상황에서 클라이언트가 핑해야 하는 URL이 포함됩니다.JSON 표현 |
---|
{ "event": string, "uri": string, } |
입력란 | |
---|---|
event |
string 추적 이벤트의 유형입니다. |
uri |
string 핑할 추적 이벤트입니다. |
UniversalAdID
UniversalAdID는 여러 광고 시스템에서 유지되는 고유한 광고 소재 식별자를 제공하는 데 사용됩니다.JSON 표현 |
---|
{ "id_value": string, "id_registry": string, } |
입력란 | |
---|---|
id_value |
string 선택한 광고 소재의 범용 광고 ID입니다. |
id_registry |
string 선택한 광고 소재의 범용 광고 ID가 카탈로그화된 레지스트리 웹사이트의 URL을 식별하는 데 사용되는 문자열입니다. |
컴패니언
컴패니언에는 광고와 함께 표시될 수 있는 컴패니언 광고에 관한 정보가 포함됩니다.JSON 표현 |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
입력란 | |
---|---|
click_data |
object(ClickData) 이 컴패니언의 클릭 데이터입니다. |
creative_type |
string 정적 유형의 컴패니언인 경우 VAST의 <StaticResource> 노드에 대한 CreativeType 속성 |
height |
int32 이 컴패니언의 높이(픽셀)입니다. |
width |
int32 이 컴패니언의 너비(픽셀)입니다. |
resource |
string 정적 및 iframe 컴패니언의 경우 로드 및 표시되는 URL입니다. HTML 컴패니언의 경우 컴패니언으로 표시되어야 하는 HTML 스니펫입니다. |
type |
string 이 컴패니언의 유형입니다. 정적, iframe 또는 HTML일 수 있습니다. |
ad_slot_id |
string 이 컴패니언의 슬롯 ID입니다. |
api_framework |
string 이 컴패니언의 API 프레임워크 |
tracking_events |
[object(TrackingEvent)] 이 컴패니언의 추적 이벤트 목록입니다. |
InteractiveFile
InteractiveFile에는 광고를 재생하는 동안 표시되어야 하는 양방향 광고 소재 (SIMID)에 관한 정보가 포함됩니다.JSON 표현 |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
입력란 | |
---|---|
resource |
string 양방향 광고 소재의 URL |
type |
string 리소스로 제공되는 파일의 MIME 유형입니다. |
variable_duration |
boolean 이 광고 소재에서 기간 연장을 요청할 수 있는지 여부입니다. |
ad_parameters |
string VAST의 <AdParameters> 노드 값입니다. |