API DAI đang ở giai đoạn thử nghiệm và có thể không có sẵn trong mạng của bạn. Vui lòng liên hệ với người quản lý tài khoản của bạn để biết thêm thông tin. Bạn nên sử dụng SDK IMA cho các nền tảng có sẵn SDK này.

Trang này được dịch bởi Cloud Translation API.

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 các luồng video theo yêu cầu (VOD) của DAI. Hỗ trợ luồng HLS và DASH.

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

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à mã video đã cho. `POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream` Tạo luồng DASH DAI cho nguồn nội dung và mã video đã cho.

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à mã video đã cho.

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

Tạo luồng DASH DAI 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 đề yêu cầu

Thông số

Thông số
`api‑key`	`string` Khoá API được cung cấp khi tạo luồng phải hợp lệ cho mạng của nhà xuất bản. Thay vì cung cấp khoá API trong phần 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>"

api‑key

string

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

Thay vì cung cấp khoá API trong phần 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ố
`content-source`	`string` Mã CMS của luồng.
`video-id`	`string` Mã video của sự kiện phát trực tiếp.

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 luồng beacon phía máy chủ. Giá trị mặc định là `false`. Tính năng theo dõi của luồng mặc định là do ứng dụng khởi tạo và được ping ở phía máy chủ.
Thông số nhắm mục tiêu DFP	Không bắt buộ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 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 luồng beacon 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 tính năng Đo lường mở cho các luồng không phát đi beacon phía máy chủ. Verifications 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 mà 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ợ 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 quảng cáo trong khi phát, hãy tạo ngay một yêu cầu 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 beacon phía máy chủ, trong đó máy chủ sẽ 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 là idempotent.

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 {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 đó đối với 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 ping tại thời điểm này.

Mã nội dung nghe nhìn 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 của 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à 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ã nội dung nghe nhìn 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ó URI mã nhận dạng giao thức là urn:google:dai:2018. Các tệp 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 nghe nhìn của quảng cáo bắt đầu bằng “google_”. Bạn phải thêm toàn bộ nội dung của thuộc tính messageData 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 được dùng để hiển thị danh sách tất cả 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, "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)], }

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` Mã nhận dạng luồng.
`total_duration`	`number` Thời lượng phát trực tuyến tính bằng giây.
`content_duration`	`number` Thời lượng nội dung (không tính 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 mà luồng có hiệu lực, theo định dạng RFC 3339.
`subtitles`	`[object(Subtitle)]` Danh sách Phụ đề. Bỏ qua nếu trống. Chỉ HLS.
`hls_master_playlist`	`string` (KHÔNG CÒN DÙNG NỮA) URL danh sách phát chính HLS. Sử dụng stream_manifest. Chỉ HLS.
`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 ngoài "stream_id" có trong phản hồi khi tạo luồng beacon 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.
`ad_breaks`	`[object(AdBreak)]` Danh sách các Điểm chèn quảng cáo. 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 trong luồng. Tệp này chứa 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 quảng cáo hợp lệ là: giữa, trước và sau.
`start`	`number` Vị trí trong luồng bắt đầu chèn quảng cáo, 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. Bỏ qua nếu trống.

Quảng cáo

Quảng cáo mô tả một quảng cáo trong sự kiện phát trực tiếp. Tệp 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 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), "skip_metadata": object(SkipMetadata), "extensions": [], }

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),
  "extensions": [],
}

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 phát mà quảng cáo bắt đầu, tính bằng giây.
`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` 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ã nhận dạng cho 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, bị bỏ qua nếu trống.
`wrappers`	`[object(Wrapper)]` Danh sách các Trình bao bọ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)]` Mục 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ã nhận dạng cho 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 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, thuộc tính 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à sự kiện theo dõi.
`extensions`	`string` Danh sách không bắt buộc gồm tất cả các nút <Extension> (Tiện ích) trong VAST.

Sự kiện

Sự kiện chứa một 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ụ đề

Subtitle mô tả một kênh phụ đề bên cho luồng video. Tệp này lưu trữ hai định dạng phụ đề: TTML và WebVTT. Thuộc tính TTMLPath chứa URL đến tệp phụ TTML và tương tự, thuộc tính WebVTTPath chứa URL đến tệp phụ 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ữ. Mã này giúp phân biệt bộ phụ đề cụ thể nếu có nhiều bộ phụ đề cho cùng một ngôn ngữ
`ttml`	`string` URL không bắt buộc đến tệp phụ trợ TTML.
`webvtt`	`string` URL không bắt buộc đến tệp phụ trợ WebVTT.

SkipMetadata

SkipMetadata cung cấp thông tin cần thiết để ứng dụ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` Độ lệch cho biết khoảng thời gian tính bằng giây mà người chơi phải chờ để hiển thị nút bỏ qua trong quảng cáo. Bỏ qua nếu không được cung cấp trong VAST.
`tracking_url`	`string` TrackingURL chứa một URL cần được ping trên sự kiện bỏ qua.

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, }

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ề 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 trình bao bọc. Mã 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` Mã nhận dạng hệ thống quảng cáo.
`ad_id`	`string` Mã nhận dạng cho 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 cho tính năng Đo lường mở, giúp hỗ trợ đ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ợ 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 tài nguyên JavaScript để xác minh.
`tracking_events`	`[object(TrackingEvent)]` Danh sách 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 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 đế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 có thể chạy tập lệnh này bên ngoài trình duyệt hay không.

TrackingEvent

TrackingEvent chứa các URL mà ứng dụng phải ping trong một số trường hợp.

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 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ý nơi mã nhận dạng 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

Thuộc tính đồ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)], }

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à tệp đồng hành thuộc loại tĩnh.
`height`	`int32` Chiều cao tính bằng pixel của thành phần đồng hành này.
`width`	`int32` Chiều rộng tính bằng pixel của thành phần đồng hành này.
`resource`	`string` Đối với các thành phần đồng hành tĩnh và iframe, đây sẽ là URL cần 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 của ứng dụng đồng hành này. Đó có thể là nội dung tĩnh, iframe hoặc HTML.
`ad_slot_id`	`string` Mã nhận dạng vị trí cho ứng dụng đồng hành này.
`api_framework`	`string` Khung API cho ứng dụng đồng hành này.
`tracking_events`	`[object(TrackingEvent)]` Danh sách sự kiện theo dõi cho ứng dụng đồ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 gia hạn thời lượng hay không.
`ad_parameters`	`string` Giá trị của nút <AdParameters> trong VAST.