API VOD 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 DAI luồng video theo yêu cầu (VOD). Các luồng HLS và DASH được hỗ trợ.

Dịch vụ: dai.google.com

Đường dẫn của phương thức stream tương ứng với https://dai.google.com

Phương thức: luồng

Phương thức
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Tạo luồng DAI HLS cho nguồn nội dung và ID video nhất định.

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

Tạo luồng DAI DASH cho nguồn nội dung và mã video nhất định.

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

Tiêu đề yêu cầu

Tham số
api‑key string

Khoá API được cung cấp khi bạn tạo sự kiện phát trực tiếp phải hợp lệ với mạng của nhà xuất bản.

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

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

Tham số đường dẫn

Tham số
content-source string

Mã CMS của luồng.

video-id string

Mã video của luồng.

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:

Tham 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. Theo dõi luồng mặc định do máy khách khởi tạo và được ping từ phía máy chủ.
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 Stream. Đối với 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ở

Trường Verifications chứa thông tin về trạng thái Mở Xác minh đo lường cho các luồng báo hiệu không phải phía máy chủ. Verifications chứa một hoặc nhiều phần tử Verification liệt kê những tài nguyên và siêu dữ liệu bạn cần xác minh hoạt động phát lại mẫu quảng cáo bằng mã đo lường của bên thứ ba. Chỉ hỗ trợ JavaScriptResource. Để biết thêm thông tin, vui lòng xem IAB Tech Lab và thông số kỹ thuật VAST 4.1.

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

Sau khi bạn 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ủa stream điểm cuối. media_verification_url là một đường dẫn tuyệt đối. Yêu cầu xác minh nội dung nghe nhìn là không cần thiết cho các luồng báo hiệu phía máy chủ, nơi 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 {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 thành công nội dung nghe nhìn và tất cả 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 do hết hạn.
  • HTTP/1.1 404 Not Found nếu 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 có một yêu cầu khác đang gửi ping vào lúc này.

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

Giá trị nhận dạng nội dung nghe nhì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 "thông tin văn bản do người dùng xác định" khung hình. Nội dung của khung sẽ không được mã hoá và sẽ 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 phải được nối vào media_verification_url cho mỗi yêu cầu xác minh quảng cáo.

Mã nhận dạng nội dung đa phương tiện của quảng cáo (DASH)

Giá trị nhận dạng nội dung nghe nhìn của quảng cáo sẽ được chèn vào tệp kê khai thông qua việc sử dụng Phần tử EventStream của DASH.

Mỗi EventStream sẽ có một URI mã nhận dạng giao thức là urn:google:dai:2018. Chúng sẽ chứa các sự kiện có thuộc tính messageData chứa mã nhận dạng nội dung nghe nhìn của quảng cáo bắt đầu bằng “google_”. Toàn bộ nội dung của messageData phải được thêm vào media_verification_url cho mỗi quảng cáo yêu cầu xác minh.

Dữ liệu phản hồi

Luồng

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

Giá trị nhận dạng luồng.
total_duration number

Thời lượng phát trực tiếp tính bằng giây.
content_duration number

Thời lượng tính bằng giây của nội dung (không có quảng cáo).
valid_for string

Thời lượng luồng có hiệu lực trong khoảng "00h00m00s" .
valid_until string

Ngày mà luồng có hiệu lực cho đến ngày, ở định dạng RFC 3339.
subtitles [object(Subtitle)]

Danh sách phụ đề. Được bỏ qua nếu trống. Chỉ HLS (Phát trực tuyến dựa trên HTTP).
hls_master_playlist string

(KHÔNG DÙNG NỮA) URL của danh sách phát chính HLS. Sử dụng Stream_manifest. Chỉ HLS (Phát trực tuyến dựa trên HTTP).
stream_manifest string

Tệp kê khai của luồng. Tương ứng với danh sách phát chính trong HLS và MPD trong DASH. Đây là trường duy nhất bên cạnh "stream_id" có trong phản hồi khi tạo một luồng báo hiệu phía máy chủ.
media_verification_url string

URL xác minh nội dung nghe nhìn.
apple_tv object(AppleTV)

Thông tin không bắt buộc dành riêng cho các thiết bị AppleTV. Chỉ HLS (Phát trực tuyến dựa trên HTTP).
ad_breaks [object(AdBreak)]

Danh sách Điểm chèn quảng cáo. Được bỏ qua nếu trống.

AppleTV

AppleTV chứa thông tin dành riêng cho các thiết bị Apple TV.
Biểu diễn dưới dạng JSON
{
  "interstitials_url": string,
}
Trường
interstitials_url string

URL của quảng cáo xen kẽ.

AdBreak

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

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

Vị trí trong luồng mà điểm chèn quảng cáo bắt đầu, tính bằng giây.
duration number

Thời lượng của điểm chèn quảng cáo, tính bằng giây.
ads [object(Ad)]

Danh sách Quảng cáo. Được bỏ qua nếu trống.
Quảng cáo mô tả một quảng cáo trong luồng. Trường này chứa vị trí của quảng cáo trong điểm chèn quảng cáo, thời lượng của quảng cáo và một số siêu dữ liệu tuỳ chọn.
Biểu diễn dưới dạng 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),
}
Trường
seq number

Vị trí của quảng cáo trong điểm chèn quảng cáo.
start number

Vị trí trong luồng mà quảng cáo bắt đầu, tính bằng giây.
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).
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. Được bỏ qua nếu trống.
events [object(Event)]

Danh sách các sự kiện trong quảng cáo.
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.
universal_ad_id object(UniversalAdID)

Mã quảng cáo chung không bắt buộc.
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.
skip_metadata object(SkipMetadata)

Siêu dữ liệu không bắt buộc cho quảng cáo có thể bỏ qua. Nếu được đặt, điều này cho biết quảng cáo có thể bỏ qua và bao gồm hướng dẫn về cách xử lý giao diện người dùng bỏ qua và theo dõi sự kiện.

Sự kiện

Sự kiện chứa loại sự kiện và thời gian trình bày của một sự kiện.
Biểu diễn dưới dạng JSON
{
  "time": number,
  "type": string,
}
Trường
time number

Thời gian trình bày của sự kiện này.
type string

Loại sự kiện này.

Phụ đề

Tiêu đề phụ mô tả bản phụ đề của tệp trợ giúp cho luồng video. Chiến dịch này lưu trữ hai định dạng phụ đề: TTML và WebVTT. Thuộc tính TTMLPath chứa URL vào tệp trợ giúp TTML và thuộc tính WebVTTPath cũng chứa URL vào tệp trợ giúp WebVTT.
Biểu diễn dưới dạng JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Trường
language string

Mã ngôn ngữ, chẳng hạn như "en" hoặc "de".
language_name string

Tên mô tả ngôn ngữ. Công cụ này phân biệt tập hợp cụ thể phụ đề nếu có nhiều bộ phụ đề cho cùng một ngôn ngữ
ttml string

URL không bắt buộc dẫn đến tệp trợ giúp TTML.
webvtt string

URL không bắt buộc đến tệp trợ giúp WebVTT.

SkipMetadata

SkipMetadata cung cấp thông tin cần thiết để khách hàng xử lý các sự kiện bỏ qua cho quảng cáo có thể bỏ qua.
Biểu diễn dưới dạng JSON
{
  "offset": number,
  "tracking_url": string,
}
Trường
offset number

Mức chênh lệch cho biết thời lượng (tính bằng giây) vào quảng cáo mà trình phát sẽ chờ để hiển thị nút bỏ qua. Bỏ qua nếu không được cung cấp trong VAST.
tracking_url string

TrackingURL chứa URL cần được ping trong sự kiện bỏ qua.

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ề tính năng Đ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 đâ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 đồng hành.
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.