동적 광고 삽입 선형 API

동적 광고 삽입 API를 사용하면 DAI 선형 (라이브) 스트림을 요청하고 추적할 수 있습니다.

서비스: dai.google.com

모든 URI는 https://dai.google.com을 기준으로 합니다.

메서드: stream

메서드
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입니다.
참고: 스트림 애셋 키는 Ad Manager UI에서도 찾을 수 있는 식별자입니다.

요청 본문

요청 본문은 application/x-www-form-urlencoded 유형이며 다음 매개변수를 포함합니다.

매개변수
dai-ssb 선택사항

서버 측 비콘 스트림을 만들려면 true로 설정합니다. 기본값은 false입니다. 기본 스트림의 추적은 클라이언트에서 시작되고 서버 측에서 핑됩니다.
DFP 타겟팅 매개변수 선택사항 추가 타겟팅 매개변수입니다.
스트림 매개변수 재정의 선택사항 스트림 생성 매개변수의 기본값을 재정의합니다.
HMAC 인증 선택사항 HMAC 기반 토큰을 사용하여 인증합니다.

응답 본문

성공한 경우 응답 본문에 새 Stream이 포함됩니다. 서버 측 비콘 스트림의 경우 이 Stream에는 stream_id 및 stream_manifest 필드만 포함됩니다.

Open Measurement

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
  • 잘못된 URL 형식 또는 만료로 인해 요청에서 미디어를 확인할 수 없는 경우 HTTP/1.1 404 Not Found
  • HTTP/1.1 404 Not Found 이 ID에 대한 이전 인증 요청이 성공한 경우
  • HTTP/1.1 409 Conflict 다른 요청이 현재 핑을 전송하고 있는 경우

광고 미디어 ID (HLS)

광고 미디어 식별자는 '사용자 정의 텍스트 정보' 프레임용으로 예약된 키 TXXX를 사용하여 HLS Timed Metadata에 인코딩됩니다. 프레임의 콘텐츠는 암호화되지 않으며 항상 "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}

쿼리 매개변수

매개변수
delta_token 선택사항 string

클라이언트의 현재 동기화 상태를 나타내는 불투명 토큰입니다. 제공된 경우 서버는 토큰이 생성된 이후 변경된 메타데이터만 응답에 새 next_delta_token와 함께 반환합니다. 생략하면 서버는 전체 DVR 구간의 전체 메타데이터를 반환합니다.

응답 본문

성공하면 응답에서 PodMetadata 인스턴스를 반환합니다.

메타데이터 작업

메타데이터에는 tags, ads, 광고 breaks의 세 가지 개별 섹션이 있습니다. 데이터의 진입점은 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

스트림의 매니페스트 URL입니다. HLS의 다중 변형 재생목록이나 DASH의 MPD를 가져오는 데 사용됩니다.
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

metadata_url 또는 heartbeat_url을 요청할 때의 폴링 빈도(초)입니다.

PodMetadata

PodMetadata에는 광고, 광고 시점, 미디어 ID 태그에 관한 메타데이터 정보가 포함되어 있습니다.
JSON 표현
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
필드
tags map[string, object(TagSegment)]

태그 접두사로 색인이 생성된 태그 세그먼트의 맵입니다.
ads map[string, object(Ad)]

광고 ID로 색인이 생성된 광고의 맵입니다.
ad_breaks map[string, object(AdBreak)]

광고 시점 ID로 색인이 생성된 광고 시점의 맵입니다.
next_delta_token string

클라이언트가 다음 폴링에서 사용할 불투명 토큰입니다.
obsolete_ad_break_ids string

지원 중단되어 클라이언트의 캐시에서 삭제해야 하는 광고 시점 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

AdBreak는 스트림의 단일 광고 시점을 설명합니다. 재생 시간, 유형 (미드/프리/포스트), 광고 수를 포함합니다.
JSON 표현
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
필드
type string

유효한 광고 유형은 pre, mid, post입니다.
duration number

이 광고 시간의 총 광고 시간(초)입니다.
expected_duration number

모든 광고와 슬레이트를 포함한 광고 시점의 예상 재생 시간 (초)입니다.
ads number

광고 시점의 광고 수입니다.
Ad는 스트림의 광고를 설명합니다.
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)]

서드 파티 측정 코드를 실행하여 광고 소재 재생을 확인하는 데 필요한 리소스와 메타데이터를 나열하는 선택적 공개 측정 확인 항목
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)입니다.

아이콘

아이콘에는 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는 포함되지 않습니다.
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에는 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> 노드 값입니다.