동적 광고 삽입 API를 사용하면 DAI 선형 (실시간) 스트림을 요청하고 추적할 수 있습니다.
서비스: dai.google.com
아래의 모든 URI는 https://dai.google.com
을 기준으로 합니다.
메서드: 스트림
방법 | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
지정된 이벤트 ID의 DAI 스트림을 생성합니다. |
HTTP 요청
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream
요청 헤더
매개변수 | |
---|---|
api‑key |
string 스트림을 만들 때 제공되는 API 키는 게시자의 네트워크에 대해 유효해야 합니다. API 키는 요청 본문에 제공하는 대신 다음과 같은 형식으로 HTTP 승인 헤더에 전달할 수 있습니다. Authorization: DCLKDAI key="<api-key>" |
경로 매개변수
매개변수 | |
---|---|
assetKey |
string 스트림의 이벤트 ID입니다. |
요청 본문
요청 본문은 application/x-www-form-urlencoded
유형이며 다음 매개변수를 포함합니다.
매개변수 | ||
---|---|---|
dai-ssb |
선택사항 | 서버 측 비커닝 스트림을 만들려면 |
Google 타겟팅 매개변수 | 선택사항 | 추가 타겟팅 매개변수입니다. |
스트림 매개변수 재정의 | 선택사항 | 스트림 생성 매개변수의 기본값을 재정의합니다. |
HMAC 인증 | 선택사항 | HMAC 기반 토큰을 사용하여 인증합니다. |
응답 본문
성공하면 응답 본문에 새로운 Stream
가 포함됩니다. 서버 측 비커닝 스트림의 경우 이 Stream
에는 stream_id
및 stream_manifest
필드만 포함됩니다.
개방형 측정
DAI API에는 Verifications
필드에 Open Measurement 인증 정보가 포함됩니다. 이 필드에는 광고 소재 재생을 확인하기 위해 서드 파티 측정 코드를 실행하는 데 필요한 리소스와 메타데이터가 나열된 Verification
요소가 하나 이상 포함됩니다. JavaScriptResource
만 지원됩니다. 자세한 내용은
IAB Tech Lab 및
VAST 4.1 사양을 참고하세요.
방법: 미디어 인증
재생 중에 광고 미디어 식별자를 발견하면 즉시 위의 스트림 엔드포인트에서 가져온 media_verification_url을 사용하여 요청합니다. 이러한 요청은 서버가 미디어 인증을 시작하는 서버 측 비커닝 스트림에 필요하지 않습니다.
media verification
엔드포인트에 대한 요청에는 멱등성이 있습니다.
방법 | |
---|---|
media verification |
GET /{media_verification_url}/{ad_media_id}
미디어 인증 이벤트를 API에 알립니다. |
HTTP 요청
GET https://{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_"
텍스트로 시작합니다.
각 광고 인증을 요청하기 전에 프레임의 전체 텍스트 콘텐츠를 광고 인증 URL에 추가해야 합니다.
메서드: metadata
metadata_url
의 메타데이터 엔드포인트는 광고 UI를 빌드하는 데 사용되는 정보를 반환합니다. 메타데이터 엔드포인트는 서버가 광고 미디어 확인을 시작해야 하는 서버 측 비커닝 스트림에 사용할 수 없습니다.
방법 | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
광고 메타데이터 정보를 검색합니다. |
HTTP 요청
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
응답 본문
성공하면 응답이 PodMetadata
인스턴스를 반환합니다.
메타데이터 작업
메타데이터에는 tags
, ads
, 광고 breaks
라는 3가지 섹션이 있습니다. 데이터의 진입점은 tags
섹션입니다. 거기에서 태그를 반복하면서 동영상 스트림에서 찾은 광고 미디어 ID의 접두어 이름인 첫 번째 항목을 찾습니다. 예를 들어 다음과 같은 광고 미디어 ID가 있을 수 있습니다.
google_1234567890
그런 다음 google_12345
라는 태그 객체를 찾습니다. 이 경우에는 광고 미디어 ID와 일치합니다. 올바른 광고 미디어 프리픽스 객체를 찾으면
광고 ID, 광고 시점 ID, 이벤트 유형을 찾을 수 있습니다. 그런 다음 광고 ID는 ads
객체의 색인을 생성하는 데 사용되고,
광고 시점 ID는 breaks
객체의 색인을 생성하는 데 사용됩니다.
응답 데이터
스트림
스트림은 새로 생성된 스트림의 리소스 목록을 JSON 형식으로 렌더링하는 데 사용됩니다.JSON 표현 |
---|
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
입력란 | |
---|---|
stream_id |
string GAM 스트림 식별자 |
stream_manifest |
string HLS의 다중 변형 재생목록 또는 DASH의 MPD를 검색하는 데 사용되는 스트림의 매니페스트 URL |
hls_master_playlist |
string (지원 중단됨) HLS 다중 변형 재생목록 URL. 대신 'stream_manifest'를 사용하세요. |
media_verification_url |
string 재생 이벤트 추적을 위한 기본 엔드포인트로 사용되는 미디어 인증 URL |
metadata_url |
string 예정된 스트림 광고 이벤트에 대한 주기적인 정보를 폴링하는 데 사용되는 메타데이터 URL |
session_update_url |
string 이 스트림의 타겟팅 매개변수를 업데이트하는 데 사용되는 세션의 업데이트 URL입니다. 타겟팅 매개변수의 원래 값은 초기 스트림 생성 요청 중에 캡처됩니다. |
polling_frequency |
number 메타데이터_URL 또는 하트비트 URL을 요청할 때의 폴링 빈도(초)입니다. |
PodMetadata
PodMetadata에는 광고, 광고 시점, 미디어 ID 태그에 대한 메타데이터 정보가 포함됩니다.JSON 표현 |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
입력란 | |
---|---|
tags |
map[string, object(TagSegment)] 태그 접두사별로 색인이 생성된 태그 세그먼트의 지도 |
ads |
map[string, object(Ad)] 광고 ID별로 색인이 생성된 광고의 지도 |
ad_breaks |
map[string, object(AdBreak)] 광고 시점 ID로 색인이 생성된 광고 시점의 지도 |
TagSegment
TagSegment에는 광고, 광고 시점 및 이벤트 유형에 대한 참조가 포함됩니다. type="progress"가 있는 TagSegment는 광고 미디어 확인 엔드포인트에 핑하면 안 됩니다.JSON 표현 |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
입력란 | |
---|---|
ad |
string 이 태그의 광고의 ID입니다. |
ad_break_id |
string 이 태그의 광고 시점 ID |
type |
string 이 태그의 이벤트 유형입니다. |
AdBreak
광고 시점은 스트림의 단일 광고 시점을 설명합니다. 여기에는 재생 시간, 유형 (중간/전/후) 및 광고 수가 포함됩니다.JSON 표현 |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
입력란 | |
---|---|
type |
string 유효한 광고 시점 유형은 프리, 미드, 포스트입니다. |
duration |
number 이 광고 시점의 총 광고 길이(초)입니다. |
expected_duration |
number 모든 광고와 슬레이트를 포함한 예상 광고 시간 (초)입니다. |
ads |
number 광고 시점의 광고 수 |
광고
광고는 스트림의 광고를 설명합니다.JSON 표현 |
---|
{ "ad_break_id": string, "position": 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, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
입력란 | |
---|---|
ad_break_id |
string 이 광고의 광고 시점 ID |
position |
number 광고 시점에서 이 광고의 게재순위(1부터 시작) |
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(선택사항) |
click_tracking_urls |
string 클릭 추적 URL(선택사항) |
verifications |
[object(Verification)] 서드 파티 측정 코드를 실행하여 광고 소재 재생을 확인하는 데 필요한 리소스와 메타데이터가 나열된 선택적 Open Measurement 확인 항목 |
slate |
boolean 현재 항목이 슬레이트임을 나타내는 부울(선택사항) |
icons |
[object(Icon)] 아이콘 목록(비어 있으면 생략됨) |
wrappers |
[object(Wrapper)] 래퍼 목록이며 비어 있으면 생략됩니다. |
universal_ad_id |
object(UniversalAdID) 범용 광고 ID(선택사항) |
extensions |
string VAST의 모든 <Extension> 노드의 목록(선택사항) |
companions |
[object(Companion)] 이 광고와 함께 표시될 수 있는 선택적 컴패니언 |
interactive_file |
object(InteractiveFile) 광고를 재생하는 동안 표시되어야 하는 선택적 양방향 광고 소재 (SIMID) |
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> 노드 값입니다. |