Ứ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 chèn quảng cáo phía máy chủ do Google Ads cung cấp, đồng thời duy trì quyền kiểm soát 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ự bằng 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 theo giao thức truyền phát HLS hoặc MPEG-DASH. Hướng dẫn này tập trung vào các luồng HLS và nêu bật những điểm khác biệt chính giữa HLS và MPEG-DASH trong các bước cụ thể.

Để tích hợp Pod Serving API 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

Tạo 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 máy chủ thao tác tệp kê khai và các điểm cuối API phân phát Pod liên quan.

Đ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":{"url":"http://example.com"}}' \
     -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, 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ị 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. Hãy liên hệ với nhà cung cấp tay điều khiển để nắm được các yêu cầu cụ thể của họ. Nếu bạn đang triển khai trình điều khiển tệp kê khai của riêng mình, hãy đọc hướng dẫn về trình điều khiển tệp kê khai để hiểu các yêu cầu đối với thành phần này.

Nhìn chung, bạn cần truyền mã luồng do điểm cuối đăng ký ở trên trả về cho trình điều khiển tệp kê khai để tạo tệp kê khai dành riêng cho phiên. Trừ phi trình thao tác tệp kê khai của bạn nêu rõ, 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

Ví dụ về phản hồi (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 trình phát video và bắt đầu phát.

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

Tạo yêu cầu GET đến metadata_url mà bạn nhận được ở bước 1. Bước này phải xảy ra sau khi bạn nhận được tệp kê khai được ghép nối từ trình thao tác tệp kê khai. Đổi lại, bạn sẽ nhận được một đối tượng JSON chứa các tham số sau:

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 theo thời gian trong luồng video.

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

Theo dõi siêu dữ liệu được tính theo thời gian 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 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ỗi thẻ siêu dữ liệu có mã nhận dạng TXXX và giá trị bắt đầu bằng chuỗi google_, theo sau là một loạt ký 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ã nhận dạng thẻ ID3 dành riêng cho "văn bản do người dùng xác định".

Ví dụ về thẻ ID3

TXXXgoogle_1234567890123456789

Đối với các luồng MP4, các sự kiện này được gửi dưới dạng sự kiện emsg trong băng tần mô phỏng thẻ ID3 v2.3. Mỗi hộp emsg có 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à giá trị message_data bắt đầu bằng ID3TXXXgoogle_. Giá trị message_data này (không có tiền tố ID3TXXX) là mã sự kiện quảng cáo.

Hộp thư emsg 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 nghe nhìn của bạn.

Nếu mã sự kiện quảng cáo là google_1234567890123456789, thì 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 nghe nhìn tự động hiển thị các sự kiện emsg mô phỏng thẻ ID3 dưới dạng thẻ ID3 gốc. Trong trường hợp này, các luồng MP4 hiển thị 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

Mỗi mã sự kiện quảng cáo có thể được so khớp với một khoá trong đối tượng tags từ bước 4. Việc so khớp các giá trị này là một quy 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 một kết quả trùng khớp, hãy truy xuất loại sự kiện và các đối tượng ad và ad_break liên quan. Các sự kiện này phải có loại progress.

   Nếu không tìm thấy kết quả phù hợp cho mã sự kiện quảng cáo đầy đủ, hãy kiểm tra đối tượng tags để tìm 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 và các đối tượng ad và ad_break liên quan. Thao tác này sẽ truy xuất tất cả sự kiện có loại khác với progress.

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

Ví dụ về mã sự kiện quảng cáo

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

Ví dụ về đối tượng thẻ

{
  "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

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

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

Tạo một yêu cầu GET bằng URL đầy đủ. Nếu yêu cầu xác minh 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
• So sánh các kiểu triển khai trình phát DAI