Early ad break notification

Sử dụng API thông báo chèn quảng cáo sớm

Lưu ý: API này vẫn đang trong giai đoạn thử nghiệm. Hãy trao đổi với người quản lý tài khoản nếu bạn muốn yêu cầu quyền truy cập vào chương trình EABN.

API Thông báo điểm chèn quảng cáo sớm (EABN) cho phép bạn thông báo cho Google Ad Manager về điểm chèn quảng cáo sắp tới bằng siêu dữ liệu trước khi bắt đầu điểm chèn quảng cáo. Bạn có thể gửi yêu cầu thông báo tối đa một giờ trước điểm chèn quảng cáo. Hướng dẫn này giải thích cách bật và sử dụng API EABN, cũng như các mẫu yêu cầu và phản hồi.

Thận trọng: Các yêu cầu EABN không thể thay đổi được, vì vậy, bạn không thể sửa đổi điểm chèn quảng cáo sau khi tạo. Các yêu cầu tiếp theo để tạo điểm chèn quảng cáo cho cùng một sự kiện sẽ bị từ chối cho đến khi điểm chèn xuất hiện trong tệp kê khai cho sự kiện đó.

Lệnh gọi đến API EABN phải bao gồm các thông tin sau:

  • Giá trị nhận dạng của sự kiện phát trực tiếp tương ứng mà điểm chèn quảng cáo được tạo. Giá trị nhận dạng này có thể là một trong những giá trị sau:
  • "Khoá tài sản" của sự kiện phát trực tiếp.
  • “Khoá thành phần tuỳ chỉnh” của sự kiện phát trực tiếp, cho phép bạn quản lý không gian khoá của riêng mình bằng cách chỉ định chuỗi giá trị nhận dạng của riêng bạn.
  • "Content Source ID" và "Content ID" của sự kiện phát trực tiếp.

Lưu ý: Bạn phải được bật để sử dụng loại giá trị nhận dạng này. Để biết thêm thông tin, hãy liên hệ với người quản lý tài khoản.

  • Thời lượng dự kiến của điểm chèn quảng cáo tiếp theo. Thời lượng phải gần với thời lượng chèn quảng cáo thực tế nhất có thể.

Ngoài các trường bắt buộc này, bạn cũng có thể gửi thông số nhắm mục tiêu tuỳ chỉnh, tên của một mẫu nhóm quảng cáo cần áp dụng hoặc dữ liệu Sử dụng tín hiệu SCTE35 (nếu có).

Điều kiện tiên quyết

Để sử dụng API EABN, bạn phải tạo tài khoản dịch vụ và thêm tài khoản đó vào mạng Google Ad Manager của mình.

Tạo một tài khoản dịch vụ

Để tạo tài khoản dịch vụ dùng để gọi API EABN, hãy hoàn tất các bước sau: – Nếu bạn có tài khoản Google Cloud, hãy sử dụng mô-đun IAM để tạo tài khoản dịch vụ. Để biết thêm thông tin, hãy xem bài viết Tạo và quản lý tài khoản dịch vụ. – Nếu bạn không có tài khoản Google Cloud, hãy hoàn thành các bước sau để tạo tài khoản trong Google API Console:

  1. Tạo dự án mới hoặc chọn dự án hiện có.
  2. Trong trang Thông tin đăng nhập, hãy nhấp vào Quản lý tài khoản dịch vụ.
  3. Trên trang Tài khoản dịch vụ, hãy nhấp vào TẠO TÀI KHOẢN DỊCH VỤ.
  4. Trên trang Tạo tài khoản dịch vụ, hãy nhập thông tin tài khoản. Sau đó, hãy nhấp vào TẠO.

Sau khi bạn tạo tài khoản dịch vụ, hãy sao chép khoá JSON của tài khoản đó. Khoá này dùng để xác thực.

Thêm tài khoản dịch vụ vào mạng Google Ad Manager

Để thêm tài khoản dịch vụ vào mạng của bạn, hãy hoàn tất các bước trong bài viết Thêm người dùng tài khoản dịch vụ để truy cập API.

Bật API

Sau khi bạn tạo tài khoản dịch vụ, hãy cung cấp thông tin sau cho người quản lý tài khoản để bật API cho tài khoản của bạn:

  • Địa chỉ email Tài khoản Google Cloud của bạn
  • Tài khoản dịch vụ của bạn
  • Mã mạng của mạng Google Ad Manager của bạn.

Sau khi người quản lý tài khoản của bạn đã bật API, hãy hoàn tất các bước sau để bật API:

  1. Trong thư viện Google API, hãy tìm kiếm “Google Ad Manager Video API”.
  2. Nhấp vào BẬT.

Lưu ý: Nếu API này không xuất hiện trong kết quả tìm kiếm, hãy liên hệ với người quản lý tài khoản để xác nhận rằng tài khoản của bạn đã được kích hoạt API DAI.

Sử dụng API

Bạn có thể gọi API EABN bằng yêu cầu JSON/REST.

Ủy quyền

Để thực hiện các lệnh gọi được uỷ quyền đến API EABN, bạn cần tạo thông tin xác thực tài khoản dịch vụ OAuth2 bằng khoá JSON trong tài khoản dịch vụ của bạn và phạm vi https://www.googleapis.com/auth/video-ads. Để biết thêm thông tin, hãy xem phần Sử dụng OAuth 2.0 cho ứng dụng từ máy chủ đến máy chủ.

Bạn phải thêm mã thông báo uỷ quyền thu được dưới dạng tiêu đề Xác thực cho mỗi lệnh gọi đến API EABN.

Gửi thông báo chèn quảng cáo sớm

Để gửi thông báo chèn quảng cáo sớm, hãy gửi yêu cầu POST đến một trong ba URL EABN hợp lệ, tuỳ thuộc vào cách bạn muốn chỉ định luồng trực tiếp. Các phần sau đây giải thích sự khác biệt giữa các URL, đồng thời cung cấp ví dụ về yêu cầu và phản hồi.

URL

Có ba URL hợp lệ cho thông báo chèn quảng cáo sớm. Bạn có thể sử dụng cả ba loại để tạo điểm chèn quảng cáo (POST) hoặc lấy danh sách các điểm chèn quảng cáo được chỉ định (GET).

Để sử dụng khoá tài sản của một sự kiện phát trực tiếp, hãy sử dụng:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Để sử dụng khoá thành phần tuỳ chỉnh của một sự kiện phát trực tiếp, hãy sử dụng:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Để sử dụng giải pháp Content Source ID và Content ID, hãy sử dụng:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Đối với tất cả các thông số:

  • network_code đại diện cho mã mạng của mạng Google Ad Manager của bạn.
  • asset_key là khoá tài sản xuất hiện trên trang chi tiết về sự kiện phát trực tiếp.
  • custom_asset_key đại diện cho khoá thành phần tuỳ chỉnh của sự kiện phát trực tiếp.
  • content_source_id đại diện cho mã của một nguồn nội dung trong Google Ad Manager.
  • content_id là mã nhận dạng của một nội dung trong Google Ad Manager.

Lưu ý: Cặp content_source_id/content_id đã chỉ định phải được liên kết với một chương trình phát trực tiếp trong Google Ad Manager.

Nội dung yêu cầu – chỉ dùng để tạo điểm chèn quảng cáo (POST)

Đối tượng

expectedDuration

Bắt buộc Thời lượng của điểm chèn quảng cáo này, sử dụng định dạng thời lượng chuẩn của Google (xx.xxxs trong đó xx.xxx là số giây)

customParams

Không bắt buộc Cặp khoá-giá trị được đưa vào yêu cầu quảng cáo cho điểm chèn này để nhắm mục tiêu theo tiêu chí tuỳ chỉnh trong AM360, được phân tách bằng

=

và đã tham gia bởi

&

.
Ví dụ:

key=value&key2=value2,value3


Để biết thêm thông tin về việc nhắm mục tiêu, hãy xem bài viết Cung cấp thông số nhắm mục tiêu cho luồng của bạn.

podTemplateName

Không bắt buộc Tên mẫu nhóm quảng cáo

scte35CueOut

Không bắt buộc Dữ liệu được mã hoá theo chuẩn Base-64 từ điểm bắt đầu ra scte35. Có thể bao gồm

splice_insert()

hoặc

time_signal()

.
Ví dụ:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

Yêu cầu mẫu

Tạo điểm chèn quảng cáo
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
Nội dung phản hồi

Nội dung phản hồi chứa tất cả các thông số được gửi trong đối tượng adBreak, cũng như trường name bổ sung chứa mã tiêu chuẩn trên toàn Google của điểm chèn quảng cáo đã tạo. Trường này được trả về ở định dạng sau:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
Ví dụ về phản hồi
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
Liệt kê các điểm chèn quảng cáo được chỉ định
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
Nội dung phản hồi

Nội dung phản hồi chứa điểm chèn quảng cáo với trường breakState bổ sung cho mỗi điểm chèn quảng cáo được chỉ định cho luồng. Trường breakState hỗ trợ các giá trị sau:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
Ví dụ về phản hồi
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}