Ứng dụng trình phát video của ứng dụng cho sự kiện phát trực tiếp

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 API phân phát nhóm DAI

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: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Tham số đường dẫn

{network_code} Mã mạng Google Ad Manager 360 của bạn
{custom_asset} Giá trị nhận dạng tuỳ chỉnh đã liên kết với sự kiện này trong Google Ad Manager.

Tham số cơ thể được mã hoá theo mẫu

Một tập hợp tuỳ chọn các biểu mẫu được mã hoá thông số nhắm mục tiêu

JSON phản hồi

media_verification_url URL cơ sở để ping các sự kiện theo dõi lượt phát. Hoàn tất quy trình xác minh nội dung nghe nhìn URL đượ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, tính theo Định dạng dhms (ngày, giờ, phút, giây). Ví dụ: 2h0m0.000s thể hiện thời lượng 2 giờ.
valid_until Thời gian mà phiên truyền trực tuyến hiện tại hết hạn, dưới dạng ISO 8601 chuỗi ngày giờ trong yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

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

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

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

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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.

Cuộc thăm dò ý kiến về siêu dữ liệu AdBreak mới

Ứng dụng chịu trách nhiệm truy xuất siêu dữ liệu cho mỗi điểm chèn quảng cáo, vì vậy biết hiển thị nào cần được kích hoạt. Để thực hiện việc này, bạn sẽ đặt một để thường xuyên thăm dò API DAI metadata_url cho quảng cáo mới của bạn. Khoảng thời gian thăm dò ý kiến được chỉ định trong polling_frequency trong phản hồi đăng ký luồng.

Đổ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ột sự kiện quảng cáo Mã nhận dạng xuất hiện trong siêu dữ liệu về thời gian của luồng phát hoặc trong trường hợp có 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ã 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 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 ở phần đầu của 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ảng cáo để thông báo cho ứng dụng rằng quảng cáo đang phát giờ nghỉ.
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. Chiến lược phát hành đĩa đơn khoá là các mã quảng cáo khớp với các giá trị được tìm thấy trong đối tượng tags được liệt kê ở 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 ad_breaks .
position Vị trí mà quảng cáo này xuất hiện trong tập hợp các quảng cáo trong quảng cáo ngắt, ở dạng dấu phẩy động trong giây.
duration Thời lượng 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. Các khoá là mã điểm chèn quảng cáo khớp với các giá trị tìm thấy trong 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 (quảng cáo trong video) và post (quảng cáo sau video).
duration Thời lượng của điểm chèn quảng cáo tính bằng giây có 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 sau mỗi cuộc thăm dò ý kiến để liên kết các sự kiện siêu dữ liệu được tính giờ 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

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 quảng cáo ngắt, cho 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