API tuyến tính cho tính năng 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 luồng tuyến tính (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: stream

Phương thức
stream POST /linear/v1/hls/event/{assetKey}/stream

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

Yêu cầu HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

Tiêu đề của yêu cầu

Thông số
api‑key string

Khoá API (được cung cấp khi tạo một luồng phát) phải hợp lệ đối với mạng của nhà xuất bản.

Thay vì cung cấp khoá API trong nội dung yêu cầu, bạn có thể truyền khoá API trong tiêu đề Uỷ quyền HTTP theo định dạng sau:

Authorization: DCLKDAI key="<api-key>"

Tham số đường dẫn

Thông số
assetKey string

Mã sự kiện của luồng.
Lưu ý: Khoá tài sản của luồng phát là một giá trị nhận dạng mà bạn cũng có thể tìm thấy trong Giao diện người dùng 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 tham số sau:

Thông số
dai-ssb Không bắt buộc

Đặt thành true để tạo một luồng báo hiệu phía máy chủ. Giá trị mặc định là false. Hoạt động theo dõi luồng mặc định do ứng dụng khách khởi tạo và được ping ở phía máy chủ.
Tham số nhắm mục tiêu DFP Không bắt buộc Các thông số nhắm mục tiêu bổ sung.
Ghi đè thông số luồng Không bắt buộc Ghi đè giá trị mặc định của một tham 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 Stream mới. Đối với các luồng báo hiệu phía máy chủ, Stream này chỉ chứa các trường stream_id và stream_manifest.

Đ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 phần tử Verification 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 việc phát mẫu quảng cáo. Chỉ hỗ trợ JavaScriptResource. Để biết thêm thông tin, hãy xem IAB Tech Lab và thông số kỹ thuật VAST 4.1.

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

Sau khi gặp phải một giá trị nhận dạng nội dung đa phương tiện quảng cáo trong quá trình phát, hãy thực hiện ngay một yêu cầu bằng cách sử dụng media_verification_url lấy từ điểm cuối stream. Những yêu cầu này không cần thiết đối với các luồng báo hiệu phía máy chủ, trong đó máy chủ bắt đầu quy trình xác minh nội dung nghe nhìn.

Các yêu cầu đến điểm cuối media verification là các yêu cầu bất biến.

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

Thông báo cho API về 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 verificationtrả về các phản hồi sau:

  • HTTP/1.1 204 No Content nếu quá trình xác minh nội dung nghe nhìn thành công và tất cả các lệnh ping đều được 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 đã hết hạn.
  • HTTP/1.1 404 Not Found nếu một yêu cầu xác minh trước đó 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 đang gửi lệnh ping vào thời điểm này.

Mã nhận dạng nội dung nghe nhìn của quảng cáo (HLS)

Giá trị nhận dạng phương tiện quảng cáo sẽ được mã hoá trong Siêu dữ liệu theo thời gian HLS bằng khoá TXXX, dành riêng cho các khung "thông tin văn bản do người dùng xác định". Nội dung của khung sẽ không được mã hoá và luôn bắt đầu bằng văn bản "google_".

Toàn bộ nội dung văn bản của khung hình phải được thêm vào URL xác minh quảng cáo trước khi đưa ra từng 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 trả về thông tin dùng để tạo giao diện người dùng quảng cáo. Điểm cuối siêu dữ liệu không dùng được cho các luồng báo hiệu phía máy chủ, trong đó 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}

Tham số truy vấn

Thông số
delta_token tùy chọn string

Một mã thông báo mờ đại diện cho trạng thái đồng bộ hoá hiện tại của ứng dụng. Nếu được cung cấp, máy chủ sẽ chỉ trả về siêu dữ liệu đã thay đổi kể từ khi mã thông báo được tạo, cùng với một next_delta_token mới trong phản hồi. Nếu bạn bỏ qua tham số này, máy chủ sẽ trả về toàn bộ siêu dữ liệu cho toàn bộ phần ghi bằng DVR.

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.

Làm việc với siêu dữ liệu

Siêu dữ liệu có 3 phần riêng biệt: tags, ads và breaks. Điểm truy cập 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 phương tiện quảng cáo có trong luồng video. Ví dụ: bạn có thể có một mã nhận dạng phương tiện quảng cáo có dạng như sau:

google_1234567890

Sau đó, bạn sẽ thấy một đối tượng thẻ có tên là google_12345. Trong trường hợp này, mã này khớp với mã nhận dạng phương tiện quảng cáo của bạn. Sau khi tìm thấy đối tượng tiền tố nội dung nghe nhìn quảng cáo chính xác, 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ã nhận dạng quảng cáo được dùng để lập chỉ mục các đối tượng ads và mã nhận dạng khoảng thời gian 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 được dùng để hiển thị danh sách tài nguyên cho một luồng mới tạo ở định dạng JSON.
Biểu diễn dưới dạng 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,
}
Trường
stream_id string

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

URL tệp kê khai của luồng phát, dùng để truy xuất danh sách phát nhiều biến thể trong HLS hoặc MPD trong DASH.
hls_master_playlist string

(KHÔNG CÒN DÙNG NỮA) URL danh sách phát nhiều biến thể HLS. Hãy dùng "stream_manifest" thay thế.
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 dùng để cập nhật các tham số nhắm mục tiêu cho luồng phát này. Các giá trị ban đầu cho tham số nhắm mục tiêu được ghi lại trong yêu cầu tạo luồng ban đầu.
polling_frequency number

Tần suất thăm dò (tính bằng giây) khi yêu cầu metadata_url hoặc heartbeat_url.

PodMetadata

PodMetadata chứa thông tin siêu dữ liệu về quảng cáo, chương trình quảng cáo và thẻ mã nhận dạng nội dung nghe nhì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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Trường
tags map[string, object(TagSegment)]

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

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

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

Một mã thông báo không công khai để ứng dụng sử dụng trong lần thăm dò tiếp theo.
obsolete_ad_break_ids string

Danh sách mã nhận dạng khoảng chèn quảng cáo không còn được dùng và cần được xoá khỏi bộ nhớ đệm của ứng dụng.

TagSegment

TagSegment 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 của quảng cáo đó. Bạn không nên ping TagSegment có type="progress" đến điểm cuối xác minh phương tiện quảng cáo.
Biểu diễn dưới dạng JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Trường
ad string

Mã nhận dạng của quảng cáo trong thẻ này.
ad_break_id string

Mã nhận dạng của điểm chèn quảng cáo trong 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 phát. Nó chứa 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 khoảng nghỉ hợp lệ là: pre, mid và post.
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à mọi nội dung thay thế.
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 phát.
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ã nhận dạng của điểm chèn 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 của 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 về quảng cáo.
advertiser string

Giá trị nhận dạng không bắt buộc của nhà quảng cáo.
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ã nhận dạng 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 xác minh Đo lường mở không bắt buộc 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 dịch vụ đo lường của bên thứ ba nhằm xác minh việc phát quảng cáo.
slate boolean

Giá trị bool không bắt buộc cho biết mục nhập hiện tại là bảng tin.
icons [object(Icon)]

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

Danh sách Trình bao bọc, bị 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ả các nút <Extension> trong VAST.
companions [object(Companion)]

Biểu ngữ đi kèm 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ẽ xuất hiện trong quá trình phát quảng cáo.

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ề một lượt nhấp qua 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ề quảng cáo 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ã nhận dạng quảng cáo dùng cho quảng cáo bao bọc.
creative_id string

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

Mã quảng cáo của mẫu quảng cáo được dùng cho quảng cáo bao bọc.
deal_id string

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

Xác minh

Xác minh chứa thông tin về chức năng Đo lường mở, giúp đo lường khả năng xem và xác minh của bên thứ ba. Hiện tại, chỉ các tài nguyên JavaScript mới được hỗ trợ. Xem 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 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 không rõ ràng được truyền đến mã xác minh khởi động.

JavaScriptResource

JavaScriptResource chứa thông tin để xác minh thông 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 cho 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 trình duyệt hay không.

TrackingEvent

TrackingEvent chứa các URL mà máy khách sẽ ping trong một số trường hợp nhất định.
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 sẽ được ping.

UniversalAdID

UniversalAdID được dùng để cung cấp giá trị nhận dạng riêng biệt của mẫu quảng cáo được 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

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

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

Companion

Companion chứa thông tin về quảng cáo đi kèm có thể xuất hiện 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 lượt nhấp cho quảng cáo đồng hành này.
creative_type string

Thuộc tính CreativeType trên nút <StaticResource> trong VAST nếu đây là một quảng cáo đồ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 các thành phần đi kèm tĩnh và iframe, đây sẽ là URL được tải và hiển thị. Đối với quảng cáo đồng hành HTML, đây sẽ là đoạn mã HTML cần được hiển thị dưới dạng quảng cáo đồng hành.
type string

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

Mã nhận dạng khu vực cho quảng cáo đi kèm này.
api_framework string

Khung API cho ứng dụng đồ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 đi kèm này.

InteractiveFile

InteractiveFile chứa thông tin về mẫu quảng cáo tương tác (tức là SIMID) cần được hiển thị trong quá trình phát 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 của 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 nút <AdParameters> trong VAST.