동적 광고 삽입 선형 API

동적 광고 삽입 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입니다.
참고: 스트림 저작물 키는 다음 위치에서도 찾을 수 있는 식별자입니다. <ph type="x-smartling-placeholder"></ph> Ad Manager UI를 사용합니다.

요청 본문

요청 본문은 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 필드만 포함합니다.

개방형 측정

DAI API에는 Open Measurement 인증을 위한 정보가 포함되어 있습니다. Verifications 필드 이 필드에는 하나 이상의 값이 포함됩니다. 실행하는 데 필요한 리소스와 메타데이터가 나열된 Verification 요소 서드 파티 측정 코드를 사용하여 광고 소재 재생을 확인합니다. 단 JavaScriptResource만 지원됩니다. 자세한 내용은 IAB Tech Lab 및 VAST 4.1 사양.

방법: 미디어 인증

재생 중에 광고 미디어 식별자를 발견하면 즉시 stream에서 가져온 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)

광고 미디어 식별자가 키를 사용하여 HLS 시간 메타데이터로 인코딩됩니다. TXXX, '사용자 정의 텍스트 정보'용으로 예약됨 있습니다. 이 프레임의 콘텐츠는 암호화되지 않으며 항상 "google_"

프레임의 전체 텍스트 콘텐츠가 광고 인증에 추가되어야 합니다. URL을 표시합니다.

메서드: metadata

metadata_url의 메타데이터 엔드포인트는 광고를 만드는 데 사용된 정보를 반환합니다. 있습니다. 메타데이터 엔드포인트는 서버 측 비커닝 스트림에 사용할 수 없습니다. 여기서 서버가 광고 미디어 인증을 시작할 책임이 있습니다.

메서드
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

스트림의 매니페스트 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)],
}
필드
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

모든 <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는 자체 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> 값이 노드입니다.