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 DAI (TRỰC TIẾP).
Dịch vụ: dai.google.com
Tất cả URI dưới đây đều liên quan đến https://dai.google.com
Phương thức: luồng
Phương thức | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
Tạo 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 đề yêu cầu
Tham số | |
---|---|
api‑key |
string Khoá API được cung cấp khi tạo sự kiện phát trực tiếp phải hợp lệ đối 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 vào tiêu đề Uỷ quyền HTTP theo định dạng sau: Authorization: DCLKDAI key="<api-key>" |
Tham số đường dẫn
Tham số | |
---|---|
assetKey |
string Mã sự kiện 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 |
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 khác. |
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 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 tiêu chuẩn Đ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, 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 gặp giá trị nhận dạng nội dung nghe nhìn quảng cáo trong khi phát, hãy đưa ra yêu cầu ngay lập tức bằng cách sử dụng media_verification_url có được từ điểm cuối stream ở trên. Những yêu cầu này không cần thiết đối với luồng báo hiệu phía máy chủ, nơi 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
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 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 của 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 khung "thông tin văn bản do người dùng xác định". Nội dung
trong 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 phải được nối vào URL xác minh quảng cáo trước khi thực hiện 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
sẽ trả về thông tin dùng để tạo giao diện người dùng
quảng cáo. Khô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 thực thể của PodMetadata
.
Cách dùng 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. Điểm truy cập vào dữ liệu là phần tags
. Từ đó, hãy lặp lại qua các thẻ và tìm mục nhập đầu tiên có tên là tiền tố cho mã nội dung nghe nhìn của quảng cáo được tìm thấy trong luồng video. Ví dụ: bạn có thể có một mã nhận dạng nội dung nghe nhìn của 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 google_12345
. Trong trường hợp này, mã này khớp với
mã 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 phù hợp, 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
, còn 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 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, dùng để truy xuất danh sách phát đa biến thể trong HLS hoặc MPD trong DASH. |
hls_master_playlist |
string (KHÔNG DÙNG NỮA) URL của danh sách phát đa biến thể HLS. Thay vào đó, hãy sử dụng "stream_manifest". |
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 được 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. |
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 siêu dữ liệu url hoặc nhịp tim_url. |
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 đồ của 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ủa 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. |
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. Không được ping phân đoạn thẻ có type="progress" đến điểm cuối xác minh nội dung nghe nhìn của 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ã 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. Quảng cáo này 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 đ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
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 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) của 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 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 không bắt buộc trong tính năng Đo lường mở, 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. |
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 gồm tất cả các nút <Extension> 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. |
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. Mã này 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 được 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ã 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 cho dịch vụ Đo lường mở, hỗ trợ việc đo lường khả năng xem và xác minh 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 yêu cầu 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 cần được ứng dụng 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 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 đượ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 cho trang web đăng ký, nơi Mã quảng cáo chung của mẫu quảng cáo đã chọn được liệt kê trong danh mục. |
Quảng cáo đồng hành
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 nút <StaticResource> trong VAST nếu đây là thuộc tính đi kèm của 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 tải và hiển thị. Đối với quảng cáo đồng hành HTML, đây sẽ là đoạn mã HTML xuất hiện dưới dạng đoạn mã đồ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 đồ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 khi 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 kéo dài thời gian hay không. |
ad_parameters |
string Giá trị của nút <AdParameters> trong VAST. |