Trang này được dịch bởi Cloud Translation API.

API Nhập mẫu quảng cáo video

API Truyền dẫn mẫu quảng cáo dạng video cho phép các hệ thống quảng cáo bên thứ ba chủ động truyền dẫn mẫu quảng cáo vào YouTube và các sản phẩm DAI. Quy trình này đảm bảo rằng khi một quảng cáo được quyết định từ một máy chủ quảng cáo không phải của Google, các mẫu quảng cáo được trả về đã sẵn sàng và có thể phân phát vào luồng video YouTube hoặc DAI.

Quy trình chủ động nhập mẫu quảng cáo từ các hệ thống quảng cáo của bên thứ ba bao gồm hai phần chính. Phần đầu tiên cho phép hệ thống quảng cáo bên thứ ba cung cấp mẫu quảng cáo cho Google và theo dõi tiến trình của mẫu quảng cáo khi mẫu quảng cáo được nhập vào cơ sở hạ tầng video của Google. Sau khi mẫu quảng cáo được nhập thành công, giá trị nhận dạng sẽ được chuyển lại cho hệ thống quảng cáo.

Bước thứ hai liên quan đến việc hệ thống quảng cáo lấy các giá trị nhận dạng đó và đưa vào tài liệu VAST tham chiếu đến mẫu quảng cáo đã gửi, bằng cách sử dụng Mã nhận dạng quảng cáo chung (VAST 4.0 trở lên) hoặc Tiện ích mẫu quảng cáo thuộc loại "UniversalAdId". Khi gặp một tài liệu VAST từ hệ thống quảng cáo tại thời điểm quyết định trong DAI hoặc YouTube, hệ thống mẫu quảng cáo sẽ trích xuất các giá trị nhận dạng đó từ VAST và tìm nạp mẫu quảng cáo thích hợp từ cơ sở hạ tầng video của Google để chèn vào nhằm phát.

Yêu cầu về nội dung nghe nhìn

Nội dung nghe nhìn của mẫu quảng cáo được gửi đến API phải đáp ứng các tiêu chí sau để đảm bảo hệ thống có thể xử lý thành công.

Loại nội dung nghe nhìn

Google chấp nhận các loại nội dung nghe nhìn sau. Mọi loại nội dung nghe nhìn khác có thể bị từ chối khi gửi.

video/mp4
video/webm
video/quicktime
video/avi
video/mpeg
video/x-flv
flv-application/octet-stream
application/octet-stream
video/3gpp
video/ogg
audio/mp4
audio/mpeg

Thuộc tính nội dung nghe nhìn

Nội dung nghe nhìn bạn gửi phải đáp ứng các tiêu chí sau:

Nội dung nghe nhìn phải có ít nhất một bản âm thanh hoặc video.
Nội dung nghe nhìn phải có thời lượng hợp lý. Không có nội dung nào vượt quá vài phút.
Nội dung nghe nhìn phải có âm thanh hoặc video dài hơn 1 giây.
Nếu có âm thanh, nội dung nghe nhìn phải có cấu hình kênh âm thanh chuẩn như âm thanh đơn âm, âm thanh nổi hoặc âm thanh vòm.

Gửi mẫu quảng cáo để nhập

Sơ đồ quy trình truyền dẫn

Hệ thống quảng cáo của bên thứ ba gửi một Yêu cầu HTTP đến API Truyền dẫn mẫu quảng cáo dạng video cùng với danh sách các tệp nội dung nghe nhìn liên kết với mẫu quảng cáo đó.
API Truyền dẫn mẫu quảng cáo dạng video sẽ chọn mẫu quảng cáo có chất lượng cao nhất trong danh sách được cung cấp và tải mẫu quảng cáo đó xuống từ CDN.
API Truyền dẫn mẫu quảng cáo dạng video sẽ truyền dẫn mẫu quảng cáo đã tải xuống vào Cơ sở hạ tầng video của Google, nhờ đó, mẫu quảng cáo này sẽ có sẵn cho cả các sản phẩm YouTube và DAI.
Thông báo Pub/Sub sẽ được gửi lại cho hệ thống quảng cáo của bên thứ ba kèm theo trạng thái của mẫu quảng cáo. Thông báo sẽ cho biết liệu video đã được tải thành công cho cả YouTube và DAI hay chưa. Nếu không tải được mẫu quảng cáo, thông báo sẽ cho biết nguyên nhân của lỗi.

Hãy tuân thủ các nguyên tắc sau khi gửi mẫu quảng cáo.

Xác thực

Bạn phải truy cập API bằng tài khoản dịch vụ Google Cloud. Tại thời điểm tích hợp, bạn phải cung cấp thông tin tài khoản cho Google để được cấp quyền thích hợp.

Sau khi bạn cung cấp thông tin tài khoản cho Google thông qua creativeingestion@google.com, quyền truy cập sẽ được cấp cho các điểm cuối API và chủ đề Cloud PubSub dùng để phát hành thông báo.

Để bắt đầu quy trình xác thực, hãy làm theo các bước sau:

Tạo tài khoản Google Cloud.
Thiết lập một dự án bằng tài khoản để gửi yêu cầu đến DAI API.
Trong dự án, hãy chuyển đến thẻ IAM & Admin (Quản lý danh tính và quyền truy cập) ở bên trái rồi tạo một tài khoản dịch vụ mới; các yêu cầu sẽ được gửi bằng tài khoản dịch vụ này.
Bật PubSub API và tạo một chủ đề Thông báo của đối tác duy nhất mà API sẽ phát hành tất cả thông báo thành công và lỗi nhập.

Nếu đã áp dụng chính sách hạn chế miền của tổ chức, bạn cần thêm mã khách hàng của Google vào danh sách khách hàng được phép. Hãy liên hệ với creativeingestion@google.com để biết mã nhận dạng. Sau khi hoàn tất, bạn có thể thêm các thực thể chính (tài khoản robot của chúng tôi) từ danh sách khách hàng được phép (mã khách hàng của API) vào các chính sách IAM (Trình xuất bản PubSub).

Thêm video-creative-library-discovery@system.gserviceaccount.com làm Nhà xuất bản PubSub vào chủ đề.
Cung cấp cho creativeingestion@google.com địa chỉ email của tài khoản dịch vụ và chủ đề PubSub để đăng ký thông tin này với API.
Bật DAI API sau khi thêm tài khoản làm người dùng dịch vụ.
Cách đặt thông tin xác thực để truy cập API:
- Tải thông tin xác thực xuống từ tài khoản dịch vụ: Nhấp vào tài khoản dịch vụ trong mục Tài khoản dịch vụ của thẻ Quản trị viên và IAM, nhấp vào Tạo khoá rồi lưu trữ thông tin xác thực.
- Xác thực phương thức gọi API. Đặt GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn của tệp JSON. Xem ví dụ về mã để xác thực ứng dụng gRPC bằng các ngôn ngữ phổ biến.

Truyền dẫn mẫu quảng cáo

Mỗi khi có mẫu quảng cáo mới trong hệ thống quảng cáo của đối tác, hệ thống của đối tác phải gửi mẫu quảng cáo đó đến Creative Ingest API.

Khi bạn gửi mẫu quảng cáo mới cho Google để tải vào cơ sở hạ tầng video, bạn phải cung cấp cùng một dữ liệu mẫu quảng cáo có trong tài liệu VAST do hệ thống quảng cáo tạo. Điều này đảm bảo rằng hành vi chủ động nhập mẫu quảng cáo vào Google có cùng hành vi như tải mẫu quảng cáo khi mẫu quảng cáo được phát hiện lần đầu tiên trong phản hồi quảng cáo.

Mỗi mẫu quảng cáo được gửi sẽ tạo một thao tác nhập kéo dài trên máy chủ mà bạn có thể truy vấn trạng thái. Sau khi hoàn tất, thao tác này sẽ tạo ra một tài nguyên mẫu quảng cáo trong hệ thống. Phản hồi khi gửi mẫu quảng cáo chứa mã của thao tác phát sinh từ yêu cầu. Mã hoạt động thu được sẽ được đưa vào thông báo Cloud PubSub được gửi khi hoạt động hoàn tất để liên kết lại với mẫu quảng cáo ban đầu đã gửi. Bạn cũng có thể dùng mã hoạt động để kiểm tra tiến trình của hoạt động bất cứ lúc nào.

Yêu cầu về mẫu quảng cáo

Dữ liệu được gửi đến API dưới dạng Vùng đệm giao thức hoặc dưới dạng đối tượng JSON. Bạn nên sử dụng Vùng đệm giao thức được gửi bằng gRPC vì các vùng đệm này là cần thiết để sử dụng thông báo PubSub và việc giải mã JSON đã gây ra thêm nhiều phức tạp do các trường google.protobuf.Any trong phản hồi.

Nội dung phản hồi mẫu quảng cáo

Nếu thành công, máy chủ sẽ trả về phản hồi Buffer giao thức hoặc phản hồi JSON, tuỳ thuộc vào loại yêu cầu. Phản hồi chứa tên thao tác truyền dẫn mới tạo và thông tin chi tiết về thao tác đó.

Khi gửi lần đầu, một số siêu dữ liệu liên kết với thao tác có thể trống và kết quả có thể không xuất hiện. Sau khi thao tác hoàn tất, kết quả sẽ được điền sẵn bằng tài nguyên Mẫu quảng cáo (hoặc lỗi) và siêu dữ liệu sẽ chứa thông tin về trạng thái nhập.

Xin lưu ý rằng siêu dữ liệu phải được giải mã từ một proto Any vào proto CreateCreativeOperationMetadata và phản hồi (nếu có) phải được giải mã vào proto Creative.

Thư viện ứng dụng để truy cập API

Hãy làm theo các bước sau để tích hợp với API:

Tải các phần phụ thuộc vùng đệm giao thức xuống rồi di chuyển toàn bộ thư mục google vào thư mục src. Bạn có thể bỏ qua bước này nếu sử dụng Google Cloud App Engine.
Sử dụng trình bổ trợ protoc để tạo mã gRPC từ tệp proto và đặt mã được tạo vào thư mục liên quan.
Tạo một tệp proto mới cho proto được trả về trong thông báo PubSub; lặp lại bước trước đó để tạo mã từ proto.
Sử dụng gRPC để gửi yêu cầu đến API:
1. Nhận Thông tin xác thực mặc định với các phạm vi sau:
https://www.googleapis.com/auth/video-ads,

https://www.googleapis.com/auth/pubsub
1. Gửi yêu cầu đến quy trình Truyền dẫn mẫu quảng cáo.
- Kết nối với dai.googleapis.com:443 bằng thông tin xác thực mặc định.
- Tạo một mô-đun khách cho dịch vụ Creative Ingest bằng mã gRPC được tạo bằng proto.
- Gọi CreateCreative bằng cách sử dụng mô-đun giả lập ứng dụng.
Bạn có thể tạo một mã giả cho dịch vụ Operations bằng cách sử dụng mã gRPC của các hoạt động chạy trong thời gian dài (có trong thư mục googleapis đã tải xuống ở Bước 2). Mã này có thể được dùng để biết trạng thái của một hoạt động nhất định (GetOperation).
Kiểm tra PubSub để xem thông báo:
1. Sử dụng thư viện ứng dụng PubSub hoặc gRPC để kết nối với dịch vụ PubSub và thăm dò ý kiến về thông báo PubSub được phát hành cho chủ đề được cung cấp.
2. Unmarshal thông báo PubSub vào proto từ Bước 4.
3. Bất cứ khi nào một Thao tác chạy trong thời gian dài được trả về từ các lệnh gọi đến CreateCreative, GetOperation hoặc trong thông báo PubSub, hãy huỷ đóng gói siêu dữ liệu vào CreateCreativeOperationMetadata trong discovery.proto từ proto google.protobuf.Any và mọi phản hồi vào Creative trong discovery.proto.

Mã ví dụ về ứng dụng Go

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
  dai "google.golang.org/genproto/googleapis/ads/dai/v1"
  psnotif "protos/dai"
  "google.golang.org/genproto/googleapis/longrunning"
  "cloud.google.com/go/pubsub"
  "golang.org/x/net/context"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
  "google.golang.org/grpc/credentials/oauth"
  "github.com/golang/protobuf/proto"
  anypb "github.com/golang/protobuf/ptypes/any"
)

var scopes = []string{"https://www.googleapis.com/auth/video-ads", "https://www.googleapis.com/auth/pubsub"}

const (
  subID = "sub-id" // The ID for the subscription to the topic you provided us (projects/<project ID>/subscriptions/<subscription ID>)
  project = "your-project-id" // Your Google Cloud Project ID
)

func main() {
  ctx := context.Background()
  crpc, err := oauth.NewApplicationDefault(ctx, scopes...)
  if err != nil {
    // TODO: Handle error
  }

  conn, err := grpc.Dial("dai.googleapis.com:443",
    grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
    grpc.WithPerRPCCredentials(crpc))
  if err != nil {
    // TODO: Handle error 
  }

  apiclient := dai.NewPartnerDiscoveryServiceClient(conn)
  opclient := longrunning.NewOperationsClient(conn)

  op, err := apiclient.CreateCreative(ctx, &dai.CreateCreativeRequest{
    // TODO: Add Creative with metadata and media files.
  })
  if err != nil {
    // TODO: Handle error
  }

  pubsubClient, err := pubsub.NewClient(ctx, project)
  if err != nil {
    // TODO: Handle error
  }
  sub := pubsubClient.Subscription(subID)

  // TODO: Pull from Pub/Sub subscription to receive messages, and acknowledge them
  var msg *pubsub.Message // Assume msg = a received Pub/Sub message

  // Unmarshal the Pub/Sub message into the proto created in step 9a of guide
  var n psnotif.CreateCreativeStatus
  if err := proto.Unmarshal(msg.Data, &n); err != nil {
    // TODO: Handle error
  }
  op = n.GetDetails()
  md, err = anyToMetadata(op.GetMetadata())
  if err != nil {
    // TODO: Handle error
  }
  // TODO: Check if ingest was successful and get Google Video ID from md.GetGvRegistryId()
  // TODO: Enable serving of creative using Google Video ID in VAST document

  // Optionally check the status of an ingest request using the status endpoint
  op, err = opclient.GetOperation(ctx, &longrunning.GetOperationRequest{Name:   op.Name})
  if err != nil {
    // TODO: Handle error
  }
}

// anyToMetadata converts the metadata Any field in an Operation message to
// CreateCreativeOperationMetadata.
func anyToMetadata(msg *anypb.Any) (*dai.CreateCreativeOperationMetadata, error) {
  var md dai.CreateCreativeOperationMetadata
  return &md, proto.Unmarshal(msg.Value, &md)
}

// anyToCreative converts the response Any field in an Operation message to
// Creative.
func anyToCreative(msg *anypb.Any) (*dai.Creative, error) {
  var cr dai.Creative
  return &cr, proto.Unmarshal(msg.Value, &cr)
}

Truy vấn mẫu quảng cáo trong khi phát

Sơ đồ quy trình tra cứu mẫu quảng cáo

Người dùng yêu cầu xem nội dung trên YouTube hoặc DAI.
YouTube / DAI nhận được phản hồi VAST từ hệ thống quảng cáo của bên thứ ba để chèn quảng cáo vào nội dung.
Quảng cáo được trả về được liên kết với các mẫu quảng cáo đã nhập trước đó. Những mẫu quảng cáo đó đã sẵn sàng để phát – chúng được tìm nạp từ Cơ sở hạ tầng video của Google và phát cho người dùng.

Đối tác đã sửa đổi tài liệu VAST

Khi hệ thống quảng cáo trả về phản hồi VAST sau khi mẫu quảng cáo được tải thành công vào cơ sở hạ tầng video của Google, tài liệu phải chứa thông tin tham chiếu đến mẫu quảng cáo đã xử lý. Tài liệu VAST phải tiếp tục bao gồm các tệp nội dung nghe nhìn cho một mẫu quảng cáo nhất định, nhưng không có gì đảm bảo rằng hệ thống sẽ sử dụng các tệp nội dung nghe nhìn này.

Có hai cách để tham chiếu mẫu quảng cáo đã xử lý trong tài liệu VAST: thêm phần tử UniversalAdId mới vào tài liệu VAST 4 trở lên hoặc thêm Tiện ích tuỳ chỉnh.

Mã nhận dạng cho quảng cáo toàn cầu

gvRegistryID do API Truyền dẫn mẫu quảng cáo dạng video trả về là một mã nhận dạng công khai phổ biến dùng để xác định riêng biệt một mẫu quảng cáo dạng video trên nhiều hệ thống quảng cáo. Bạn nên thêm mã nhận dạng này vào tài liệu VAST 4 trở lên của hệ thống quảng cáo để khi YouTube hoặc DAI nhận được tài liệu VAST, mã nhận dạng này có thể được dùng để liên kết lại với mẫu quảng cáo ban đầu đã gửi.

Các hệ thống quảng cáo nên thêm một phần tử UniversalAdId mới vào tài liệu VAST 4 trở lên trong nút Mẫu quảng cáo. Bạn phải đặt thuộc tính idRegistry thành "googlevideo" và giá trị phải là giá trị được cung cấp trong trạng thái của thông báo mẫu quảng cáo đã xử lý thành công.

Sau đây là tài liệu VAST 4 mẫu có mã nhận dạng quảng cáo toàn cầu mới được thêm vào:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

CreativeExtension

Vì phần tử Mã nhận dạng quảng cáo chung chỉ được giới thiệu trong VAST 4.0, nên cùng một dữ liệu cần có phần mở rộng tuỳ chỉnh để hiển thị trong các tài liệu VAST có phiên bản thấp hơn 4.0. Bạn có thể thực hiện việc này bằng cách sử dụng phần tử CreativeExtension trong phần tử Creative của thông số kỹ thuật VAST.

Phần mở rộng mới được giới thiệu là một phần mở rộng chung được bật để cho phép điền bất kỳ giá trị Universal AD ID nào. Trong trường hợp cụ thể này, Mã quảng cáo chung sẽ thuộc sổ đăng ký googlevideo và mã này sẽ là mã video của google.

<VAST version="3.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>My Ad Server</AdSystem>
      <AdTitle>Car Company</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <Linear>...</Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creative>
    </InLine>
  </Ad>
</VAST>

Bạn cũng có thể sử dụng phương pháp CreativeExtension trong VAST 4 trở lên trong trường hợp UniversalAdId đã được điền sẵn mã nhận dạng cho một sổ đăng ký UniversalAdId khác:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="other-registry">other-id</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

API Nhập mẫu quảng cáo video Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.