동적 광고 삽입 VOD API

동적 광고 삽입 API를 사용하면 DAI를 요청하고 추적할 수 있습니다. 살펴보겠습니다 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 스트림을 생성합니다.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

지정된 콘텐츠 소스 및 동영상 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 선택사항

서버 측 비커닝 스트림을 만들려면 true로 설정합니다. 기본값은 false입니다. 기본 스트림의 추적 클라이언트가 시작하고 서버 측에서 핑됩니다.
Google 타겟팅 매개변수 선택사항 <ph type="x-smartling-placeholder"></ph> 추가 타겟팅 매개변수입니다.
스트림 매개변수 재정의 선택사항 <ph type="x-smartling-placeholder"></ph> 스트림 생성 매개변수의 기본값을 재정의합니다.
HMAC 인증 선택사항 <ph type="x-smartling-placeholder"></ph> HMAC 기반 토큰을 사용하여 인증합니다.

응답 본문

성공하면 응답 본문에 새로운 Stream 서버 측 비커닝 스트림의 경우 이 Stream stream_id 및 stream_manifest 필드만 포함합니다.

개방형 측정

Verifications 필드에는 Open(열기)에 관한 정보가 포함됩니다. 비서버 측 비커닝 스트림 측정 확인 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가 있습니다. 여기에는 messageData 속성이 포함된 “google_”(으)로 시작하는 광고 미디어 ID입니다. 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),
  "skip_metadata": object(SkipMetadata),
}
필드
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)입니다(선택사항).
skip_metadata object(SkipMetadata)

건너뛸 수 있는 광고를 위한 선택적 메타데이터입니다. 설정된 경우 광고가 건너뛸 수 있으며 건너뛰기 UI를 처리하는 방법에 관한 안내가 포함되어 있습니다. 이벤트 추적을 지원합니다

이벤트

Event에는 이벤트 유형과 이벤트의 프레젠테이션 시간이 포함됩니다.
JSON 표현
{
  "time": number,
  "type": string,
}
필드
time number

이 이벤트의 프레젠테이션 시간입니다.
type string

이 이벤트의 유형입니다.

부제목

자막은 동영상 스트림의 사이드카 자막 트랙을 설명합니다. 그것은 저장 두 가지 자막 형식, TTML 및 WebVTT TTMLPath 속성에는 TTML 사이드카 파일에 연결되고 WebVTTPath 속성에도 URL이 WebVTT 사이드카 파일에 추가합니다
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(선택사항)

SkipMetadata

SkipMetadata는 클라이언트가 건너뛸 수 있는 광고의 건너뛰기 이벤트를 처리하는 데 필요한 정보를 제공합니다.
JSON 표현
{
  "offset": number,
  "tracking_url": string,
}
필드
offset number

오프셋은 플레이어가 광고를 재생하는 시간(초)을 나타냅니다. 건너뛰기 버튼이 렌더링될 때까지 기다려야 합니다. VAST에서 제공되지 않으면 생략됩니다.
tracking_url string

TrackingURL에는 건너뛰기 이벤트에서 핑해야 하는 URL이 포함되어 있습니다.

아이콘

아이콘에는 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는 자체 API 프레임워크를 기반으로 하는 확인할 수 있습니다.
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

등록처 웹사이트의 URL을 식별하는 데 사용되는 선택한 광고 소재의 유니버설 광고 ID가 카탈로그화됩니다.

컴패니언

컴패니언에는 표시될 수 있는 컴패니언 광고에 대한 정보가 포함되어 있습니다. 표시됩니다.
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

<StaticResource>의 CreativeType 속성 노드 수의 static 유형의 컴패니언입니다.
height int32

이 컴패니언의 높이(픽셀)입니다.
width int32

이 컴패니언의 픽셀 단위 너비입니다.
resource string

정적 및 iframe 컴패니언의 경우 이 URL이 로드되어 표시됩니다. 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

<AdParameters> 값이 노드입니다.