Quản lý sự kiện phát trực tiếp DAI

API DAI của Google cho phép bạn triển khai các luồng được bật DAI của Google trong những môi trường không hỗ trợ việc triển khai IMA SDK. Bạn vẫn nên sử dụng IMA trên những nền tảng có hỗ trợ SDK IMA.

Bạn nên sử dụng DAI API trên các nền tảng sau:

  • Samsung Smart TV (Tizen)
  • TV LG
  • HbbTV
  • Xbox (ứng dụng JavaScript)
  • KaiOS

API này hỗ trợ các chức năng cơ bản do IMA DAI SDK cung cấp. Nếu bạn có câu hỏi cụ thể về khả năng tương thích hoặc các tính năng được hỗ trợ, hãy liên hệ với người quản lý tài khoản của bạn tại Google.

Triển khai API DAI cho sự kiện phát trực tiếp

API DAI hỗ trợ các luồng tuyến tính (TRỰC TIẾP) bằng cả giao thức HLS và DASH. Các bước được mô tả trong hướng dẫn này áp dụng cho cả hai giao thức.

Để tích hợp API này vào ứng dụng cho các sự kiện phát trực tiếp, hãy hoàn tất các bước sau:

1. Yêu cầu phát trực tiếp

Để yêu cầu một sự kiện phát trực tiếp từ DAI API, hãy thực hiện lệnh gọi POST đến điểm cuối của luồng. Phản hồi JSON chứa tệp kê khai luồng phát cũng như các điểm cuối và giá trị API DAI được liên kết.

Nội dung yêu cầu mẫu

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Ví dụ về nội dung phản hồi

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Phản hồi lỗi

Trong trường hợp xảy ra lỗi, các mã lỗi HTTP tiêu chuẩn sẽ được trả về mà không có nội dung phản hồi JSON.

Phân tích cú pháp phản hồi JSON và lưu trữ các giá trị sau:

stream_id
Bạn có thể dùng giá trị này để xác định luồng được trả về.
stream_manifest
URL này được truyền đến trình phát đa phương tiện của bạn để phát trực tuyến.
media_verification_url
URL này là điểm cuối cơ sở để theo dõi các sự kiện phát.
metadata_url
URL này được dùng để thăm dò thông tin định kỳ về các sự kiện phát trực tiếp sắp tới.
session_update_url
URL này dùng để cập nhật các tham số yêu cầu luồng phát được gửi trong yêu cầu luồng phát ban đầu. Xin lưu ý rằng các tham số của yêu cầu này sẽ thay thế tất cả các tham số được đặt cho luồng trước đó.
polling_frequency
Tần suất (tính bằng giây) khi yêu cầu Siêu dữ liệu điểm chèn quảng cáo mới nhất từ DAI API.

2. Lấy thông tin về Siêu dữ liệu điểm chèn quảng cáo mới

Đặt một bộ hẹn giờ để thăm dò Siêu dữ liệu điểm chèn quảng cáo mới ở tần suất thăm dò, bằng cách sử dụng URL siêu dữ liệu. Nếu không được chỉ định trong phản hồi luồng, khoảng thời gian mặc định được đề xuất là 10 giây.

Để tối ưu hoá băng thông, hãy làm như sau:

  1. Tạo yêu cầu GET ban đầu đến điểm cuối metadata_url.
    • Bỏ qua tham số truy vấn delta_token. Quy trình này cho phép máy chủ trả về đầy đủ siêu dữ liệu cho cửa sổ Trình ghi video kỹ thuật số (DVR) của luồng phát. Phần ghi bằng DVR chứa khung thời gian phát sóng mà người xem có thể tua lại và phát. Phản hồi bao gồm một trường đối tượng next_delta_token.
  2. Lưu trữ siêu dữ liệu ở phía máy khách.
  3. Thực hiện các lệnh gọi tiếp theo bằng cách sử dụng giá trị next_delta_token mà phản hồi gần đây nhất trả về. Mỗi phản hồi đều chứa một giá trị next_delta_token. Luôn gửi giá trị mới nhất mà bạn nhận được.
  4. Cập nhật siêu dữ liệu đã lưu trữ để hợp nhất các thay đổi và xoá các điểm chèn quảng cáo không còn dùng nữa.

Đừng cố gắng phân tích cú pháp, tạo hoặc sửa đổi mã thông báo delta. Định dạng của mã thông báo có thể thay đổi. Lưu trữ mã thông báo như đã nhận và truyền mã thông báo đó trở lại mà không thay đổi trong yêu cầu tiếp theo.

Ví dụ về yêu cầu ban đầu

Yêu cầu ban đầu không có tham số truy vấn và trả về toàn bộ siêu dữ liệu:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Ví dụ về yêu cầu tiếp theo

Mỗi yêu cầu tiếp theo sẽ truyền giá trị next_delta_token từ phản hồi trước đó dưới dạng tham số delta_token. Phản hồi chứa những nội dung sau:

  • Quảng cáo
  • Điểm chèn quảng cáo
  • Các thẻ mà máy chủ đã thêm hoặc cập nhật kể từ khi máy chủ phát hành mã thông báo.
  • Một danh sách obsolete_ad_break_ids các điểm chèn quảng cáo cần xoá khỏi siêu dữ liệu đã lưu trữ

Máy chủ bỏ qua những điểm chèn quảng cáo không thay đổi. Ví dụ sau đây cho thấy một cuộc thăm dò ý kiến tiếp theo bằng cách sử dụng mã thông báo delta để chỉ tìm nạp những thay đổi gần đây này:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Nếu thành công, bạn sẽ thấy kết quả tương tự như sau:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Theo dõi các sự kiện ID3 và sự kiện phát

Để xác minh rằng các sự kiện cụ thể đã xảy ra trong một luồng video, hãy làm theo các bước sau để xử lý các sự kiện ID3:

  1. Lưu trữ các sự kiện về nội dung nghe nhìn trong một hàng đợi, lưu từng mã nhận dạng nội dung nghe nhìn cùng với dấu thời gian (nếu trình phát hiển thị).
  2. Mỗi lần cập nhật từ trình phát hoặc theo tần suất đã đặt (nên dùng 500 mili giây), hãy kiểm tra hàng đợi sự kiện đa phương tiện để biết các sự kiện đã phát gần đây bằng cách so sánh dấu thời gian của sự kiện với con trỏ vị trí.
  3. Đối với những sự kiện về nội dung nghe nhìn mà bạn xác nhận là đã phát, hãy kiểm tra loại bằng cách tra cứu mã nhận dạng nội dung nghe nhìn trong các thẻ ngắt quảng cáo đã lưu trữ. Xin lưu ý rằng các thẻ được lưu trữ chỉ chứa tiền tố của mã nhận dạng nội dung nghe nhìn, vì vậy, bạn không thể tìm thấy kết quả khớp chính xác.
  4. Vì ứng dụng trình phát video của bạn định kỳ thăm dò URL siêu dữ liệu, nên có thể xảy ra độ trễ giữa thời điểm trình phát video gặp thẻ ID3 trong luồng và thời điểm siêu dữ liệu liên kết có sẵn. Nếu không tìm thấy thẻ ID3 trong các thẻ đã lưu trữ, hãy giữ thẻ trong hàng đợi và xử lý lại thẻ sau lần thăm dò siêu dữ liệu tiếp theo. Giữ sự kiện trong hàng đợi cho đến khi quá trình xử lý hoàn tất.
  5. Sau khi bạn tìm thấy thẻ trong siêu dữ liệu, hãy kiểm tra trường type của thẻ dựa trên các loại sự kiện quảng cáo được liệt kê trong phần sau. Để theo dõi xem trình phát video có đang phát một khoảng thời gian quảng cáo hay không, hãy sử dụng các sự kiện có giá trị progress trong trường type. Đừng gửi những sự kiện này đến điểm cuối xác minh nội dung nghe nhìn. Đối với tất cả các loại sự kiện khác, hãy thêm mã nhận dạng nội dung nghe nhìn vào điểm cuối xác minh nội dung nghe nhìn và đưa ra yêu cầu GET để theo dõi hoạt động phát.
  6. Xoá sự kiện nội dung nghe nhìn khỏi hàng đợi.

Loại sự kiện quảng cáo

Mỗi thẻ trong đối tượng siêu dữ liệu tags có một trong các loại sự kiện sau:

Loại sự kiện Mô tả
start Chạy ở phần đầu của quảng cáo.
firstquartile Chạy vào cuối phần tư đầu tiên của quảng cáo.
midpoint Chạy ở điểm giữa của quảng cáo.
thirdquartile Chạy ở cuối phần tư thứ ba của quảng cáo.
complete Chạy ở cuối quảng cáo.
progress Chạy định kỳ trong điểm chèn quảng cáo để báo hiệu rằng điểm chèn quảng cáo đang phát. Đừng gửi những sự kiện này đến điểm cuối xác minh nội dung nghe nhìn.

Ví dụ về yêu cầu

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Câu trả lời mẫu

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Bạn có thể xác minh các sự kiện theo dõi trong Trình giám sát hoạt động phát trực tiếp.

4. Cập nhật thông số phiên phát trực tiếp

Bạn có thể muốn điều chỉnh các thông số phiên sau khi tạo một luồng. Để làm việc này, hãy gửi yêu cầu đến URL cập nhật phiên.

Nội dung yêu cầu mẫu

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Ví dụ về nội dung phản hồi

Successful response would be to look for - HTTP/1.1 200

Các điểm hạn chế

Nếu sử dụng API trong webview, bạn phải tuân thủ các hạn chế sau đây liên quan đến việc nhắm mục tiêu:

  • UserAgent: Tham số tác nhân người dùng được truyền dưới dạng giá trị cụ thể của trình duyệt thay vì nền tảng cơ bản.
  • rdid, idtype, is_lat: Mã nhận dạng thiết bị không được truyền đúng cách, điều này hạn chế khả năng của các tính năng sau:
    • Giới hạn tần suất
    • Xoay vòng quảng cáo tuần tự
    • Chia phân khúc đối tượng và nhắm mục tiêu

Các phương pháp hay nhất

Xin lưu ý rằng điểm cuối siêu dữ liệu cho chỉ mục sự kiện phát trực tiếp dựa trên tiền tố của thẻ ID3 tương ứng. Đây là một thiết kế nhằm ngăn việc sử dụng điểm cuối siêu dữ liệu để ping ngay tất cả các nút xác minh.

Tài nguyên khác