API Chèn quảng cáo động cho phép bạn yêu cầu và theo dõi các luồng video theo yêu cầu (VOD) trong DAI. 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 dựa trên HLS cho nguồn nội dung và mã video đã cho.
Tạo luồng DAI DASH cho nguồn nội dung và mã video đã cho. |
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 đề của yêu cầu
Tham số | |
---|---|
api‑key |
string Khoá API (được cung cấp khi tạo một luồng) phải hợp lệ cho 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 theo định dạng 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 tham số sau:
Tham số | ||
---|---|---|
dai-ssb |
Không bắt buộc | Đặt thành |
Thông 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
mới. Đối với các luồng có 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 để xác minh tiêu chuẩn Đo lường mở cho các luồng không phải báo hiệu 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 việc phát mẫu quảng cáo bằng mã đo lường của bên thứ ba.
Chỉ hỗ trợ giá trị JavaScriptResource
. Để biết thêm thông tin, vui lòng xem Phòng thí nghiệm công nghệ IAB 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 quá trình phát, hãy thực hiện yêu cầu ngay lập tức bằng cách sử dụng media_verification_url
từ điểm cuối stream
. media_verification_url
là một đường dẫn tuyệt đối.
Bạn không cần yêu cầu xác minh nội dung nghe nhìn cho các luồng báo hiệu phía máy chủ, khi máy chủ bắt đầu xác minh nội dung nghe nhìn.
Các yêu cầu gửi đến điểm cuối media verification
là 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 nội dung nghe nhìn thành công 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 hết hạn.HTTP/1.1 404 Not Found
nếu yêu cầu xác minh trước đó cho mã này thành công.HTTP/1.1 409 Conflict
nếu có một yêu cầu khác đã gửi ping tại thời điểm này.
Mã nhận dạng nội dung đa phương tiện của quảng cáo (HLS)
Giá trị nhận dạng nội dung đa phương tiện của quảng cáo sẽ được mã hoá trong Siêu dữ liệu có thời gian HLS bằng cách sử dụng khoá TXXX
,
dành riêng cho 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à 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 thêm 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 đa phương tiệ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ã giao thức là urn:google:dai:2018
.
Các sự kiện này sẽ chứa các sự kiện có thuộc tính messageData
chứa
mã nhận dạng nội dung đa phương tiện của quảng cáo bắt đầu bằng “google_”
. Toàn bộ nội dung của thuộc tính messageData
phải được thêm vào media_verification_url cho mỗi yêu cầu xác minh
quảng cáo.
Dữ liệu phản hồi
Luồng
Luồng dùng để hiển thị danh sách tất cả tài nguyên cho luồng mới tạo ở đị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 sự kiện phát trực tiếp. |
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 của nội dung (không có quảng cáo) tính bằng giây. |
valid_for |
string Luồng thời lượng hợp lệ ở định dạng "00h00m00s". |
valid_until |
string Ngày có hiệu lực của sự kiện phát trực tiếp ở định dạng RFC 3339. |
subtitles |
[object(Subtitle)] Danh sách phụ đề. Bị 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 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" xuất hiện trong phản hồi khi tạo 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. Bị 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
Điểm chèn quảng cáo mô tả một điểm chèn quảng cáo đơn lẻ trong luồng phát. Thẻ này chứa 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í (tính bằng giây) trong luồng mà điểm chèn quảng cáo bắt đầu. |
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 các Google Ads. Bị bỏ qua nếu trống. |
Quảng cáo
Quảng cáo mô tả một quảng cáo trong luồng. Tệp này chứa vị trí của quảng cáo trong điểm chèn, thời lượng của quảng cáo và một số siêu dữ liệu không bắt buộc.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), } |
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í (tính bằng giây) trong luồng mà quảng cáo sẽ bắt đầu. |
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 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 không bắt buộc dùng cho mẫu quảng cáo. |
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 các 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. |
events |
[object(Event)] Danh sách các sự kiện trong quảng cáo. |
verifications |
[object(Verification)] Mục nhập xác minh Đ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 việc 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 (SIMID) không bắt buộc phải hiển thị trong khi phát quảng cáo. |
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ụ đề
Phụ đề mô tả bản phụ đề phụ cho luồng video. Hộp cát về quyền riêng tư lưu trữ hai định dạng phụ đề: TTML và WebVTT. Thuộc tính TTMLPath chứa URL đến tệp trợ giúp TTML và thuộc tính WebVTTPath chứa một URL tương tự như 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ả của ngôn ngữ. Thuộc tính này phân biệt một nhóm phụ đề cụ thể nếu có nhiều nhóm 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 phụ của WebVTT. |
Biểu tượng
Biểu tượng chứa thông tin về 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 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ề một 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. Giao thức này không bao gồm Mã giao dịch nếu không có.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 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 mẫu quảng cáo 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
Quy trình xác minh chứa thông tin cho chức năng Đo lường mở, hỗ trợ hoạt động đ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. Xem 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 cho quy trình 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 thi 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à ứng dụng 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 một giá trị nhận dạng mẫu quảng cáo duy nhất đượ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 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 dùng để xác định URL của trang web đăng ký, trong đó mã quảng cáo chung của mẫu quảng cáo đã chọn được đưa vào danh mục. |
Quảng cáo đồng hành
Quảng cáo đồng hành chứa thông tin cho 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 nút <StaticResource> trong VAST nếu đây là thuộc tính đồng hành của kiểu 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 tải và hiển thị. Đối với quảng cáo đồng hành HTML, đây sẽ là đoạn mã HTML sẽ xuất hiện 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à tĩnh, iframe hoặc HTML. |
ad_slot_id |
string Mã vùng của quảng cáo đồng hành này. |
api_framework |
string Khung API cho quảng cáo đồ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 về mẫu quảng cáo tương tác (tức là SIMID) sẽ 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 đế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 gia hạn hay không. |
ad_parameters |
string Giá trị của nút <AdParameters> trong VAST. |