API trực tiếp phân phát nhóm Chèn quảng cáo động

API Chèn quảng cáo động cho phép bạn yêu cầu và theo dõi sự kiện phát trực tiếp DAI.

Dịch vụ: dai.google.com

Tất cả URI đều liên quan đến https://dai.google.com.

Phương thức: luồng

Phương thức
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Đăng ký phiên phát trực tiếp phân phát nhóm DAI DAI (Chèn quảng cáo động).

Yêu cầu HTTP

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

Tham số đường dẫn

Thông số
network_code string

Mã mạng Google Ad Manager của nhà xuất bản.

custom_asset_key string

Mã nhận dạng tuỳ chỉnh đã liên kết với sự kiện này trong Google Ad Manager.

Nội dung yêu cầu

Nội dung yêu cầu thuộc loại application/x-www-form-urlencoded và chứa các thông số sau:

Thông số
Tham số nhắm mục tiêu DFP Không bắt buộc Tham số nhắm mục tiêu bổ sung.
Ghi đè thông số luồng Không bắt buộc Ghi đè các giá trị mặc định của thông số tạo luồng.
Xác thực HMAC Không bắt buộc Xác thực bằng mã thông báo dựa trên HMAC.

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một đối tượng Stream mới.

Đo lường mở

API DAI chứa thông tin xác minh Đo lường mở trong Trường Verifications. Trường này chứa một hoặc nhiều Các phần tử Verification liệt kê những tài nguyên và siêu dữ liệu cần thiết để thực thi mã đo lường của bên thứ ba để xác minh việc phát lại mẫu quảng cáo. Chỉ JavaScriptResource được hỗ trợ. Để biết thêm thông tin, vui lòng xem Phòng thí nghiệm công nghệ của IAB và Quy cách VAST 4.1.

Phương pháp: phân đoạn nhóm

Phương thức
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}

Tạo luồng DAI cho mã sự kiện đã cho.

Yêu cầu 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}

Tham số đường dẫn

Thông số
network_code string

Mã mạng Google Ad Manager của nhà xuất bản.

custom_asset_key string

Mã nhận dạng tuỳ chỉnh đã liên kết với sự kiện này trong Google Ad Manager.

pod_id integer

Giá trị nhận dạng dạng số cho điểm chèn quảng cáo hiện tại. Mã nhóm quảng cáo là được chỉ định tăng dần cho mỗi sự kiện, bắt đầu từ 1.
profile_name string

Chiến lược phát hành đĩa đơn tên được yêu cầu Hồ sơ mã hoá DAI trên Google Ad Manager. Hồ sơ mã hoá phải là một trong những hồ sơ mã hoá đã định cấu hình cho sự kiện đã chọn.

segment_number integer

Chỉ mục của phân khúc được yêu cầu trong nhóm quảng cáo hiện tại, bắt đầu từ 0.
segment_format string

Đuôi tệp được liên kết với định dạng phân đoạn được yêu cầu. Các tiện ích được chấp nhận là: ts, mp4, vtt, aac, ac3 hoặc eac3.

Tham số truy vấn

Thông số
stream_id bắt buộc string

Mã luồng của phiên của người dùng hiện tại. Giá trị này được trả về bởi yêu cầu thành công đến điểm cuối stream.
sd required1 integer

Thời lượng của phân đoạn được yêu cầu, tính bằng mili giây.
so tùy chọn

Độ lệch của phân đoạn được yêu cầu trong nhóm quảng cáo, tính bằng mili giây. Nếu bạn bỏ qua tham số so, tham số này sẽ được tính bằng nhân thời lượng phân đoạn với số phân đoạn.
pd bắt buộc2 integer

Thời lượng của nhóm quảng cáo, tính bằng mili giây.
auth-token bắt buộc string

URL được mã hoá, đã ký Mã thông báo HMAC cho nhóm quảng cáo hiện tại.
last tùy chọn boolean

Cho biết phân đoạn cuối cùng trong điểm chèn quảng cáo. Bỏ qua tham số này đối với tất cả mã các phân đoạn khác.
scte35 tùy chọn string

Tín hiệu SCTE-35 được mã hoá dạng Base64 cho điểm chèn quảng cáo này.
cust_params tùy chọn string

Tập hợp các cặp khoá-giá trị, dùng để nhắm mục tiêu theo chiến dịch Ad Manager. Các các cặp phải được biểu thị dưới dạng chuỗi truy vấn được mã hoá url.

Ví dụ:
Thông số
  • phần = sports
  • trang = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Chú thích chân trang

  1. Không bắt buộc phải có sd đối với phân đoạn khởi chạy. ↩
  2. Bạn không bắt buộc phải sử dụng pd cho các sự kiện có quảng cáo không có thời lượng bật điểm chèn quảng cáo. ↩

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ là một đoạn luồng có thể phát khớp với định dạng và tham số xác định trong yêu cầu.

Phương thức: Mẫu giai đoạn nhóm DASH

Phương thức
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Yêu cầu mẫu giai đoạn DASH từ Google Ad Manager. Mẫu này chứa macro mà bạn phải điền bằng thông số luồng của mình. Một lần các macro này được điền, mẫu trở thành khoảng thời gian chèn quảng cáo của bạn và có thể được ghép vào tệp kê khai DASH của bạn.

Yêu cầu HTTP

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

Tham số đường dẫn

Thông số
network_code string

Mã mạng Google Ad Manager của nhà xuất bản.

custom_asset_key string

Mã nhận dạng tuỳ chỉnh đã liên kết với sự kiện này trong Google Ad Manager.

Tham số truy vấn

Thông số
stream_id bắt buộc string

Mã luồng của phiên của người dùng hiện tại. Giá trị này được trả về bởi yêu cầu thành công đến điểm cuối stream.

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một Đối tượng PodTemplateResponse.

Phương thức: xác minh nội dung nghe nhìn

Sau khi gặp giá trị nhận dạng nội dung nghe nhìn của quảng cáo trong khi phát, hãy ngay lập tức yêu cầu bằng media_verification_url có được từ luồng điểm cuối, ở trên. Những yêu cầu này không cần thiết cho tính năng báo hiệu phía máy chủ luồng mà máy chủ bắt đầu xác minh nội dung nghe nhìn.

Các yêu cầu đến điểm cuối media verification không thay đổi giá trị.

Phương thức
media verification GET /{media_verification_url}/{ad_media_id}

Thông báo cho API của một sự kiện xác minh nội dung nghe nhìn.

Yêu cầu HTTP

GET https://{media-verification-url}/{ad-media-id}

Nội dung phản hồi

media verification trả về các phản hồi sau:

  • HTTP/1.1 204 No Content nếu xác minh nội dung nghe nhìn thành công và tất cả các ping đều đã gửi.
  • HTTP/1.1 404 Not Found nếu yêu cầu không thể xác minh nội dung nghe nhìn do định dạng URL không chính xác hoặc URL hết hạn.
  • HTTP/1.1 404 Not Found nếu trước đó có yêu cầu xác minh cho giấy tờ tuỳ thân này đã thành công.
  • HTTP/1.1 409 Conflict nếu một yêu cầu khác đã gửi ping tại địa chỉ này bất cứ lúc nào.

Mã nội dung nghe nhìn của quảng cáo

Giá trị nhận dạng nội dung nghe nhìn của quảng cáo sẽ được mã hoá trong một kênh siêu dữ liệu riêng biệt — theo thời gian siêu dữ liệu cho luồng truyền tải HLS hoặc emsg cho tệp mp4. Giá trị nhận dạng nội dung nghe nhìn của quảng cáo sẽ luôn bắt đầu bằng chuỗi google_.

Toàn bộ nội dung văn bản của mục siêu dữ liệu phải được nối vào quảng cáo URL xác minh trước khi thực hiện mỗi yêu cầu xác minh quảng cáo.

Phương thức: siêu dữ liệu

Điểm cuối siêu dữ liệu tại metadata_url sẽ trả về thông tin dùng để tạo quảng cáo Giao diện người dùng. Không dùng được điểm cuối siêu dữ liệu cho các luồng báo hiệu phía máy chủ, nơi máy chủ chịu trách nhiệm bắt đầu quy trình xác minh nội dung nghe nhìn quảng cáo.

Phương thức
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Truy xuất thông tin siêu dữ liệu quảng cáo.

Yêu cầu HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Nội dung phản hồi

Nếu thành công, phản hồi sẽ trả về một phiên bản của PodMetadata.

Phân tích cú pháp siêu dữ liệu

Siêu dữ liệu có ba phần riêng biệt: tags, ads và breaks quảng cáo. Mục nhập trỏ vào dữ liệu là phần tags. Từ đó, hãy lặp lại các thẻ và tìm mục nhập đầu tiên có tên là tiền tố cho mã nhận dạng nội dung nghe nhìn của quảng cáo trong luồng video. Ví dụ: bạn có thể có ID phương tiện quảng cáo như sau:

google_1234567890

Sau đó, bạn sẽ thấy một đối tượng thẻ có tên google_12345. Trong trường hợp này, URL khớp với id phương tiện quảng cáo. Sau khi tìm thấy đúng đối tượng tiền tố nội dung nghe nhìn quảng cáo, bạn có thể tra cứu mã quảng cáo, mã điểm chèn quảng cáo và loại sự kiện. Sau đó, mã quảng cáo được dùng để lập chỉ mục Các đối tượng ads và mã điểm chèn quảng cáo được dùng để lập chỉ mục các đối tượng breaks.

Dữ liệu phản hồi

Luồng

Luồng dùng để hiển thị danh sách tài nguyên cho một luồng mới được tạo trong Định dạng JSON.
Biểu diễn dưới dạng 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,
}
Trường
stream_id string

Giá trị nhận dạng luồng GAM.
media_verification_url string

URL xác minh nội dung nghe nhìn được dùng làm điểm cuối cơ sở để theo dõi các sự kiện phát.
metadata_url string

URL siêu dữ liệu dùng để thăm dò thông tin định kỳ về các sự kiện quảng cáo trong luồng phát sắp tới.
session_update_url string

URL cập nhật của phiên được dùng để cập nhật các thông số nhắm mục tiêu cho luồng này. Các giá trị ban đầu cho các thông số nhắm mục tiêu sẽ được thu thập trong yêu cầu tạo luồng ban đầu.
heartbeat_url string

URL nhịp tim, được dùng để duy trì hoạt động truyền phát tín hiệu báo hiệu phía máy chủ, nó phải được ping mỗi {PollingFrequency} giây một lần. Được điền sẵn cho các luồng báo hiệu phía máy chủ.
polling_frequency number

Tần suất thăm dò ý kiến (tính bằng giây) khi yêu cầu siêu dữ liệu_url hoặc đẩy nhịp tim_url.
pod_manifest_url string

Mẫu URL của tệp kê khai nhóm được dùng để tạo URL nhằm truy xuất tệp kê khai nhóm của luồng, tương ứng với URL của danh sách phát đa biến thể trong HLS hoặc MPD trong DASH. Điền cho các sự kiện phát trực tiếp thuộc loại Chèn quảng cáo động POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Định dạng tệp kê khai là định dạng của tệp kê khai được truy xuất từ pod_manifest_url, dấu gạch ngang hoặc hls.

PodMetadata

PodMetadata chứa thông tin siêu dữ liệu về quảng cáo, điểm chèn quảng cáo và thẻ ID phương tiện.
Biểu diễn dưới dạng JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
Trường
tags map[string, object(TagSegment)]

Bản đồ của các phân khúc thẻ được lập chỉ mục theo tiền tố thẻ.
ads map[string, object(Ad)]

Bản đồ quảng cáo mà mã quảng cáo đã lập chỉ mục.
ad_breaks map[string, object(AdBreak)]

Sơ đồ điểm chèn quảng cáo được lập chỉ mục theo mã điểm chèn quảng cáo.

TagSegment

Tag Segment chứa thông tin tham chiếu đến một quảng cáo, điểm chèn quảng cáo và loại sự kiện. Phân đoạn thẻ với type="progress" không được ping đến phương tiện quảng cáo điểm cuối xác minh.
Biểu diễn dưới dạng JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Trường
ad string

Mã quảng cáo của thẻ này.
ad_break_id string

Mã điểm chèn quảng cáo của thẻ này.
type string

Loại sự kiện của thẻ này.

AdBreak

AdBreak mô tả một điểm chèn quảng cáo duy nhất trong luồng. Thông số này có một thời lượng, loại (giữa/trước/sau) và số lượng quảng cáo.
Biểu diễn dưới dạng JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Trường
type string

Các loại điểm chèn hợp lệ là: trước, giữa và sau.
duration number

Tổng thời lượng quảng cáo cho điểm chèn quảng cáo này, tính bằng giây.
expected_duration number

Thời lượng dự kiến của điểm chèn quảng cáo (tính bằng giây), bao gồm tất cả quảng cáo và bất kỳ phương tiện chặn nào.
ads number

Số lượng quảng cáo trong điểm chèn quảng cáo.
Quảng cáo mô tả một quảng cáo trong luồng.
Biểu diễn dưới dạng 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),
}
Trường
ad_break_id string

Mã điểm chèn quảng cáo của quảng cáo này.
position number

Vị trí của quảng cáo này trong điểm chèn quảng cáo, bắt đầu từ 1.
duration number

Thời lượng quảng cáo, tính bằng giây.
title string

Tiêu đề không bắt buộc của quảng cáo.
description string

Nội dung mô tả (không bắt buộc) của quảng cáo.
advertiser string

Mã nhận dạng nhà quảng cáo (không bắt buộc).
ad_system string

Hệ thống quảng cáo không bắt buộc.
ad_id string

Mã quảng cáo không bắt buộc.
creative_id string

Mã mẫu quảng cáo không bắt buộc.
creative_ad_id string

Mã quảng cáo của mẫu quảng cáo không bắt buộc.
deal_id string

Mã giao dịch không bắt buộc.
clickthrough_url string

URL của trang đích khi nhấp (không bắt buộc).
click_tracking_urls string

URL theo dõi lượt nhấp không bắt buộc.
verifications [object(Verification)]

Các mục nhập xác minh tiêu chuẩn Đo lường mở (không bắt buộc) liệt kê các tài nguyên và siêu dữ liệu cần thiết để thực thi mã đo lường của bên thứ ba nhằm xác minh phát mẫu quảng cáo.
slate boolean

Bool không bắt buộc cho biết mục nhập hiện tại là phương tiện chặn.
icons [object(Icon)]

Danh sách biểu tượng, sẽ bị bỏ qua nếu trống.
wrappers [object(Wrapper)]

Danh sách trình bao bọc, bỏ qua nếu trống.
universal_ad_id object(UniversalAdID)

Mã quảng cáo chung không bắt buộc.
extensions string

Danh sách không bắt buộc của tất cả <Extension> nút trong VAST.
companions [object(Companion)]

Quảng cáo đồng hành (không bắt buộc) có thể xuất hiện cùng với quảng cáo này.
interactive_file object(InteractiveFile)

Mẫu quảng cáo tương tác không bắt buộc (SIMID) sẽ hiển thị trong khi phát quảng cáo.

PodTemplateResponse

PodTemplateResponse biểu thị tải trọng JSON được trả về VTP để ghép nhóm.
Biểu diễn dưới dạng JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Trường
dash_period_template string

DashPeriodTemplate là mẫu xml cho khoảng thời gian cần điền dữ liệu thích hợp trước khi ghép.
segment_duration_ms int64

SegmentDurationMS là thời lượng của các phân đoạn khoảng thời gian tính bằng mili giây.

Biểu tượng

Biểu tượng chứa thông tin về một biểu tượng VAST.
Biểu diễn dưới dạng 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,
}
Trường
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 chứa thông tin về lượt nhấp vào biểu tượng.
Biểu diễn dưới dạng JSON
{
  "url": string,
}
Trường
url string

FallbackImage

FallbackImage chứa thông tin về hình ảnh dự phòng VAST.
Biểu diễn dưới dạng JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Trường
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Trình bao bọc chứa thông tin về một quảng cáo trình bao bọc. Không bao gồm Mã giao dịch nếu không tồn tại.
Biểu diễn dưới dạng JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Trường
system string

Giá trị nhận dạng hệ thống quảng cáo.
ad_id string

Mã quảng cáo dùng cho quảng cáo trình bao bọc.
creative_id string

Mã mẫu quảng cáo dùng cho quảng cáo trình bao bọc.
creative_ad_id string

Mã quảng cáo mẫu quảng cáo dùng cho quảng cáo trình bao bọc.
deal_id string

Mã giao dịch không bắt buộc cho quảng cáo trình bao bọc.

Xác minh

Quy trình xác minh chứa thông tin về giải pháp Đo lường mở, hỗ trợ đo lường xác minh và khả năng xem của bên thứ ba. Hiện tại, chúng tôi chỉ hỗ trợ các tài nguyên JavaScript. Hãy tham khảo tại https://iabtechlab.com/standards/open-measurement-sdk/
Biểu diễn dưới dạng JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Trường
vendor string

Nhà cung cấp dịch vụ xác minh.
java_script_resources [object(JavaScriptResource)]

Danh sách các tài nguyên JavaScript để xác minh.
tracking_events [object(TrackingEvent)]

Danh sách các sự kiện theo dõi để xác minh.
parameters string

Một chuỗi mờ được truyền đến mã xác minh Tự khởi động.

JavaScriptResource

JavaScriptResource chứa thông tin xác minh qua JavaScript.
Biểu diễn dưới dạng JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Trường
script_url string

URI đến tải trọng JavaScript.
api_framework string

APIFramework là tên của khung video thực hiện mã xác minh.
browser_optional boolean

Liệu tập lệnh này có thể chạy bên ngoài một .

TrackingEvent

TrackingEvent chứa các URL cần được khách hàng ping trong một số ngoại lệ.
Biểu diễn dưới dạng JSON
{
  "event": string,
  "uri": string,
}
Trường
event string

Loại sự kiện theo dõi.
uri string

Sự kiện theo dõi cần được ping.

UniversalAdID

UniversalAdID dùng để cung cấp một giá trị nhận dạng mẫu quảng cáo duy nhất duy trì trên các hệ thống quảng cáo.
Biểu diễn dưới dạng JSON
{
  "id_value": string,
  "id_registry": string,
}
Trường
id_value string

Mã quảng cáo chung của mẫu quảng cáo đã chọn cho quảng cáo.
id_registry string

Một chuỗi được dùng để xác định URL cho trang web của sổ đăng ký nơi mã quảng cáo toàn cầu của mẫu quảng cáo đã chọn đã được lập danh mục.

Companion

Quảng cáo đồng hành chứa thông tin về quảng cáo đồng hành có thể hiển thị cùng với quảng cáo.
Biểu diễn dưới dạng 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)],
}
Trường
click_data object(ClickData)

Dữ liệu về lượt nhấp cho quảng cáo đồng hành này.
creative_type string

Thuộc tính CreativeType trên <StaticResource> nút trong VAST nếu thì đây là tệp đồng hành thuộc loại tĩnh.
height int32

Chiều cao tính bằng pixel của quảng cáo đồng hành này.
width int32

Chiều rộng tính bằng pixel của quảng cáo đồng hành này.
resource string

Đối với quảng cáo đồng hành tĩnh và iframe, đây sẽ là URL cần được tải và được hiển thị. Đối với quảng cáo đồng hành HTML, đây sẽ là đoạn mã HTML nên sẽ xuất hiện dưới dạng giá trị đi kèm.
type string

Loại của quảng cáo đồng hành này. Đó có thể là tĩnh, iframe hoặc HTML.
ad_slot_id string

Mã vị trí cho quảng cáo đồng hành này.
api_framework string

Khung API cho đồng hành này.
tracking_events [object(TrackingEvent)]

Danh sách các sự kiện theo dõi cho quảng cáo đồng hành này.

InteractiveFile

InteractiveFile chứa thông tin cho quảng cáo tương tác (ví dụ: SIMID) sẽ được hiển thị trong khi phát lại quảng cáo.
Biểu diễn dưới dạng JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Trường
resource string

URL đến mẫu quảng cáo tương tác.
type string

Loại MIME của tệp được cung cấp dưới dạng tài nguyên.
variable_duration boolean

Liệu mẫu quảng cáo này có thể yêu cầu kéo dài thời lượng hay không.
ad_parameters string

Giá trị của <AdParameters> nút trong VAST.