Video Creative Ingest API

Video Creative Ingest API memungkinkan sistem iklan pihak ketiga secara proaktif melakukan transfer materi iklan ke produk YouTube dan DAI. Proses ini memastikan bahwa saat iklan diputuskan dari server iklan non-Google, materi iklan yang ditampilkan sudah siap dan tersedia untuk ditayangkan ke streaming video YouTube atau DAI.

Proses penyerapan materi iklan secara proaktif dari sistem iklan pihak ketiga meliputi dua bagian utama. Bagian pertama memungkinkan sistem iklan pihak ketiga menyediakan materi iklan ke Google dan memantau progres materi iklan saat dimasukkan ke infrastruktur video Google. Setelah materi iklan berhasil diproses, ID akan diteruskan kembali ke sistem iklan.

Langkah kedua melibatkan sistem iklan yang mengambil ID tersebut dan menyertakannya dalam dokumen VAST yang mereferensikan materi iklan yang dikirim, menggunakan Universal Ad ID (VAST 4.0+) atau Ekstensi Materi Iklan dengan jenis "UniversalAdId". Saat dokumen VAST dari sistem iklan ditemukan pada waktu pengambilan keputusan di DAI atau YouTube, sistem materi iklan akan mengekstrak ID tersebut dari VAST dan mengambil materi iklan yang sesuai dari infrastruktur video Google untuk disisipkan untuk diputar.

Persyaratan media

Media materi iklan yang dikirimkan ke API harus memenuhi kriteria berikut untuk memastikan materi iklan tersebut berhasil diproses oleh sistem.

Jenis media

Jenis media berikut diterima oleh Google. Jenis media lainnya dapat ditolak setelah dikirim.

  • 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

Properti media

Media yang dikirimkan harus memenuhi kriteria berikut:

  • Media harus memiliki minimal satu trek audio atau video.
  • Media harus memiliki durasi yang wajar. Tidak ada yang melebihi beberapa menit.
  • Media harus memiliki audio atau video yang berdurasi lebih dari 1 detik.
  • Jika memiliki audio, media harus memiliki konfigurasi saluran audio standar seperti mono, stereo, atau suara surround.

Mengirimkan materi iklan untuk penyerapan

Diagram alur proses penyerapan

  1. Sistem iklan pihak ketiga mengirimkan Permintaan HTTP ke Video Creative Ingest API dengan daftar file media yang terkait dengan materi iklan.
  2. Video Creative Ingest API memilih materi iklan dengan kualitas tertinggi dari daftar yang diberikan dan mendownloadnya dari CDN.
  3. Video Creative Ingest API menyerap materi iklan yang didownload ke Infrastruktur Video Google, sehingga tersedia untuk produk YouTube dan DAI.
  4. Notifikasi Pub/Sub dikirim kembali ke sistem iklan pihak ketiga dengan status materi iklan. Notifikasi akan menunjukkan apakah iklan berhasil dimuat untuk YouTube dan DAI. Jika pemuatan materi iklan mengakibatkan kegagalan, notifikasi akan menunjukkan penyebab kegagalan tersebut.

Ikuti panduan ini saat mengirimkan materi iklan.

Autentikasi

Anda harus mengakses API menggunakan akun layanan Google Cloud. Pada saat integrasi, informasi akun harus diberikan kepada Google untuk mendapatkan otorisasi yang sesuai.

Setelah informasi akun diberikan kepada Google melalui creativeingestion@google.com, akses akan diberikan ke endpoint API dan topik Cloud PubSub yang digunakan untuk memublikasikan notifikasi.

Untuk memulai proses autentikasi, ikuti langkah-langkah berikut:

  1. Buat akun Google Cloud.
  2. Siapkan project dengan akun untuk mengirim permintaan ke DAI API.
  3. Dalam project, buka tab IAM & Admin di sebelah kiri, lalu buat akun layanan baru; permintaan dikirim menggunakan akun layanan.

  4. Aktifkan PubSub API dan buat satu topik Notifikasi Partner unik tempat API memublikasikan semua notifikasi keberhasilan dan kegagalan penyerapan.

    Jika Anda memiliki kebijakan organisasi pembatasan domain, Anda harus menambahkan ID pelanggan Google ke daftar pelanggan yang diizinkan. Hubungi creativeingestion@google.com untuk mendapatkan ID. Setelah selesai, Anda dapat menambahkan akun utama (akun robot kami) dari daftar pelanggan yang diizinkan (client ID API) ke kebijakan IAM (Penayang PubSub).

    Tambahkan video-creative-library-discovery@system.gserviceaccount.com sebagai Penerbit PubSub ke topik.

  5. Berikan creativeingestion@google.com dengan alamat email akun layanan dan topik PubSub untuk mendaftarkan informasi ini ke API.

  6. Aktifkan DAI API setelah akun ditambahkan sebagai konsumen layanan.

  7. Untuk menetapkan kredensial Anda guna mengakses API:

    • Download kredensial dari akun layanan: Klik akun layanan di bagian Akun layanan pada tab IAM & Admin, klik Buat Kunci, lalu simpan kredensial.

    • Autentikasikan pemanggil API Anda. Tetapkan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON. Lihat contoh kode untuk mengautentikasi klien gRPC dalam bahasa umum.

Proses transfer materi iklan

Setiap kali materi iklan baru tersedia di sistem iklan partner, materi iklan tersebut harus dikirim oleh sistem partner ke Creative Ingest API.

Saat materi iklan baru dikirimkan ke Google untuk dimuat ke dalam infrastruktur video, data materi iklan yang sama yang disertakan dalam dokumen VAST yang dihasilkan oleh sistem iklan harus diberikan. Hal ini memastikan bahwa perilaku proses transfer materi iklan ke Google secara proaktif memiliki perilaku yang sama dengan memuat materi iklan saat pertama kali ditemukan dalam respons iklan.

Setiap materi iklan yang dikirimkan akan membuat operasi transfer yang berjalan lama di server yang statusnya dapat dibuat kuerinya. Setelah berhasil diselesaikan, operasi tersebut akan menghasilkan resource materi iklan dalam sistem. Respons untuk mengirimkan materi iklan berisi ID operasi yang dihasilkan dari permintaan. ID operasi yang dihasilkan disertakan dalam notifikasi Cloud PubSub yang dikirim saat operasi selesai untuk memetakan kembali ke materi iklan asli yang dikirim. ID operasi juga dapat digunakan untuk memeriksa progres operasi pada waktu tertentu.

Permintaan materi iklan

Data dikirim ke API sebagai Buffer Protokol atau sebagai objek JSON. Buffer Protokol, yang dikirim menggunakan gRPC, direkomendasikan karena diperlukan untuk menggunakan notifikasi PubSub, dan unmarshaling JSON memiliki komplikasi tambahan karena kolom google.protobuf.Any dalam respons.

Respons kreatif

Jika berhasil, server akan menampilkan respons Buffer Protokol atau respons JSON, bergantung pada jenis permintaan. Respons berisi nama operasi proses transfer yang baru dibuat dan detail operasi.

Setelah pengiriman awal, beberapa metadata yang terkait dengan operasi mungkin kosong dan hasilnya mungkin tidak ada. Setelah operasi selesai, hasilnya akan diisi dengan resource Materi iklan (atau error) dan metadata berisi informasi tentang status transfer.

Perhatikan bahwa metadata harus di-unmarshal dari proto Any ke proto CreateCreativeOperationMetadata, dan respons (jika ada) harus di-unmarshal ke proto Creative.

Library klien untuk mengakses API

Ikuti langkah-langkah berikut untuk berintegrasi dengan API:

  1. Download dependensi buffering protokol dan pindahkan seluruh folder google ke direktori src Anda. Langkah ini dapat dilewati jika menggunakan Google Cloud App Engine.
  2. Gunakan plugin protoc untuk membuat kode gRPC dari file proto dan menempatkan kode yang dihasilkan di direktori yang relevan.
  3. Buat file proto baru untuk proto yang ditampilkan dalam notifikasi PubSub; ulangi langkah sebelumnya untuk membuat kode dari proto.

  4. Gunakan gRPC untuk membuat permintaan ke API:

    1. Dapatkan Kredensial Default dengan cakupan berikut:

    https://www.googleapis.com/auth/video-ads,

    https://www.googleapis.com/auth/pubsub

    1. Kirim permintaan ke Proses Upload Materi Iklan.
    • Hubungkan ke dai.googleapis.com:443 menggunakan kredensial default.
    • Buat stub klien ke layanan Creative Ingest menggunakan kode proto gRPC.
    • Panggil CreateCreative menggunakan stub klien.

    Secara opsional, buat stub ke layanan Operasi menggunakan kode gRPC operasi yang berjalan lama—disertakan dalam direktori googleapis yang didownload di Langkah 2—yang dapat digunakan untuk mendapatkan status operasi tertentu (GetOperation).

  5. Periksa PubSub untuk notifikasi:

    1. Gunakan library klien PubSub atau gRPC untuk terhubung ke layanan PubSub dan melakukan polling untuk notifikasi PubSub yang dipublikasikan ke topik yang diberikan.

    2. Unmarshal pesan PubSub ke proto dari Langkah 4.

    3. Setiap kali Operasi yang berjalan lama ditampilkan dari panggilan ke CreateCreative, GetOperation, atau dalam notifikasi PubSub, unmarshal metadata ke CreateCreativeOperationMetadata di discovery.proto dari proto google.protobuf.Any dan respons apa pun ke Creative di discovery.proto.

Contoh kode klien 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)
}

Pencarian materi iklan selama pemutaran

Diagram alir proses pencarian materi iklan

  1. Permintaan pengguna untuk melihat konten di YouTube atau DAI.
  2. YouTube / DAI mendapatkan respons VAST dari sistem iklan pihak ketiga untuk iklan yang akan disisipkan ke dalam konten.
  3. Iklan yang ditampilkan dipetakan ke materi iklan yang ditransfer sebelumnya. Materi iklan tersebut sudah siap diputar - materi iklan diambil dari Infrastruktur Video Google dan diputar untuk pengguna.

Dokumen VAST yang diubah partner

Saat respons VAST ditampilkan dari sistem iklan setelah materi iklan berhasil dimuat ke infrastruktur video Google, dokumen harus berisi referensi ke materi iklan yang diproses. Dokumen VAST harus terus menyertakan file media untuk materi iklan tertentu, tetapi tidak ada jaminan bahwa file media ini akan digunakan oleh sistem.

Ada dua cara untuk mereferensikan materi iklan yang diproses dalam dokumen VAST: menambahkan elemen UniversalAdId baru ke dokumen VAST 4+ atau menambahkan Ekstensi kustom.

ID Iklan Universal

gvRegistryID yang ditampilkan oleh Video Creative Ingest API adalah ID universal yang ditampilkan kepada publik dan digunakan untuk mengidentifikasi secara unik materi iklan video di beberapa sistem iklan. ID ini harus ditambahkan ke dokumen VAST 4+ sistem iklan sehingga saat dokumen VAST diterima oleh YouTube atau DAI, ID tersebut dapat digunakan untuk memetakan kembali ke materi iklan yang awalnya dikirimkan.

Sistem iklan harus menambahkan elemen UniversalAdId baru ke dokumen VAST 4+ di bagian node Materi Iklan. Atribut idRegistry harus ditetapkan ke "googlevideo" dan nilainya harus berupa nilai yang diberikan dalam status pemberitahuan materi iklan yang berhasil diproses.

Berikut adalah contoh dokumen VAST 4 dengan ID Iklan Universal baru yang ditambahkan:

<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

Karena elemen ID Iklan Universal hanya diperkenalkan di VAST 4.0, data yang sama memerlukan ekstensi kustom agar dapat ditampilkan di dokumen VAST dengan versi yang lebih rendah dari 4.0. Hal ini dilakukan menggunakan elemen CreativeExtension di bawah elemen Creative dari spesifikasi VAST.

Ekstensi baru yang diperkenalkan adalah ekstensi generik yang diaktifkan untuk memungkinkan nilai ID Iklan Universal diisi. Dalam kasus khusus ini, ID Iklan Universal akan menjadi milik registry googlevideo dan ID-nya adalah ID video 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>

Pendekatan CreativeExtension juga dapat digunakan di VAST 4+ jika UniversalAdId sudah diisi dengan ID untuk registry UniversalAdId yang berbeda:

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