Ứ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 xem xét API này, hãy kiểm tra xem đã có SDK IMA cho nền tảng mà bạn chọn hay chưa. Bạn nên sử dụng SDK IMA DAI trên các nền tảng có sẵn SDK này. API phân phát nhóm chỉ 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ự với SDK IMA DAI. Nếu bạn 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 trong giao thức truyền trực tuyến 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 theo các bước cụ thể.

Để tích hợp API phân phát nhóm vào ứng dụng cho luồng VOD, hãy hoàn thành 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 một 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 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

{network_code}

Mã mạng Google Ad Manager 360 của bạn

Tham số nội dung JSON

targeting_parameters

Đối tượng JSON chứa mã nguồn nội dung (cmsid), mã video (vid) và thông số nhắm mục tiêu của quảng cáo. Bắt buộc

Phản hồi JSON

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 sẽ đượ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 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	Khoảng 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, ở định dạng dhms (ngày, giờ, phút, giây). Ví dụ: 2h0m0.000s biểu thị thời lượng là 2 giờ.
valid_until	Thời điểm mà phiên truyền trực tuyến hiện tại hết hạn, dưới dạng chuỗi ngày giờ 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":{"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ó 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.

Lưu ý: Các URL được cung cấp trong phản hồi của API có thể thay đổi mà không có thông báo. Do đó, hãy sử dụng các URL như được cung cấp trong phản hồi của API thay vì tự tạo các 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 xử lý tệp kê khai

Mỗi trình thao tác với tệp kê khai có một yêu cầu và định dạng phản hồi riêng. Hãy liên hệ với nhà cung cấp bộ điều khiển để hiểu các yêu cầu cụ thể của họ. Nếu bạn đang triển khai trình thao tác tệp kê khai của riêng mình, hãy đọc hướng dẫn về trình thao tác 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ề đến trình xử lý tệp kê khai để tạo tệp kê khai dành riêng cho phiên. Trừ phi được trình xử lý tệp kê khai chỉ định rõ ràng, phản hồi cho yêu cầu tệp kê khai của bạn sẽ 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 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. Bước này phải diễn ra sau khi bạn nhận được tệp kê khai ghép từ trình thao tác tệp kê khai. Lần lượt bạn 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ả cá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 đã xác định thời gian của luồng hoặc mã sự kiện quảng cáo đầy đủ (trong trường hợp sự kiện thuộc loại progress). Mỗi giá trị là một đối tượng chứa các tham số sau: ad Mã của một quảng cáo khớp với 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 là: start Được kích hoạt ở đầu quảng cáo. firstquartile Được kích hoạt ở cuối phần tư đầu tiên. midpoint Được kích hoạt ở điểm giữa của quảng cáo. thirdquartile Được kích hoạt ở cuối phần tư thứ ba. complete Được kích hoạt ở cuối quảng cáo. progress Được kích hoạt định kỳ trong suốt quá trình 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	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ã 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í mà quảng cáo này xuất hiện trong tập hợp quảng cáo tại điểm chèn quảng cáo, tính theo giây có dấu phẩy động. duration Thời lượng của quảng cáo tính bằng giây có 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 giá trị tìm được trong các đối tượng tags và ads được liệt kê ở trên. Mỗi giá trị là một đối tượng chứa các thông 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 (trong video) và post (sau video). duration Độ dài 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 đã xác định thời gian trong luồng video của bạn.

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 về 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 sẽ 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ã 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à một 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".

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 các sự kiện emsg trong băng mô phỏng các thẻ ID3 v2.3. Mỗi hộp emsg 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.

Ví dụ về hộp emsg

Cấu trúc dữ liệu có thể thay đổi, 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, 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 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 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 ứng dụng

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. Việc so khớp các giá trị này là một 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ả trùng khớp, hãy truy xuất loại sự kiện cũng như các đối tượng ad và ad_break liên kết. Những 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 đố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 cũng như các đối tượng ad và ad_break được liên kết. Thao tác này sẽ truy xuất tất cả sự kiện có loại không phải là 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 trình phát. Ví dụ: khi bạn nhận được start hoặc sự kiện progress đầu tiên, hãy ẩn nút điều khiển dịch vụ tìm kiếm của người chơi và hiển thị một 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".

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

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

Bạn phải gửi một 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ông phải là progress.

Để 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 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 với URL đầy đủ. Nếu yêu cầu xác minh thành công, bạn sẽ nhận được một phản hồi HTTP chứa mã trạng thái 202. Nếu không, bạn sẽ nhận được mã lỗi HTTP 404.

Lưu ý: Bạn không được gửi các sự kiện quảng cáo thuộc loại progress đến Ad Manager. Những sự kiện này nhằm thông báo cho ứng dụng trình phát video của khách hàng rằng một điểm chèn quảng cáo đang phát trong những tình huống có thể không nhận được sự kiện bắt đầu. Ví dụ: nếu người dùng tìm một vị trí hoặc bắt đầu phát tại một dấu thời gian cụ thể ở giữa một 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 loại triển khai lớp DAI