Early ad break notification

Cómo usar la API de Early Ad Break Notification

Nota: Esta API aún se encuentra en versión beta. Si desea solicitar acceso al programa EABN, comuníquese con su administrador de cuentas.

La API de notificación anticipada de pausa publicitaria (EABN) te permite notificar a Google Ad Manager sobre la próxima pausa publicitaria con sus metadatos antes de que comience la pausa. Puedes enviar una solicitud de notificación hasta una hora antes de la pausa publicitaria. En esta guía, se explica cómo habilitar y usar la API de EABN, y los ejemplos de solicitudes y respuestas.

Precaución: Las solicitudes de EABN son inmutables, por lo que una vez que se crea una pausa, no se puede modificar. Las solicitudes posteriores para crear pausas publicitarias para el mismo evento se rechazarán hasta que la pausa aparezca en el manifiesto del evento.

Las llamadas realizadas a la API de EABN deben incluir la siguiente información:

  • Es el identificador de la transmisión en vivo correspondiente en la que se crea la pausa publicitaria. Este identificador puede ser uno de los siguientes:
  • La "clave del activo" de la transmisión en vivo
  • La “clave del activo personalizada” de la transmisión en vivo, que te permite administrar tu propio espacio de claves especificando tu propia cadena de identificador.
  • "Content Source ID" y "Content ID" de la transmisión en vivo

Nota: Debes tener habilitada la opción para usar este tipo de identificador. Para obtener más información, comunícate con tu administrador de cuentas.

  • Es la duración esperada de la siguiente pausa publicitaria. La duración debe ser lo más cercana posible a la duración real de la pausa publicitaria.

Además de estos campos obligatorios, también puedes enviar parámetros de segmentación personalizados, el nombre de la plantilla de un grupo de anuncios que deseas aplicar o datos del estado de salida SCTE35 (si están disponibles).

Requisitos previos

Para usar la API de EABN, debes crear una cuenta de servicio y agregarla a tu red de Google Ad Manager.

Crea una cuenta de servicio

Para crear una cuenta de servicio para llamar a la API de EABN, sigue estos pasos: - Si tienes una cuenta de Google Cloud, usa el módulo de IAM para crear una cuenta de servicio. Para obtener más información, consulta Crea y administra cuentas de servicio. - Si no tienes una cuenta de Google Cloud, sigue estos pasos para crear una en la Consola de APIs de Google:

  1. Crea un proyecto nuevo o selecciona uno existente.
  2. En la página Credenciales, haz clic en Administrar cuentas de servicio.
  3. En la página Cuentas de servicio, haz clic en CREAR CUENTA DE SERVICIO.
  4. En la página Crear cuenta de servicio, ingresa los detalles de la cuenta. Luego, haz clic en CREAR.

Una vez que hayas creado una cuenta de servicio, copia la clave JSON de la cuenta, que se usa para la autenticación.

Agrega tu cuenta de servicio a tu red de Google Ad Manager

Para agregar la cuenta de servicio a tu red, completa los pasos que se indican en Agrega un usuario de cuenta de servicio para acceder a la API.

Habilitar la API

Una vez que hayas creado la cuenta de servicio, proporciona la siguiente información a tu administrador de cuentas para habilitar la API para tu cuenta:

  • La dirección de correo electrónico de tu Cuenta de Google Cloud
  • Tu cuenta de servicio
  • Es el código de red de tu red de Google Ad Manager.

Una vez que tu administrador de cuentas haya habilitado la API, sigue estos pasos para habilitarla:

  1. En la biblioteca de APIs de Google, busca "API de video de Google Ad Manager".
  2. Haz clic en HABILITAR.

Nota: Si la API no aparece en los resultados de la búsqueda, comuníquese con su administrador de cuentas para confirmar que su cuenta esté habilitada para utilizar la API de DAI.

Cómo usar la API

Puedes llamar a la API de EABN con solicitudes JSON/REST.

Autorización

Para realizar llamadas autorizadas a la API de EABN, debes generar credenciales de cuenta de servicio de OAuth2 con la clave JSON de tu cuenta de servicio y el permiso https://www.googleapis.com/auth/video-ads. Si quieres obtener más información, consulta Usa OAuth 2.0 para aplicaciones de servidor a servidor.

Debes incluir el token de autorización resultante como un encabezado de autenticación para cada llamada a la API de EABN.

Cómo enviar una notificación de pausa publicitaria antes de lo planificado

Para enviar una notificación de pausa publicitaria anticipada, envía una solicitud POST a una de las tres URLs de EABN válidas, según cómo prefieras especificar la transmisión en vivo. En las siguientes secciones, se explican las diferencias entre las URLs y se proporcionan ejemplos de solicitudes y respuestas.

URL

Existen tres URLs válidas para la notificación de pausas publicitarias anticipadas. Puedes usar los tres tipos para crear una pausa publicitaria (POST) o para obtener la lista de pausas publicitarias asignadas (GET).

Para usar la clave de activo de una transmisión en vivo, haz lo siguiente:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Para usar la clave de activo personalizada de una transmisión en vivo, haz lo siguiente:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Para usar el enfoque de Content Source ID y Content ID, usa lo siguiente:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Para todos los parámetros:

  • network_code representa el código de tu red de Google Ad Manager.
  • asset_key representa la clave del activo que se muestra en la página de detalles de la transmisión en vivo.
  • custom_asset_key representa la clave del activo personalizada de tu transmisión en vivo.
  • content_source_id representa el ID de una fuente de contenido en Google Ad Manager.
  • content_id representa el ID de un fragmento de contenido en Google Ad Manager.

Nota: El par content_source_id/content_id especificado debe estar asociado a una transmisión en vivo en Google Ad Manager.

Cuerpo de la solicitud: Solo se usa para crear una pausa publicitaria (POST).

Objeto

expectedDuration

Obligatorio Es la duración de esta pausa publicitaria con el formato de duración estándar de Google (xx.xxxs, en el que xx.xxx es la cantidad de segundos)

customParams

Opcional Pares clave-valor que se incluirán en las solicitudes de anuncios de esta pausa para la segmentación de criterios personalizados en AM360, separados por

=

y se unieron

&

.
Ejemplo:

key=value&key2=value2,value3


Para obtener más información sobre la segmentación, consulta Cómo proporcionar parámetros de segmentación a tu transmisión.

podTemplateName

Opcional El nombre de la plantilla del grupo de anuncios

scte35CueOut

Opcional Datos codificados en Base-64 a partir del indicador de scte35. Puede incluir el

splice_insert()

o

time_signal()

bq load.
Ejemplos:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

Solicitudes de ejemplo

Crea una pausa publicitaria
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
Cuerpo de la respuesta

El cuerpo de la respuesta contiene todos los parámetros enviados en el objeto adBreak, así como un campo name adicional, que contiene el ID estándar de Google de la pausa publicitaria creada. Este campo se devuelve en el siguiente formato:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
Ejemplo de respuesta
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
Enumerar pausas publicitarias asignadas
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
Cuerpo de la respuesta

El cuerpo de la respuesta contiene las pausas publicitarias con un campo breakState adicional para cada pausa publicitaria asignada a la transmisión. El campo breakState admite los siguientes valores:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
Ejemplo de respuesta
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}