Ứng dụng trình phát video của ứng dụng cho luồng VOD

API phân phát nhóm DAI của Google cho phép bạn thực hiện chèn quảng cáo phía máy chủ bởi Google Ads trong khi vẫn kiểm soát được việc ghép video của riêng bạn.

Hướng dẫn này cho bạn biết cách tương tác với API phân phát nhóm và đạt được chức năng tương tự với SDK IMA DAI. Đối với các câu hỏi cụ thể về chức năng được hỗ trợ, hãy liên hệ với người quản lý tài khoản của Google.

API phân phát nhóm hỗ trợ các luồng phân phát nhóm ở định dạng HLS hoặc MPEG-DASH phát trực tuyến. Hướng dẫn này tập trung vào các luồng HLS và nêu bật khoá sự khác biệt giữa HLS và MPEG-DASH trong các bước cụ thể.

Để tích hợp API phân phát nhóm vào ứng dụng của bạn cho các luồng VOD, hãy hoàn tất các bước sau:

Gửi yêu cầu đăng ký luồng đến Ad Manager

Gửi yêu cầu POST đến điểm cuối đăng ký luồng. Bạn sẽ lần lượt nhận được Phản hồi JSON chứa mã luồng để gửi đến thao tác đối với tệp kê khai và các điểm cuối của API Phân phát nhóm được liên kết.

Điểm cuối của API

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Tham số đường dẫn

Tham số nội dung JSON

JSON phản hồi

Yêu cầu mẫu (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

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

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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

Phân tích cú pháp phản hồi JSON và lưu trữ các giá trị có liên quan.

Yêu cầu tệp kê khai luồng từ trình điều khiển tệp kê khai

Mỗi trình điều khiển tệp kê khai có một định dạng yêu cầu và phản hồi khác nhau. Thông tin liên hệ nhà cung cấp thiết bị thao tác của bạn để nắm được các yêu cầu cụ thể của họ. Nếu bạn triển khai trình điều khiển tệp kê khai của riêng bạn, hãy đọc trình điều khiển tệp kê khai hướng dẫn này để tìm hiểu các yêu cầu cho thành phần này.

Nói chung, bạn cần chuyển ID luồng được trả về bởi điểm cuối đăng ký ở trên đến trình điều khiển tệp kê khai để trình điều khiển tệp kê khai có thể tạo tệp kê khai dành riêng cho phiên. Trừ phi được nêu rõ trong tệp kê khai của bạn thì phản hồi cho yêu cầu tệp kê khai của bạn là một luồng video chứa cả nội dung và quảng cáo.

Yêu cầu mẫu (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Câu trả lời mẫu (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Phát luồng

Tải tệp kê khai mà bạn nhận được từ máy chủ thao tác tệp kê khai vào một trình phát video và bắt đầu phát.

Yêu cầu siêu dữ liệu nhóm quảng cáo từ Ad Manager

Gửi yêu cầu GET đến metadata_url mà bạn đã nhận được ở bước 1. Chiến dịch này bước phải diễn ra sau khi bạn nhận được tệp kê khai ghép nối từ tệp kê khai trình điều khiển. Đổi lại, bạn sẽ nhận được đối tượng JSON chứa các thông tin sau thông số:

Lưu trữ các giá trị này để liên kết với các sự kiện siêu dữ liệu được tính giờ trong video của bạn luồng.

Yêu cầu mẫu (cURL)

curl https://dai.google.com/.../metadata

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

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Theo dõi các sự kiện quảng cáo

Nghe siêu dữ liệu được tính giờ thông qua các sự kiện quảng cáo được kích hoạt trong luồng âm thanh/video của trình phát video.

Đối với các luồng MPEG-TS, siêu dữ liệu xuất hiện dưới dạng thẻ ID3 v2.3 trong băng tần. Một thẻ siêu dữ liệu có mã nhận dạng TXXX và giá trị bắt đầu bằng chuỗi google_ tiếp theo là một loạt nhân vật. Giá trị này là mã sự kiện quảng cáo.

XXX trong TXXX không phải là phần giữ chỗ. Chuỗi TXXX là mã thẻ ID3 dành riêng cho "văn bản do người dùng xác định".

Thẻ ID3 ví dụ

TXXXgoogle_1234567890123456789

Đối với các luồng MP4, chúng được gửi dưới dạng sự kiện emsg trong băng tần mô phỏng ID3 v2.3 các thẻ. Mỗi hộp tin nhắn điện tử liên quan có giá trị scheme_id_uri là https://aomedia.org/emsg/ID3 hoặc https://developer.apple.com/streaming/emsg-id3 và một giá trị message_data bắt đầu bằng ID3TXXXgoogle_. Giá trị message_data này mà không có Tiền tố ID3TXXX là mã sự kiện quảng cáo.

Hộp tin nhắn điện tử mẫu

Cấu trúc dữ liệu có thể khác nhau, tuỳ thuộc vào thư viện trình phát nội dung đa phương tiện của bạn.

Nếu mã sự kiện quảng cáo là google_1234567890123456789, nội dung phản hồi sẽ có dạng như sau:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Một số thư viện trình phát nội dung đa phương tiện tự động trình bày sự kiện emsg mô phỏng ID3 làm thẻ ID3 gốc. Trong trường hợp này, luồng MP4 trình bày các thẻ ID3 giống hệt nhau dưới dạng MPEG_TS.

Cập nhật giao diện người dùng của ứng dụng trình phát video

Bạn có thể so khớp mỗi mã sự kiện quảng cáo với một khoá trong đối tượng tags ở bước 4. So khớp các giá trị này là quá trình gồm hai bước:

1. Kiểm tra đối tượng tags để tìm khoá khớp với mã sự kiện quảng cáo đầy đủ. Nếu tìm thấy kết quả phù hợp, hãy truy xuất loại sự kiện cùng với ad và Đối tượng ad_break. Các sự kiện này phải có kiểu progress.

   Nếu không tìm thấy kết quả trùng khớp cho mã sự kiện quảng cáo đầy đủ, hãy kiểm tra tags cho một khoá khớp với 17 ký tự đầu tiên của mã sự kiện quảng cáo. Truy xuất loại sự kiện cũng như các đối tượng ad và ad_break đã liên kết. Thao tác này sẽ truy xuất mọi sự kiện có kiểu không phải là progress.

2. Sử dụng thông tin đã truy xuất này để cập nhật giao diện người dùng của trình phát của bạn. Ví dụ: khi bạn nhận được start hoặc sự kiện progress đầu tiên, hãy ẩn lượt tìm kiếm của người chơi kiểm soát và hiển thị lớp phủ mô tả vị trí của quảng cáo hiện tại trong điểm chèn quảng cáo, ví dụ: "Quảng cáo 1/3".

Mã sự kiện quảng cáo mẫu

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Đối tượng thẻ mẫu

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Gửi ping xác minh nội dung nghe nhìn

Phải gửi ping xác minh nội dung nghe nhìn đến Ad Manager mỗi khi có sự kiện quảng cáo có loại khác progress thì sẽ nhận được.

Để tạo URL xác minh nội dung nghe nhìn hoàn chỉnh của một sự kiện quảng cáo, hãy thêm toàn bộ URL mã sự kiện quảng cáo với giá trị media_verification_url từ quá trình đăng ký luồng của bạn.

Hãy gửi yêu cầu GET chứa URL đầy đủ. Nếu yêu cầu xác minh là thành công, bạn sẽ nhận được phản hồi HTTP có mã trạng thái 202. Nếu không, bạn sẽ nhận được mã lỗi HTTP 404.

Yêu cầu mẫu (cURL)

curl https://{...}/media/google_5555555555123456789

Ví dụ về phản hồi thành công

HTTP/1.1 202 Accepted

Tài nguyên khác

• Tài liệu về SDK IMA
• Các kiểu triển khai trình phát DAI so sánh