Ứ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.

Lưu ý quan trọng: Trước khi cân nhắc API này, hãy kiểm tra xem có SDK DAI IMA cho nền tảng mà bạn chọn hay không. Bạn nên sử dụng SDK DAI IMA trên các nền tảng có SDK này. API Phân phát nhóm chỉ được dùng trên các nền tảng không có SDK IMA DAI.

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

{network_code}

Mã mạng Google Ad Manager 360

Tham số nội dung JSON

targeting_parameters

Một đối tượng JSON chứa các tham số nhắm mục tiêu của quảng cáo. Bắt buộc

JSON phản hồi

media_verification_url	URL cơ sở để ping các sự kiện theo dõi lượt phát. URL xác minh nội dung nghe nhìn hoàn chỉnh được tạo bằng cách thêm mã sự kiện quảng cáo vào URL cơ sở này.
metadata_url	URL để yêu cầu siêu dữ liệu của nhóm quảng cáo.
stream_id	Chuỗi dùng để xác định phiên phát trực tuyến hiện tại.
valid_for	Thời gian còn lại cho đến khi phiên phát trực tuyến hiện tại hết hạn, theo định dạng dhms (ngày, giờ, phút, giây). Ví dụ: 2h0m0.000s đại diện cho thời lượng 2 giờ.
valid_until	Thời điểm phiên phát trực tuyến hiện tại hết hạn, dưới dạng chuỗi ngày giờ theo tiêu chuẩn ISO 8601 ở định dạng yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

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.

Mẹo: Các URL được cung cấp trong phản hồi API có thể thay đổi mà không cần thông báo. Do đó, hãy sử dụng các URL được cung cấp trong phản hồi API thay vì tự tạo URL. Điều này giúp đảm bảo rằng mã của bạn tiếp tục hoạt động chính xác khi URL thay đổi.

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:

tags	Một tập hợp các cặp khoá-giá trị chứa tất cả sự kiện quảng cáo xuất hiện trong luồng. Khoá là 17 ký tự đầu tiên của mã sự kiện quảng cáo xuất hiện trong siêu dữ liệu theo thời gian của luồng hoặc trong trường hợp sự kiện thuộc loại progress, mã sự kiện quảng cáo đầy đủ. Mỗi giá trị là một đối tượng chứa các tham số sau: ad Mã nhận dạng của một quảng cáo khớp với một khoá trong đối tượng ads. ad_break_id Mã của một điểm chèn quảng cáo khớp với một khoá trong đối tượng ad_breaks. type Loại sự kiện quảng cáo. Các loại sự kiện quảng cáo bao gồm: start Được kích hoạt ở đầu quảng cáo. firstquartile Được kích hoạt vào cuối tứ phân vị thứ nhất. midpoint Được kích hoạt ở điểm giữa của quảng cáo. thirdquartile Được kích hoạt vào cuối tứ phân vị thứ ba. complete Được kích hoạt ở phần cuối của quảng cáo. progress Được kích hoạt định kỳ trong suốt quảng cáo để thông báo cho ứng dụng rằng một điểm chèn quảng cáo đang phát.
ads	Một tập hợp các cặp khoá-giá trị mô tả tất cả quảng cáo xuất hiện trong luồng. Khoá là mã nhận dạng quảng cáo khớp với các giá trị tìm thấy trong đối tượng tags nêu trên. Mỗi giá trị là một đối tượng chứa các tham số sau: ad_break_id Mã của một điểm chèn quảng cáo khớp với một khoá trong đối tượng ad_breaks. position Vị trí quảng cáo này xuất hiện trong nhóm quảng cáo trong điểm chèn quảng cáo, tính bằng giây dấu phẩy động. duration Thời lượng của quảng cáo tính bằng giây dấu phẩy động. clickthrough_url URL sẽ mở khi người dùng tương tác với quảng cáo này, nếu được hỗ trợ.
ad_breaks	Một tập hợp các cặp khoá-giá trị mô tả tất cả các điểm chèn quảng cáo xuất hiện trong luồng. Khoá là mã điểm chèn quảng cáo khớp với các giá trị tìm thấy trong đối tượng tags và ads nêu trên. Mỗi giá trị là một đối tượng chứa các tham số sau: type Loại điểm chèn quảng cáo. Các loại điểm chèn quảng cáo là pre (trước video), mid (giữa video) và post (sau video). duration Thời lượng của điểm chèn quảng cáo tính bằng giây dấu phẩy động. ads Số lượng quảng cáo trong điểm chèn quảng cáo này.

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.

Mẹo: Bạn không nên gửi sự kiện quảng cáo thuộc loại progress đến Ad Manager. Các sự kiện này nhằm thông báo cho ứng dụng trình phát video của ứng dụng rằng một khoảng nghỉ quảng cáo đang phát trong trường hợp có thể không nhận được sự kiện bắt đầu. Ví dụ: nếu người dùng tua đến một vị trí hoặc bắt đầu phát tại một dấu thời gian cụ thể ở giữa quảng cáo, thì họ sẽ không nhận được sự kiện bắt đầu. Các sự kiện tiến trình được gửi đến Ad Manager sẽ bị loại bỏ, điều này có thể ảnh hưởng tiêu cực đến hiệu suất của ứng dụng.

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