Esta página se ha movido; se le dirigirá a la nueva ubicacion en 3 segundos. ¡Actualiza tus marcadores!

API de Brightcove Live: Inserción de anuncios en el servidor (SSAI)

Este tema le muestra cómo configurar la inserción de anuncios del lado del servidor (SSAI) para sus trabajos de transmisión en vivo.

Descripción general

SSAI le permite mostrar anuncios durante un evento de transmisión en vivo en momentos específicos. Las principales características incluyen:

  • Inserte anuncios utilizando puntos de referencia enviados desde su codificador o cree un punto de referencia instantáneo utilizando el Live API
  • Ingesta elementos de "lista" para completar el tiempo publicitario no utilizado
  • Evite los bloqueadores de anuncios con anuncios que están integrados en la transmisión en vivo en el lado del servidor.

Para crear una transmisión en vivo con anuncios del lado del servidor, siga estos pasos:

  1. Revise la información general sobre la API en vivo
  2. Cree una configuración de anuncios en vivo. También puedes hacer esto en Estudio de Video Cloud. Consulte las secciones a continuación para obtener detalles sobre cómo administrar las configuraciones de sus anuncios mediante la API en vivo.
  3. Crear activos de pizarra. Si prefiere una interfaz de usuario, puede administrar pizarras en Studio.
  4. Opcional: Insertar puntos de referencia y balizas publicitarias.
  5. Ahora estás listo para crear una transmisión en vivo usando la API en vivo. Si prefiere utilizar Studio, puede implementar anuncios del lado del servidor en el módulo Live

Consulte el resto de este documento para obtener detalles sobre los encabezados personalizados, las variables de configuración de anuncios, el uso de DFP y macros de anuncios.

información general

La siguiente información pertenece a todas las API de Live con solicitudes SSAI.

URL base

La URL base para Live API con SSAI es:

    https://api.bcovlive.io/v1/ssai

Autenticación

La autenticación de solicitudes requiere un encabezado con una clave API:

    X-API-KEY: your API KEY

Comuníquese con su administrador de cuentas para obtener una clave API asociada a su cuenta.

Crea una configuración de anuncios

Para crear una nueva configuración de anuncios, envíe un POST solicitud de la siguiente manera:

Método POST
URL https://api.bcovlive.io/v1/ssai/applications
Encabezamiento X-API-KEY: your API KEY

Cuerpo de solicitud de muestra

    {
      "application_ad_configuration": {
        "ad_configuration_description": "Human readable description of the configuration",
        "ad_configuration_expected_response_type": "Dfp, Vast or SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

Respuesta de muestra

    {
      "application": {
        "account_id": "User Account ID",
        "application_description": "Human readable description of the ad application",
        "application_ad_configuration": {
          "ad_configuration_description": "Human readable description of the configuration",
          "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
          "ad_configuration_headers": {
            "X-Custom-Header-Rand": "{{random.int32}}",
            "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
          },
          "ad_configuration_headers_for_impressions": false,
          "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
          "ad_configuration_transforms": [
            {
              "xpath": "/",
              "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
            }
          ],
          "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
        },
        "application_id": "Application ID"
      },
      "inserted": true
    }

Actualizar una configuración de anuncios

Actualizar la configuración de un anuncio es muy similar a crear uno. Hacer una PUT solicitud de la siguiente manera:

Método PUT
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Encabezamiento X-API-KEY: your API KEY

Cuerpo de solicitud de muestra

    {
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp or Vast or SmartXML,
        "ad_configuration_headers": {
          "X-Custom-Header-Rand": "{{random.int32}}",
          "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

Respuesta de muestra

    {
      "account_id": "User Account ID",
      "application_description": "Human readable description of the ad application",
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_id": "Application ID"
    }

Obtenga todas las configuraciones de anuncios

Para recuperar todas las configuraciones de anuncios de una cuenta, envíe un GET solicitud de la siguiente manera:

Método GET
URL https://api.bcovlive.io/v1/ssai/applications/account/Account_ID
Encabezamiento X-API-KEY: your API KEY

Respuesta de muestra

    [
      {
        "application_id": "Application_ID_1",
        "application_description": "DFP Single Midroll",
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      },
      {
        "application_id": "Application_ID_2",
        "application_description": "Test DFP Single Midroll"
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [
        {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
        }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      }
    ]

Obtener una configuración de anuncios

También puede recuperar una configuración de anuncio específica por su application_id enviando un GET solicitud de la siguiente manera:

Método GET
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Encabezamiento X-API-KEY: your API KEY

Respuesta de muestra

    {
      "application_id": "Application_ID",
      "application_description": "Test DFP Single Midroll",
      "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
          }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
      },
      "account_id": "Account_ID"
    }

Eliminar una configuración de anuncios

Para eliminar una configuración de anuncios, envíe un DELETE solicitud de la siguiente manera:

Método DELETE
URL https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID
Encabezamiento X-API-KEY: your API KEY

Respuesta de muestra

    {
    "application_id": "Application_ID",
    "deleted": true
    }

Manejo de pizarras

Las pizarras son sus propios activos que se utilizan para llenar el tiempo publicitario no utilizado. Puede utilizar pizarras para proporcionar un mensaje "ya vuelvo" o cualquier contenido que desee.

A continuación, se muestran los detalles de las solicitudes de la API para agregar y administrar activos de lista.

Agregar recurso de lista

Para ingerir un nuevo recurso de fuente de medios de pizarra, envíe un POST pedido:

Método POST
URL https://api.bcovlive.io/v1/ssai/slates
Encabezamiento X-API-KEY: your API KEY

Cuerpo de solicitud de muestra

    {
      "source_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "account_id": "Account_ID [Optional]",
      "source_description": "User identifiable description for the slate  [Optional]"
    }

Respuesta de muestra

    {
      "media_source_asset_id": "New_UUID",
      "account_id": "Account_ID",
      "media_source_asset_default": false,
      "media_source_asset_type": "slate",
      "media_source_asset_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "media_source_asset_status": "transcoding"
      "media_source_asset_description": "User identifiable description for the slate"
    }

Eliminar recurso de lista

Para eliminar un recurso de fuente de medios de lista, envíe un DELETE pedido:

Método DELETE
URL https://api.bcovlive.io/v1/ssai/slates/slate/Slate_MSA_ID
Encabezamiento X-API-KEY: your API KEY

Respuesta de muestra

    {
      "media_source_asset_id": "MSA_UUID",
      "media_source_asset_type": "slate",
      "media_source_asset_url": "http://someS3urlpath/media.mp4",
      "media_source_asset_default": false,
      "media_source_asset_status": "ready",
      "account_id": "ACCOUNT_ID"
    }

Obtener activos de pizarra

Puede recuperar una matriz de todos los activos de fuente de medios de pizarra para una cuenta enviando un GET pedido:

Método GET
URL https://api.bcovlive.io/v1/ssai/slates/account/Account_ID
Encabezamiento X-API-KEY: your API KEY

Respuesta de muestra

    [
      {
      "media_source_asset_id": "MSA_UUID_1",
      "media_source_asset_type": "slate",
      "media_source_asset_default": false,
      "media_source_asset_url": "http://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      },
      {
      "media_source_asset_id": "MSA_UUID_2",
      "media_source_asset_type": "slate",
      "media_source_asset_default": true,
      "media_source_asset_url": "http://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      }
    ]

Notas sobre DFP

Si obtiene anuncios de DFP, a continuación, le indicamos algunos aspectos que debe tener en cuenta para ayudar a evitar problemas.

Etiqueta de anuncio

Cuando cree una etiqueta de anuncio para Live, asegúrese de seguir las pautas adecuadas e incluir /live . Ver el documento de DFP Cree una etiqueta de video maestra manualmente para conocer todos los detalles.

Concurrencia

Si espera una gran cantidad de simultaneidad, le recomendamos que hable con su equipo de cuentas de DFP.

Respuestas de anuncios únicos / múltiples

La singleadresponse y multiadresponse los parámetros no son utilizados actualmente por SSAI.

Vivir SSAI solo realiza una única llamada al servidor de anuncios y espera que la respuesta contenga todos los anuncios de la pausa, con la excepción de que seguirá los envoltorios de anuncios necesarios con un límite de 5 redireccionamientos por anuncio. Se aceptan los siguientes formatos de respuesta al anuncio y se analizarán de la siguiente manera:

  • VAST: respuesta única o grupo de anuncios en una única respuesta
  • Reglas de anuncios de DFP: agrega todos los anuncios disponibles en la respuesta, incluidos los anuncios definidos antes, durante y después del video.
  • XML inteligente: agrega todos los anuncios disponibles en la respuesta, incluidos los anuncios definidos antes, durante y después del video.

Encabezados personalizados para solicitudes de anuncios

La SSAI La plataforma puede pasar encabezados personalizados con las llamadas de anuncios y todas las balizas utilizadas por la plataforma de backend. Algunos servidores de anuncios como VideoPlaza requieren encabezados personalizados.

Los encabezados personalizados se especifican como un conjunto de pares clave-valor en un ad_configuration_headers objeto, que es parte del application_ad_configuration (ver el Crea una configuración de anuncios sección).

Notas

  • Los encabezados estándar se manejan de forma predeterminada, como:
    • X-Forwarded-For
    • X-Device-User-Agent
  • Los valores de encabezado pueden usar el variables de configuración de anuncios
  • Los valores de encabezado también pueden ser cadenas estáticas

Orientación de anuncios mediante macros publicitarias

Cuando creas una configuración de anuncio, la etiqueta de anuncio suele tener un aspecto similar a este:

      https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&
      num={{random.int32}}&ses={{session.session_id}}&IDFA={{deviceid}}&
      sitesection={{sitesection}}&breakid={{breakid}}&breaktheme={{breaktheme}}

Los elementos dentro de las llaves dobles son variables, también llamadas macros publicitarias, que Brightcove Live reemplazará con valores, si existen, cuando envíe la solicitud de anuncio.

Los valores de macro de anuncios se pueden proporcionar de las siguientes formas:

Usar información de encabezado

Información del encabezado, detallada en el Variables de configuración de anuncios sección anterior, está disponible para cualquier solicitud. Simplemente especifique las variables que desee con los nombres de clave adecuados en la configuración de su anuncio.

Agregar la URL

Se pueden agregar valores de sesión adicionales a la URL de la transmisión en vivo, como este:

      http://playback.bcovlive.io/e058d9f2737e18/us-west-2/NA/
      playlist.m3u8?deviceid=123456&sitesection=services"

Agregar URL de forma dinámica

Puede agregar URL dinámicamente, utilizando Javascript y Brightcove Player API:

      <!DOCTYPE html>
      <body>
        <video
        id="myPlayerID"
        data-video-id="5975635167001"
        data-account="3737230870001"
        data-player="tIG7lVKBm"
        data-embed="default"
        data-application-id
        class="video-js"
        controls
        width="640"
        height="360"></video>
        <script src="//players.brightcove.net/3737230870001/tIG7lVKBm_default/index.min.js"></script>

        <script type="text/javascript">
        var player = videojs("myPlayerID");

        player.one("loadstart", function(){
          var sourceUrl = player.currentSource();
          console.log(sourceUrl);
          var liveUrlWithParams = sourceUrl.src + "?player_width={width}&player_height={height}&deviceid={deviceid}";

          player.src([{
            "type": "application/vnd.apple.mpegurl",
            "src": liveUrlWithParams
          }]);
        });
      </script>

      </body>

Tenga en cuenta que los nombres de las claves en este ejemplo corresponden a los nombres de las variables en la etiqueta de anuncio que se muestra arriba.

Variables de configuración de anuncios

Las variables de configuración de anuncios, también conocidas como balizas, se pueden usar en solicitudes para administrar configuraciones de anuncios. Para obtener más detalles, consulte la API en vivo: Puntos de referencia y balizas publicitarias con SSAI documento.

Usar puntos de referencia manuales

Los valores para pausas publicitarias específicas se pueden enviar con la solicitud de inserción manual del punto de referencia. Para obtener más detalles, consulte la API en vivo: Puntos de referencia y balizas publicitarias documento.

Problemas conocidos

  • SSAI requiere que la transmisión de video en vivo tenga una pista de audio.
  • Si el VAST devuelto tiene el mismo ID de anuncio, el servidor no solicitará el contenido del anuncio, aunque la URL del anuncio utilice variables dinámicas para convertirla en una URL única. Esto hace no aplicar si utiliza DFP para anuncios.
  • Con DFP, si bien puede usar el mismo ID de anuncio, aún debe haber un ID de creatividad diferente; en otras palabras, no puede hacer un simple intercambio del MediaFile.

  • Si una pausa publicitaria tiene una duración menor que la duración MAX de la URL del anuncio (min_ad_duration = 0 & max_ad_duration = 30000), si el anuncio se devuelve más tiempo que la pausa publicitaria, no se reproducirá.

  • Los anuncios VPAID o en los que se puede hacer clic no son compatibles con Brightcove Live SSAI.

  • Cuando una pausa publicitaria tiene un tiempo restante más corto que los segundos del segmento de la transmisión y se muestra una lista, la lista se muestra para la duración de su segmento y la pausa publicitaria real será más larga de lo esperado.

  • Lo anterior puede provocar que una de las siguientes pausas publicitarias se reduzca por la duración de la latencia para intentar que la sesión vuelva al límite activo.

  • La primera vez que nuestro sistema ve el anuncio, no se reproducirá hasta que se transcodifique y esté listo para publicarse.
  • VMAP for Live SSAI no es compatible actualmente.