라이브 API를 게재하는 동적 광고 삽입 광고 모음

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

서비스: dai.google.com

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

메서드: 스트림

메서드
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

라이브 스트림 세션을 게재하는 DAI DAI 광고 모음을 등록합니다.

HTTP 요청

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

경로 매개변수

매개변수
network_code string

게시자의 Google Ad Manager 네트워크 코드입니다.

custom_asset_key string

Google Ad Manager에서 이 이벤트와 연결된 맞춤 식별자입니다.

요청 본문

요청 본문은 application/x-www-form-urlencoded 유형이며 다음을 포함합니다. 다음과 같습니다.

매개변수
Google 타겟팅 매개변수 선택사항 추가 타겟팅 매개변수입니다.
스트림 매개변수 재정의 선택사항 스트림 생성 매개변수의 기본값을 재정의합니다.
HMAC 인증 선택사항 HMAC 기반 토큰을 사용하여 인증합니다.

응답 본문

요청이 성공하면 응답 본문에 새로운 Stream 객체가 포함됩니다.

개방형 측정

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

메서드: 광고 모음 세그먼트

메서드
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

지정된 이벤트 ID의 DAI 스트림을 생성합니다.

HTTP 요청

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

경로 매개변수

매개변수
network_code string

게시자의 Google Ad Manager 네트워크 코드입니다.

custom_asset_key string

Google Ad Manager에서 이 이벤트와 연결된 맞춤 식별자입니다.

pod_id integer

현재 광고 시점의 숫자 식별자입니다. 광고 모음 ID: 1부터 시작하여 각 이벤트에 점진적으로 할당됩니다.
profile_name string

이 이름 요청된 Google Ad Manager DAI 인코딩 프로필 인코딩 프로필은 다음에 대해 구성된 인코딩 프로필 중 하나여야 합니다. 선택할 수 있습니다.

segment_number integer

현재 광고 모음 내에서 요청된 세그먼트의 색인으로, 0에서 설정합니다.
segment_format string

요청된 세그먼트 형식과 연결된 파일 확장자입니다. 허용되는 확장자는 ts, mp4, vtt, aac, ac3 또는 eac3

쿼리 매개변수

매개변수
stream_id required string

현재 사용자 세션의 스트림 ID입니다. 이 값은 stream 엔드포인트에 요청을 전송합니다.
sd required1 integer

요청된 세그먼트의 길이(밀리초)입니다.
so 선택사항

광고 모음 내 요청된 세그먼트의 오프셋(밀리초)입니다. so 매개변수를 생략하면 다음과 같이 계산됩니다. 세그먼트 길이와 세그먼트 번호를 곱합니다
pd 필수2 integer

광고 모음의 재생 시간(밀리초)입니다.
auth-token required string

서명된 URL 인코딩 HMAC 토큰 확인할 수 있습니다
last 선택사항 boolean

광고 시점의 마지막 세그먼트를 나타냅니다. 모든 항목에서 이 매개변수 생략 확인할 수 있습니다
scte35 선택사항 string

이 광고 시점에 대한 Base64로 인코딩된 SCTE-35signal입니다.
cust_params 선택사항 string

Ad Manager 캠페인 타겟팅에 사용되는 키-값 쌍 세트입니다. 이러한 쌍은 url로 인코딩된 쿼리 문자열로 표현되어야 합니다.

예:
매개변수
  • 섹션 = sports
  • 페이지 = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

각주

  1. sd는 초기화 세그먼트에 필요하지 않습니다. ↩
  2. 재생 시간이 없는 광고가 포함된 이벤트에는 pd가 필요하지 않습니다. 사용할 수 있습니다. ↩

응답 본문

성공한 경우 응답 본문은 다음과 일치하는 재생 가능한 스트림 세그먼트가 됩니다. 형식 및 매개변수가 포함됩니다.

방법: DASH 포드 기간 템플릿

메서드
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Google Ad Manager에 DASH 기간 템플릿을 요청합니다. 이 템플릿 에는 스트림 매개변수로 채워야 하는 매크로가 포함되어 있습니다. 한 번 매크로가 채워지면 템플릿이 광고 기간이 되며 DASH 매니페스트에 연결할 수 있습니다.

HTTP 요청

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

경로 매개변수

매개변수
network_code string

게시자의 Google Ad Manager 네트워크 코드입니다.

custom_asset_key string

Google Ad Manager에서 이 이벤트와 연결된 맞춤 식별자입니다.

쿼리 매개변수

매개변수
stream_id required string

현재 사용자 세션의 스트림 ID입니다. 이 값은 stream 엔드포인트에 요청을 전송합니다.

응답 본문

성공하면 응답 본문에 새로운 PodTemplateResponse 객체

방법: 미디어 인증

재생 중에 광고 미디어 식별자를 발견하면 즉시 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 형식 또는 만료일 수 있습니다.
  • HTTP/1.1 404 Not Found: 이 ID에 대한 이전 인증 요청인 경우 성공했습니다.
  • HTTP/1.1 409 Conflict: 다른 요청이 이 시점에 핑을 이미 전송하고 있는 경우 있습니다.

광고 미디어 ID

광고 미디어 식별자가 별도의 메타데이터 트랙으로 인코딩됩니다. HLS 전송 스트림의 메타데이터, mp4 파일의 경우 emsg 파일. 광고 미디어 식별자 항상 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,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
필드
stream_id string

GAM 스트림 식별자
media_verification_url string

재생 이벤트 추적을 위한 기본 엔드포인트로 사용되는 미디어 확인 URL
metadata_url string

예정된 스트림 광고 이벤트에 대한 주기적인 정보를 폴링하는 데 사용되는 메타데이터 URL
session_update_url string

이 스트림의 타겟팅 매개변수를 업데이트하는 데 사용되는 세션의 업데이트 URL입니다. 타겟팅 매개변수의 원래 값은 초기 스트림 생성 요청 중에 캡처됩니다.
heartbeat_url string

서버 측 비커닝 스트림을 활성 상태로 유지하는 데 사용되는 하트비트 URL {PollingFrequency}초마다 핑해야 합니다. 서버 측 비커닝 스트림의 경우 채워집니다.
polling_frequency number

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

포드 매니페스트 URL 템플릿은 스트림의 포드 매니페스트를 검색하기 위한 URL을 생성하는 데 사용됩니다. HLS의 다중 변형 재생목록 URL 또는 DASH의 MPD에 해당합니다. 동적 광고 삽입 유형 POD_SERVING_MANIFEST의 라이브 스트림 이벤트에 대해 채워집니다. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

매니페스트 형식은 pod_manifest_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)입니다(선택사항).

PodTemplateResponse

PodTemplateResponse는 포드 병합을 위해 VTP로 반환되는 JSON 페이로드를 나타냅니다.
JSON 표현
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
필드
dash_period_template string

DashPeriodTemplate은 병합 전에 적절한 데이터로 기간을 채울 수 있는 xml 템플릿입니다.
segment_duration_ms int64

SegmentDurationMS는 기간 세그먼트의 기간(밀리초 단위)입니다.

아이콘

아이콘에는 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> 값이 노드입니다.