Esta página foi traduzida pela API Cloud Translation.

API Video Creative Ingest

A API de transferência de criativos de vídeo permite que sistemas de anúncios de terceiros transfiram proativamente criativos para o YouTube e produtos de DAI. Esse processo garante que, quando um anúncio for decidido por um servidor de anúncios que não seja do Google, os criativos retornados esteja prontos e disponíveis para veiculação em um fluxo de vídeo do YouTube ou do DAI.

O processo de ingestão proativa de criativos de sistemas de anúncios de terceiros envolve duas partes principais. A primeira parte permite que o sistema de anúncios de terceiros forneça criativos ao Google e monitore o progresso deles à medida que são ingeridos na infraestrutura de vídeo do Google. Depois que os criativos forem ingeridos, os identificadores serão transmitidos de volta ao sistema de anúncios.

A segunda etapa envolve o sistema de anúncios coletar esses identificadores e incluí-los nos documentos VAST que fazem referência ao criativo enviado, usando o ID universal do anúncio (VAST 4.0+) ou uma extensão do criativo do tipo "UniversalAdId". Quando um documento VAST do sistema de anúncios é encontrado no momento da decisão no DAI ou no YouTube, o sistema de criativos extrai esses identificadores do VAST e busca o criativo adequado da infraestrutura de vídeo do Google para ser inserido na reprodução.

Requisitos de mídia

A mídia do criativo enviada para a API precisa atender aos seguintes critérios para garantir que possa ser processada pelo sistema.

Tipos de mídia

Os seguintes tipos de mídia são aceitos pelo Google. Qualquer outro tipo de mídia pode ser rejeitado no envio.

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

Propriedades de mídia

A mídia enviada precisa atender aos seguintes critérios:

A mídia precisa ter pelo menos uma faixa de áudio ou vídeo.
A mídia precisa ter uma duração razoável. Nada que dure mais do que alguns minutos.
A mídia precisa ter áudio ou vídeo com mais de 1 segundo de duração.
Se a mídia tiver áudio, ela precisará ter uma configuração de canal de áudio padrão, como mono, estéreo ou som surround.

Enviar criativos para transferência

Diagrama de fluxo do processo de transferência

Um sistema de anúncios de terceiros envia uma solicitação HTTP para a API Video Creative Ingest com uma lista de arquivos de mídia associados ao criativo.
A API de transferência de criativos em vídeo seleciona o criativo de maior qualidade da lista fornecida e faz o download dele do CDN.
A API de transferência de criativos de vídeo transfere o criativo transferido para a infraestrutura de vídeo do Google, disponibilizando-o para os produtos do YouTube e da DAI.
Uma notificação do Pub/Sub é enviada de volta ao sistema de anúncios de terceiros com o status do criativo. A notificação vai indicar se ela foi carregada com sucesso para o YouTube e o DAI. Se o carregamento do criativo resultar em falha, a notificação vai indicar a causa dela.

Siga estas diretrizes ao enviar criativos.

Autenticação

É necessário acessar a API usando uma conta de serviço do Google Cloud. No momento da integração, as informações da conta precisam ser fornecidas ao Google para receber a autorização adequada.

Depois que as informações da conta forem enviadas ao Google por creativeingestion@google.com, o acesso será concedido aos endpoints da API e aos tópicos do Cloud Pub/Sub usados para publicar notificações.

Para iniciar o processo de autenticação, siga estas etapas:

Crie uma conta do Google Cloud.
Configure um projeto com a conta para enviar solicitações à API DAI.
No projeto, acesse a guia IAM e administrador à esquerda e crie uma nova conta de serviço. As solicitações são enviadas usando a conta de serviço.
Ative a API Pub/Sub e crie um único tópico de notificação do parceiro para que a API publique todas as notificações de sucesso e falha de transferência.

Se você tiver uma política de restrição de domínio da organização ativada, será necessário adicionar o ID de cliente do Google à lista de clientes permitidos. Entre em contato com creativeingestion@google.com para saber o ID. Depois disso, você poderá adicionar os principais (nossa conta de robô) das listas de clientes permitidas (o ID de cliente da API) às políticas do IAM (editor do PubSub).

Adicione video-creative-library-discovery@system.gserviceaccount.com como um editor do Pub/Sub ao tópico.
Forneça a creativeingestion@google.com o endereço de e-mail da conta de serviço e o tópico do Pub/Sub para registrar essas informações na API.
Ative a API DAI depois que a conta for adicionada como consumidora de serviços.
Para definir as credenciais de acesso à API:
- Faça o download das credenciais da conta de serviço: clique na conta de serviço na seção Contas de serviço da guia IAM e administrador, clique em Criar chave e armazene as credenciais.
- Autenticar o autor da chamada da API. Defina GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON. Consulte os exemplos de código para autenticar clientes gRPC em linguagens comuns.

Transferência de criativos

Sempre que um novo criativo estiver disponível no sistema de anúncios de um parceiro, ele precisa ser enviado pelo sistema do parceiro para a API Creative Ingest.

Quando novos criativos são enviados ao Google para carregar na infraestrutura de vídeo, os mesmos dados de criativos incluídos no documento VAST gerado pelo sistema de anúncios precisam ser fornecidos. Isso garante que o comportamento de ingestão proativa de criativos no Google tenha o mesmo comportamento de carregamento de criativos quando eles são descobertos pela primeira vez em uma resposta de anúncio.

Cada criativo enviado cria uma operação de transferência de longa duração no servidor, cuja situação pode ser consultada. Quando a operação é concluída, ela resulta em um recurso de criativo no sistema. A resposta ao envio de um criativo contém o ID da operação que resultou da solicitação. O ID da operação resultante é incluído nas notificações do Cloud Pub/Sub que são enviadas quando a operação é concluída para mapear o criativo original que foi enviado. O ID da operação também pode ser usado para verificar o progresso da operação a qualquer momento.

Solicitações de criativos

Os dados são enviados à API como buffers de protocolo ou objetos JSON. Os buffers de protocolo, enviados usando o gRPC, são recomendados porque são necessários para consumir as notificações do Pub/Sub, e a descodificação do JSON adicionou complicações devido aos campos google.protobuf.Any na resposta.

Respostas criativas

Em caso de sucesso, o servidor retorna uma resposta de buffer de protocolo ou JSON, dependendo do tipo de solicitação. A resposta contém o nome da operação de transferência recém-criada e os detalhes dela.

No envio inicial, alguns dos metadados associados à operação podem estar vazios e o resultado pode não estar presente. Quando a operação for concluída, o resultado será preenchido com o recurso de criativo (ou um erro), e os metadados terão informações sobre o status de transferência.

Os metadados precisam ser desserializados de um proto Any para o CreateCreativeOperationMetadata, e a resposta (se presente) precisa ser desserializada para o proto Creative.

Biblioteca de cliente para acessar a API

Siga estas etapas para fazer a integração com a API:

Faça o download das dependências do buffer de protocolo e mova toda a pasta google para o diretório src. Isso pode ser pulado se você estiver usando o Google Cloud App Engine.
Use o plug-in protoc para gerar o código gRPC do arquivo proto e coloque o código gerado no diretório relevante.
Crie um novo arquivo proto para o proto retornado na notificação do Pub/Sub. Repita a etapa anterior para gerar o código do proto.
Use o gRPC para fazer solicitações à API:
1. Receba as credenciais padrão com os seguintes escopos:
https://www.googleapis.com/auth/video-ads,

https://www.googleapis.com/auth/pubsub
1. Envie a solicitação para o Creative Ingest.
- Conecte-se a dai.googleapis.com:443 usando as credenciais padrão.
- Crie um stub de cliente para o serviço de transferência de criativos usando o código gerado pelo protótipo do gRPC.
- Chame CreateCreative usando o stub do cliente.
Opcionalmente, crie um stub para o serviço de operações usando o código gRPC de operações de longa duração, incluído no diretório googleapis baixado na etapa 2, que pode ser usado para receber o status de uma determinada operação (GetOperation).
Verifique as notificações do Pub/Sub:
1. Use a biblioteca de cliente do Pub/Sub ou o gRPC para se conectar ao serviço do Pub/Sub e pesquisar notificações do Pub/Sub publicadas no tópico fornecido.
2. Desempacote a mensagem do Pub/Sub no proto da etapa 4.
3. Sempre que uma operação de longa duração for retornada de chamadas para CreateCreative, GetOperation ou em uma notificação do Pub/Sub, desempacote os metadados em CreateCreativeOperationMetadata em discovery.proto do proto google.protobuf.Any e qualquer resposta em Creative em discovery.proto.

Exemplo de código de cliente 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)
}

Consulta de criativos durante a reprodução

Fluxograma do processo de pesquisa de criativos

O usuário solicita a exibição de conteúdo no YouTube ou na DAI.
O YouTube / DAI recebe uma resposta VAST de um sistema de anúncios de terceiros para inserir anúncios no conteúdo.
Os anúncios retornados são mapeados para criativos ingeridos anteriormente. Essas peças estão prontas para reprodução. Elas são extraídas da infraestrutura de vídeo do Google e reproduzidas para o usuário.

Documentos VAST modificados pelo parceiro

Quando uma resposta VAST é retornada pelo sistema de anúncios depois que o criativo é carregado na infraestrutura de vídeo do Google, o documento precisa conter uma referência ao criativo processado. O documento VAST precisa continuar incluindo os arquivos de mídia de um determinado criativo, mas não há garantia de que esses arquivos de mídia serão usados pelo sistema.

Há duas maneiras de fazer referência a um criativo processado em um documento VAST: adicionar um novo elemento UniversalAdId ao documento VAST 4+ ou adicionar uma extensão personalizada.

ID universal do anúncio

O gvRegistryID retornado pela API Video Creative Ingest é um ID universal público usado para identificar exclusivamente um criativo de vídeo em vários sistemas de anúncios. Esse ID precisa ser adicionado aos documentos VAST 4+ do sistema de anúncios. Assim, quando um documento VAST for recebido pelo YouTube ou pelo DAI, o ID poderá ser usado para mapear o criativo enviado originalmente.

Os sistemas de anúncios precisam adicionar um novo elemento UniversalAdId aos documentos VAST 4+ no nó "Creative". O atributo idRegistry precisa ser definido como "googlevideo" e o valor precisa ser o informado no status da notificação do criativo processado.

Confira a seguir um exemplo de documento VAST 4 com o novo ID universal do anúncio adicionado:

<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

Como o elemento ID universal do anúncio foi introduzido apenas no VAST 4.0, os mesmos dados precisam de uma extensão personalizada para serem expostos em documentos VAST com versão inferior a 4.0. Isso é feito usando um elemento CreativeExtension no elemento Creative da especificação VAST.

A nova extensão apresentada é uma extensão genérica ativada para permitir que qualquer valor de ID de publicidade universal seja preenchido. Nesse caso específico, o ID universal do anúncio pertence ao registro do googlevideo e o ID seria o ID do vídeo do 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>

A abordagem CreativeExtension também pode ser usada no VAST 4+ caso o UniversalAdId já esteja preenchido com um ID para um registro UniversalAdId diferente:

<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 Video Creative Ingest Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.