Эта страница переведена с помощью Cloud Translation API.

API приема видеообъявлений

API Video Creative Ingest позволяет сторонним рекламным системам активно вставлять креативы в продукты YouTube и DAI. Этот процесс гарантирует, что при выборе объявления с рекламного сервера, не являющегося Google, возвращаемые креативы готовы и доступны для показа в видеопотоке YouTube или DAI.

Процесс активного получения креативов из сторонних рекламных систем состоит из двух основных частей. Первая часть позволяет сторонней рекламной системе предоставлять объявления Google и отслеживать ход выполнения объявлений по мере их загрузки в видеоинфраструктуру Google. После успешной загрузки креативов идентификаторы передаются обратно в рекламную систему.

На втором этапе рекламная система принимает эти идентификаторы и включает их в документы VAST, которые ссылаются на отправленный креатив, используя либо универсальный идентификатор объявления (VAST 4.0+), либо расширение креатива типа «UniversalAdId». Когда документ VAST из рекламной системы встречается в момент принятия решения в DAI или YouTube, креативная система извлекает эти идентификаторы из VAST и извлекает соответствующий креатив из видеоинфраструктуры Google для вставки для воспроизведения.

Требования к СМИ

Креативные материалы, отправленные в API, должны соответствовать следующим критериям, чтобы обеспечить их успешную обработку системой.

Типы носителей

Следующие типы мультимедиа принимаются Google. Любые другие типы носителей могут быть отклонены при подаче.

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

Свойства мультимедиа

Представленные СМИ должны соответствовать следующим критериям:

Медиафайл должен иметь хотя бы одну аудио- или видеодорожку.
СМИ должны иметь разумную продолжительность. Ничего более нескольких минут.
Медиафайлы должны содержать аудио или видео продолжительностью более 1 секунды.
Если носитель содержит звук, он должен иметь стандартную конфигурацию аудиоканала, например моно, стерео или объемный звук.

Отправьте креативы на обработку

Блок-схема процесса приема

Сторонняя рекламная система отправляет HTTP-запрос в API приема видеокреативов со списком медиафайлов, связанных с креативом.
API приема видеокреативов выбирает креатив самого высокого качества из предоставленного списка и загружает его из CDN.
API-интерфейс Video Creative Ingest добавляет загруженный креатив в инфраструктуру видео Google, делая его доступным как для продуктов YouTube, так и для продуктов DAI.
Уведомление Pub/Sub отправляется обратно в стороннюю рекламную систему со статусом креатива. В уведомлении будет указано, успешно ли оно было загружено как для YouTube, так и для DAI. Если загрузка креатива завершилась сбоем, в уведомлении будет указана причина сбоя.

Следуйте этим правилам при отправке объявлений.

Аутентификация

Вы должны получить доступ к API, используя учетную запись службы Google Cloud . Во время интеграции информация об учетной записи должна быть предоставлена Google для получения соответствующей авторизации.

После того как информация об аккаунте будет предоставлена Google по адресу Creativeingestion@google.com, будет предоставлен доступ к конечным точкам API и темам Cloud PubSub, используемым для публикации уведомлений.

Чтобы начать процесс аутентификации, выполните следующие действия:

Создайте учетную запись Google Cloud.
Настройте проект с учетной записью для отправки запросов к DAI API.
В проекте перейдите на вкладку IAM & Admin слева и создайте новую учетную запись службы; запросы отправляются с использованием учетной записи службы.
Включите API PubSub и создайте единую уникальную тему уведомлений для партнеров, в которой API будет публиковать все уведомления об успешном и неудачном приеме.
Если у вас действует политика организации по ограничению доменов , вам необходимо добавить идентификатор клиента Google в список разрешенных клиентов. Чтобы получить идентификатор, свяжитесь с нами по адресу creativeingestion@google.com . Как только это будет сделано, вы сможете добавить участников (нашу учетную запись робота) из списков разрешенных клиентов (идентификатор клиента API) в политики IAM (PubSub Publisher).
Добавьте video-creative-library-discovery@system.gserviceaccount.com в качестве издателя PubSub в тему.
Укажите на адрес creativeingestion@google.com адрес электронной почты сервисного аккаунта и тему PubSub, чтобы зарегистрировать эту информацию с помощью API.
Включите DAI API после того, как учетная запись будет добавлена в качестве потребителя услуг.
Чтобы установить свои учетные данные для доступа к API:
- Загрузите учетные данные из учетной записи службы. Щелкните учетную запись службы в разделе « Учетные записи служб» на вкладке «IAM и администратор» , нажмите «Создать ключ» и сохраните учетные данные.
- Аутентифицируйте вызывающего API . Задайте GOOGLE_APPLICATION_CREDENTIALS путь к файлу JSON. См. примеры кода для аутентификации клиентов gRPC на распространенных языках.

Креативный прием

Каждый раз, когда в рекламной системе партнера появляется новый креатив, он должен быть отправлен партнерской системой в API Creative Ingest.

Когда новые креативы отправляются в Google для загрузки в видеоинфраструктуру, должны быть предоставлены те же данные креатива, которые включены в документ VAST, созданный рекламной системой. Это гарантирует, что поведение проактивной загрузки креативов в Google будет таким же, как и загрузка креативов, когда они впервые обнаруживаются в ответе на объявление.

Каждое отправленное объявление создает на сервере длительную операцию загрузки, статус которой можно запросить. После успешного завершения операции в системе появляется творческий ресурс. Ответ на отправку креатива содержит идентификатор операции, произошедшей в результате запроса. Полученный идентификатор операции включается в уведомления Cloud PubSub, которые отправляются после завершения операции и сопоставляются с исходным отправленным креативом. Идентификатор операции также можно использовать для проверки хода операции в любой момент времени.

Креативные запросы

Данные отправляются в API в виде буферов протокола или объектов JSON. Рекомендуется использовать буферы протокола, отправляемые с помощью gRPC , поскольку они необходимы для использования уведомлений PubSub, а демаршалинг JSON добавляет сложности из-за полей google.protobuf.Any в ответе.

Креативные ответы

В случае успеха сервер возвращает ответ протокольного буфера или ответ JSON, в зависимости от типа запроса. Ответ содержит имя вновь созданной операции приема и подробные сведения об операции.

При первоначальной отправке некоторые метаданные, связанные с операцией, могут быть пустыми, и результат может отсутствовать. После завершения операции результат заполняется креативным ресурсом (или ошибкой), а метаданные содержат информацию о статусе приема.

Обратите внимание, что метаданные должны быть демаршалированы из Any прототипа в прототип CreateCreativeOperationMetadata , а ответ (если он присутствует) должен быть демаршалирован в Creative прототип.

Клиентская библиотека для доступа к API

Выполните следующие шаги для интеграции с API:

Загрузите зависимости буфера протокола и переместите всю папку google в свой каталог src . Это можно пропустить, если вы используете Google Cloud App Engine.
Используйте плагин protoc для генерации кода gRPC из файла прототипа и поместите сгенерированный код в соответствующий каталог.
Создайте новый файл прототипа для прототипа, возвращенного в уведомлении PubSub; повторите предыдущий шаг, чтобы сгенерировать код из прототипа.
Используйте gRPC для отправки запросов к API:
1. Получите учетные данные по умолчанию со следующими областями:
https://www.googleapis.com/auth/video-ads ,
https://www.googleapis.com/auth/pubsub
1. Отправьте запрос в Creative Ingest.
- Подключитесь к dai.googleapis.com:443 используя учетные данные по умолчанию.
- Создайте клиентскую заглушку для службы Creative Ingest, используя код, созданный прототипом gRPC.
- Вызовите CreateCreative используя клиентскую заглушку.
При необходимости создайте заглушку для службы операций, используя код gRPC длительных операций, включенный в каталог googleapis, загруженный на шаге 2, который можно использовать для получения статуса данной операции ( GetOperation ).
Проверьте PubSub на наличие уведомлений:
1. Используйте клиентскую библиотеку PubSub или gRPC для подключения к службе PubSub и опроса уведомлений PubSub, опубликованных в указанной теме.
2. Демаршалируйте сообщение PubSub в прототип из шага 4.
3. Всякий раз, когда из вызовов CreateCreative , GetOperation или уведомления PubSub возвращается длительная операция, демаршалируйте метаданные в CreateCreativeOperationMetadata в discovery.proto из google.protobuf.Any proto и любой ответ в Creative в discovery.proto .

Пример клиентского кода 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)
}

Творческий поиск во время воспроизведения

Блок-схема процесса творческого поиска

Пользователь запрашивает просмотр контента на YouTube или DAI.
YouTube/DAI получает ответ VAST от сторонней рекламной системы для вставки рекламы в контент.
Возвращенные объявления сопоставляются с ранее загруженными креативами. Эти объявления готовы к воспроизведению: они извлекаются из инфраструктуры видео Google и воспроизводятся пользователю.

Документы VAST, измененные партнером

Когда ответ VAST возвращается от рекламной системы после успешной загрузки креатива в видеоинфраструктуру Google, документ должен содержать ссылку на обработанный креатив. Документ VAST должен по-прежнему включать медиафайлы для данного объявления, но нет никакой гарантии, что эти медиафайлы будут использоваться системой.

Есть два способа сослаться на обработанное объявление в документе VAST: добавить новый элемент UniversalAdId в документ VAST 4+ или добавить собственное расширение.

Универсальный рекламный идентификатор

gvRegistryID, возвращаемый API-интерфейсом Video Creative Ingest, представляет собой универсальный общедоступный идентификатор, используемый для уникальной идентификации видеообъявления в нескольких рекламных системах. Этот идентификатор следует добавить в документы VAST 4+ рекламной системы, чтобы при получении документа VAST YouTube или DAI этот идентификатор можно было использовать для сопоставления с исходно отправленным объявлением.

Рекламные системы должны добавить новый элемент UniversalAdId в свои документы VAST 4+ в разделе Creative. Атрибуту idRegistry должно быть присвоено значение «googlevideo», а значение должно соответствовать значению, указанному в статусе успешно обработанного уведомления о креативе.

Ниже приведен образец документа VAST 4 с добавленным новым универсальным идентификатором объявления:

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

КреативноеРасширение

Поскольку элемент Universal Ad ID появился только в VAST 4.0, для тех же данных требуется специальное расширение, чтобы их можно было отображать в документах VAST версии ниже 4.0. Это делается с помощью элемента CreativeExtension в элементе Creative спецификации VAST.

Представленное новое расширение представляет собой универсальное расширение, позволяющее заполнять любое значение универсального идентификатора AD. В этом конкретном случае универсальный рекламный идентификатор будет принадлежать реестру GoogleVideo, а идентификатор будет идентификатором видео 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>

Подход CreativeExtension также можно использовать в VAST 4+ в случае, если UniversalAdId уже заполнен идентификатором для другого реестра UniversalAdId:

<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 приема видеообъявлений Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.