API de Video Creative Ingest

La API de transferencia de creatividades de video permite que los sistemas de anuncios de terceros transfieran de forma proactiva creatividades a YouTube y a los productos de la DAI. Este proceso garantiza que, cuando se toma una decisión sobre un anuncio desde un servidor de anuncios que no es de Google, las creatividades que se muestran estén listas y disponibles para publicarse en una transmisión de video de YouTube o DAI.

El proceso de transferir de forma proactiva creatividades de sistemas de anuncios de terceros implica dos partes principales. La primera parte permite que el sistema de anuncios de terceros proporcione creatividades a Google y supervise su progreso a medida que se transfieren a la infraestructura de video de Google. Una vez que las creatividades se transfieren correctamente, los identificadores se vuelven a pasar al sistema de anuncios.

En el segundo paso, el sistema de anuncios toma esos identificadores y los incluye en los documentos VAST que hacen referencia a la creatividad enviada, ya sea con el ID de anuncio universal (VAST 4.0 y versiones posteriores) o una extensión de creatividad de tipo "UniversalAdId". Cuando se encuentra un documento VAST del sistema de anuncios en el momento de la decisión en la DAI o en YouTube, el sistema de creatividades extrae esos identificadores del VAST y recupera la creatividad adecuada de la infraestructura de video de Google para insertarla en la reproducción.

Requisitos para el contenido multimedia

El contenido multimedia de las creatividades que se envía a la API debe cumplir con los siguientes criterios para garantizar que el sistema pueda procesarlo correctamente.

Tipos de medios

Google acepta los siguientes tipos de medios. Cualquier otro tipo de contenido multimedia podría rechazarse cuando se envíe.

  • 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

Propiedades multimedia

El contenido multimedia que envíes debe cumplir con los siguientes criterios:

  • El contenido multimedia debe tener al menos una pista de audio o video.
  • El contenido multimedia debe tener una duración razonable. Nada que exceda varios minutos.
  • El contenido multimedia debe tener audio o video que dure más de 1 segundo.
  • Si el contenido multimedia tiene audio, debe tener una configuración de canal de audio estándar, como mono, estéreo o sonido envolvente.

Envía creatividades para su transferencia

Diagrama de flujo del proceso de transferencia

  1. Un sistema de anuncios de terceros envía una solicitud HTTP a la API de Video Creative Ingest con una lista de archivos multimedia asociados con la creatividad.
  2. La API de Video Creative Ingest selecciona la creatividad de mayor calidad de la lista proporcionada y la descarga de la CDN.
  3. La API de Video Creative Ingest transfiere la creatividad descargada a la infraestructura de video de Google, lo que la pone a disposición de los productos de YouTube y DAI.
  4. Se vuelve a enviar una notificación de Pub/Sub al sistema de anuncios de terceros con el estado de la creatividad. La notificación indicará si se cargó correctamente para YouTube y la inserción de anuncios dinámicos. Si la carga de la creatividad falló, la notificación indicará la causa.

Sigue estos lineamientos cuando envíes creatividades.

Autenticación

Debes acceder a la API con una cuenta de servicio de Google Cloud. En el momento de la integración, se debe proporcionar información de la cuenta a Google para obtener la autorización adecuada.

Una vez que se proporcione la información de la cuenta a Google a través de creativeingestion@google.com, se otorgará acceso a los extremos de la API y a los temas de Cloud Pub/Sub que se usan para publicar notificaciones.

Para iniciar el proceso de autenticación, sigue estos pasos:

  1. Crea una cuenta de Google Cloud.
  2. Configura un proyecto con la cuenta para enviar solicitudes a la API de DAI.
  3. Dentro del proyecto, ve a la pestaña IAM y administración a la izquierda y crea una cuenta de servicio nueva. Las solicitudes se envían con la cuenta de servicio.

  4. Habilita la API de Pub/Sub y crea un solo tema de notificación de socio único al que la API publique todas las notificaciones de transferencia correctas y de error.

    Si tienes una política de organización de restricción de dominio, debes agregar el ID de cliente de Google a la lista de clientes permitidos. Comunícate con creativeingestion@google.com para obtener el ID. Una vez que lo hagas, podrás agregar principales (nuestra cuenta de robot) de las listas de clientes permitidas (el ID de cliente de la API) a las políticas de IAM (publicador de PubSub).

    Agrega video-creative-library-discovery@system.gserviceaccount.com como publicador de Pub/Sub al tema.

  5. Proporciona a creativeingestion@google.com la dirección de correo electrónico de la cuenta de servicio y el tema de PubSub para registrar esta información con la API.

  6. Habilita la API de DAI después de agregar la cuenta como consumidor de servicios.

  7. Para configurar tus credenciales de acceso a la API, haz lo siguiente:

    • Descargar credenciales de la cuenta de servicio: Haz clic en la cuenta de servicio en la sección Cuentas de servicio de la pestaña IAM y administración, haz clic en Crear clave y almacena las credenciales.

    • Autentica a quien llama a tu API. Establece GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso del archivo JSON. Consulta los ejemplos de código para autenticar clientes de gRPC en lenguajes comunes.

Transferencia de creatividades

Cada vez que una creatividad nueva está disponible en el sistema de anuncios de un socio, el sistema del socio debe enviarla a la API de transferencia de creatividades.

Cuando se envían creatividades nuevas a Google para que se carguen en la infraestructura de video, se deben proporcionar los mismos datos de creatividad que se incluyen en el documento VAST que genera el sistema de anuncios. Esto garantiza que el comportamiento de transferir creatividades de forma proactiva a Google tenga el mismo comportamiento que la carga de creatividades cuando se descubren por primera vez en una respuesta de anuncio.

Cada creatividad enviada crea una operación de transferencia de larga duración en el servidor cuyo estado se puede consultar. Una vez que la operación se completa correctamente, se obtiene un recurso de creatividad dentro del sistema. La respuesta para enviar una creatividad contiene el ID de la operación que resultó de la solicitud. El ID de operación resultante se incluye en las notificaciones de Cloud Pub/Sub que se envían cuando se completa la operación para volver a asignarla a la creatividad original que se envió. El ID de operación también se puede usar para verificar el progreso de la operación en cualquier momento.

Solicitudes de creatividades

Los datos se envían a la API como búferes de protocolo o como objetos JSON. Se recomiendan los búferes de protocolo, que se envían con gRPC, ya que son necesarios para consumir las notificaciones de Pub/Sub, y la transferencia de formato sin serialización del JSON tiene complicaciones adicionales debido a los campos google.protobuf.Any en la respuesta.

Respuestas creativas

Si se realiza correctamente, el servidor muestra una respuesta de Protocol Buffer o JSON, según el tipo de solicitud. La respuesta contiene el nombre de la operación de transferencia creada recientemente y los detalles de la operación.

En el envío inicial, es posible que algunos de los metadatos asociados con la operación estén vacíos y que el resultado no esté presente. Una vez que se completa la operación, el resultado se propaga con el recurso de creatividad (o un error), y los metadatos contienen información sobre el estado de transferencia.

Ten en cuenta que los metadatos se deben transferir de un proto Any al proto CreateCreativeOperationMetadata, y la respuesta (si está presente) se debe transferir al proto Creative.

Biblioteca cliente para acceder a la API

Sigue estos pasos para realizar la integración con la API:

  1. Descarga las dependencias del búfer de protocolo y mueve toda la carpeta google a tu directorio src. Puedes omitir este paso si usas Google Cloud App Engine.
  2. Usa el complemento protoc para generar código gRPC a partir del archivo proto y colocar el código generado en el directorio relevante.
  3. Crea un nuevo archivo proto para el proto que se muestra en la notificación de PubSub. Repite el paso anterior para generar código a partir del proto.

  4. Usa gRPC para realizar solicitudes a la API:

    1. Obtén credenciales predeterminadas con los siguientes permisos:

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

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

    1. Envía la solicitud a Transferencia de creatividades.
    • Conéctate a dai.googleapis.com:443 con las credenciales predeterminadas.
    • Crea un stub de cliente para el servicio de transferencia de creatividades con el código generado por proto de gRPC.
    • Llama a CreateCreative con el stub de cliente.

    De forma opcional, crea un stub para el servicio de operaciones con el código de gRPC de operaciones de larga duración, que se incluye en el directorio googleapis que descargaste en el paso 2, que se puede usar para obtener el estado de una operación determinada (GetOperation).

  5. Consulta Pub/Sub para ver las notificaciones:

    1. Usa la biblioteca cliente de PubSub o gRPC para conectarte al servicio de PubSub y sondear las notificaciones de PubSub publicadas en el tema proporcionado.

    2. Deserializa el mensaje de PubSub en el proto del paso 4.

    3. Cada vez que se muestra una operación de larga duración desde llamadas a CreateCreative, GetOperation o en una notificación de Pub/Sub, analiza los metadatos en CreateCreativeOperationMetadata en discovery.proto desde el proto google.protobuf.Any y cualquier respuesta en Creative en discovery.proto.

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

Búsqueda de creatividades durante la reproducción

Diagrama de flujo del proceso de búsqueda de creatividades

  1. Solicitudes del usuario para ver contenido en YouTube o DAI
  2. YouTube o la DAI obtienen una respuesta de VAST de un sistema de anuncios externo para que los anuncios se inserten en el contenido.
  3. Los anuncios que se muestran se asignan a las creatividades transferidas anteriormente. Esas creatividades están listas para la reproducción: se recuperan de la infraestructura de Google Video y se reproducen para el usuario.

Documentos de VAST modificados por el socio

Cuando se muestra una respuesta de VAST desde el sistema de anuncios después de que la creatividad se cargó correctamente en la infraestructura de video de Google, el documento debe contener una referencia a la creatividad procesada. El documento VAST debe seguir incluyendo los archivos multimedia de una creatividad determinada, pero no se garantiza que el sistema los use.

Existen dos maneras de hacer referencia a una creatividad procesada en un documento VAST: agregar un nuevo elemento UniversalAdId al documento VAST 4 o posterior, o bien agregar una extensión personalizada.

ID de anuncio universal

El gvRegistryID que muestra la API de Video Creative Ingest es un ID universal para el público que se usa para identificar de forma exclusiva una creatividad de video en varios sistemas de anuncios. Este ID se debe agregar a los documentos VAST 4+ del sistema de anuncios para que, cuando YouTube o la DAI reciban un documento VAST, se pueda usar el ID para volver a asignarlo a la creatividad enviada originalmente.

Los sistemas de anuncios deben agregar un nuevo elemento UniversalAdId a sus documentos VAST 4 y versiones posteriores en el nodo Creative. El atributo idRegistry debe establecerse en "googlevideo" y el valor debe ser el que se proporciona en el estado de la notificación de la creatividad procesada correctamente.

El siguiente es un documento VAST 4 de muestra con el nuevo ID de anuncio universal agregado:

<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

Dado que el elemento ID de anuncio universal solo se introdujo en VAST 4.0, los mismos datos necesitan una extensión personalizada para exponerse en documentos de VAST con una versión inferior a 4.0. Esto se hace con un elemento CreativeExtension debajo del elemento Creative de la especificación VAST.

La nueva extensión que se presentó es una extensión genérica habilitada para permitir que se propague cualquier valor de ID de anuncio universal. En este caso en particular, el ID de anuncio universal pertenecería al registro de googlevideo y el ID sería el ID de video de 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>

El enfoque de CreativeExtension también se puede usar en VAST 4 y versiones posteriores en el caso de que UniversalAdId ya esté propagado con un ID para un registro de 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>