Cette page a été déplacée - vous serez dirigé vers le nouvel emplacement dans 3 secondes. Veuillez mettre à jour vos signets !

API Live Brightcove : Insertion d'annonces côté serveur (SSAI)

Cette rubrique explique comment configurer l'insertion d'annonces côté serveur (SSAI) pour vos travaux de diffusion en direct.

Aperçu

SSAI vous permet d'afficher des annonces lors d'un événement de diffusion en direct à des heures spécifiées. Les principales caractéristiques comprennent :

  • Insérez des annonces à l'aide de points de repère envoyés par votre encodeur ou créez un point de repère instantané à l'aide du Live API
  • Ingérer des éléments « slate » pour remplir tout temps publicitaire inutilisé
  • Évitez les bloqueurs de publicités avec des publicités qui sont cousues dans le flux en direct côté serveur

Pour créer une diffusion en direct avec des publicités côté serveur, procédez comme suit :

  1. Consultez les informations générales sur l'API Live
  2. Créer une configuration d'annonce en direct. Vous pouvez également le faire dans Studio Nuage Vidéo. Consultez les sections ci-dessous pour plus de détails sur la gestion de vos configurations d'annonces à l'aide de l'API Live.
  3. Créer des actifs d'ardoise. Si vous préférez une interface utilisateur, vous pouvez gérer les ardoises dans Studio.
  4. Optionnel: Insérer des points de repère et des balises publicitaires.
  5. Maintenant, vous êtes prêt à créer un flux en direct à l'aide de l'API Live. Si vous préférez utiliser Studio, vous pouvez implémenter des publicités côté serveur dans le module Live

Consultez le reste de ce document pour en savoir plus sur les en-têtes personnalisés, les variables de configuration des annonces, l'utilisation de DFP et les macros publicitaires.

Informations générales

Les informations suivantes concernent toutes les requêtes Live API avec SSAI.

URL de base

L'URL de base pour l'API Live avec SSAI est :

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

Authentification

L'authentification des requêtes nécessite un en-tête avec une clé API :

    X-API-KEY: your API KEY

Contactez votre gestionnaire de compte pour obtenir une clé API associée à votre compte.

Créer une configuration d'annonce

Pour créer une nouvelle configuration d'annonce, envoyez un POST demande comme suit :

Méthode POST
URL https://api.bcovlive.io/v1/ssai/applications
Entête X-API-KEY: your API KEY

Exemple de corps de requête

    {
      "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]"
    }

Exemple de réponse

    {
      "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
    }

Mettre à jour une configuration d'annonce

La mise à jour d'une configuration d'annonce est très similaire à la création d'une. Faire un PUT demande comme suit :

Méthode PUT
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Entête X-API-KEY: your API KEY

Exemple de corps de requête

    {
      "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]"
    }

Exemple de réponse

    {
      "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"
    }

Obtenez toutes les configurations d'annonces

Pour récupérer toutes les configurations d'annonces d'un compte, soumettez un GET demande comme suit :

Méthode GET
URL https://api.bcovlive.io/v1/ssai/applications/account/Account_ID
Entête X-API-KEY: your API KEY

Exemple de réponse

    [
      {
        "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"
      }
    ]

Obtenir une configuration d'annonce

Vous pouvez également récupérer une configuration d'annonce spécifique par son application_id en envoyant un GET demande comme suit :

Méthode GET
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Entête X-API-KEY: your API KEY

Exemple de réponse

    {
      "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"
    }

Supprimer une configuration d'annonce

Pour supprimer une configuration d'annonce, envoyez un DELETE demande comme suit :

Méthode DELETE
URL https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID
Entête X-API-KEY: your API KEY

Exemple de réponse

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

Gestion des ardoises

Les ardoises sont vos propres actifs utilisés pour remplir le temps publicitaire inutilisé. Vous pouvez utiliser des ardoises pour fournir un message « soyez de retour » ou tout contenu que vous aimez.

Vous trouverez ci-dessous des détails sur les demandes d'API pour ajouter et gérer les actifs de l'ardoise.

Ajouter un élément d'ardoise

Pour ingérer un nouvel élément de source multimédia Slate, soumettez un POST demander:

Méthode POST
URL https://api.bcovlive.io/v1/ssai/slates
Entête X-API-KEY: your API KEY

Exemple de corps de requête

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

Exemple de réponse

    {
      "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"
    }

Supprimer l'actif de l'ardoise

Pour supprimer une ressource de source multimédia Slate, envoyez un DELETE demander:

Méthode DELETE
URL https://api.bcovlive.io/v1/ssai/slates/slate/Slate_MSA_ID
Entête X-API-KEY: your API KEY

Exemple de réponse

    {
      "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"
    }

Obtenir des actifs d'ardoise

Vous pouvez récupérer un tableau de tous les actifs de la source multimédia de l'ardoise pour un compte en envoyant un GET demander:

Méthode GET
URL https://api.bcovlive.io/v1/ssai/slates/account/Account_ID
Entête X-API-KEY: your API KEY

Exemple de réponse

    [
      {
      "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"
      }
    ]

Remarques sur DFP

Si vous obtenez des annonces de DFP, voici quelques éléments à garder à l'esprit pour éviter les problèmes.

Balise publicitaire

Lorsque vous créez un tag d'emplacement publicitaire pour Live, assurez-vous de suivre les instructions appropriées et d'inclure /live . Consultez le document DFP Créer manuellement une balise vidéo principale pour plus de détails.

Concurrence

Si vous vous attendez à un niveau élevé de simultanéité, nous vous recommandons de contacter votre équipe chargée des comptes DFP.

Réponses d'annonces uniques/multiples

le singleadresponse et multiadresponse les paramètres ne sont pas actuellement utilisés par SSAI.

Live SSAI ne fait qu'un appel de serveur publicitaire unique et s'attend à ce que la réponse contienne toutes les annonces pour la pause, sauf qu'elle suivra tous les wrappers publicitaires nécessaires avec une limite de 5 redirections par annonce. Les formats de réponse d'annonce suivants sont acceptés et seront analysés comme suit :

  • VAST - Réponse unique ou espace d'annonces en une seule réponse
  • Règles publicitaires DFP - Agrège toutes les annonces disponibles dans la réponse, y compris les annonces pré, milieu et post-roll définies
  • XML intelligent - Regroupe toutes les annonces disponibles dans la réponse, y compris les annonces définies avant, mi- et post-roll

En-têtes personnalisés pour les demandes d'annonces

La SSAI plate-forme peut transmettre des en-têtes personnalisés avec les appels publicitaires et tous les balises utilisées par la plate-forme backend. Certains serveurs publicitaires tels que VideoPlaza nécessitent des en-têtes personnalisés.

Les en-têtes personnalisés sont spécifiés sous la forme d'un ensemble de paires clé-valeur dans un ad_configuration_headers objet, qui fait partie de application_ad_configuration (voir la section Créer une section de configuration publicitaire).

Remarques

  • Les en-têtes standard sont gérés par défaut tels que :
    • X-Forwarded-For
    • X-Device-User-Agent
  • Les valeurs d'en-tête peuvent utiliser le variables de configuration des annonces
  • Les valeurs d'en-tête peuvent également être des chaînes statiques

Ciblage d'annonces à l'aide de macros d'annonces

Lorsque vous créer une configuration d'annonce , votre tag d'emplacement publicitaire ressemblera généralement à ceci :

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

Les éléments à l'intérieur des accolades doubles sont des variables, également appelées macros publicitaires, que Brightcove Live remplacera par des valeurs, si elles existent, lors de l'envoi de la demande de publicité.

Les valeurs des macros publicitaires peuvent être fournies des manières suivantes :

Utilisation des informations d'en-tête

Les informations d'en-tête, détaillées dans le Variables de configuration des annonces section ci-dessus, est disponible pour toute demande. Spécifiez simplement les variables souhaitées avec les noms de clé appropriés dans votre configuration publicitaire.

Ajout de l'URL

Des valeurs de session supplémentaires peuvent être ajoutées à l'URL du flux en direct, comme ceci :

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

Ajout dynamique d'URL

Vous pouvez ajouter des URL de manière dynamique, à l'aide de Javascript et de l'API Brightcove Player :

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

Notez que les noms de clé dans cet exemple correspondent aux noms de variable dans le tag d'emplacement publicitaire indiqué ci-dessus.

Variables de configuration des annonces

Les variables de configuration des annonces, également appelées balises, peuvent être utilisées dans les demandes de gestion des configurations des annonces. Pour plus de détails, consultez le API en direct : Points de repère et balises publicitaires avec document SSAI.

Utilisation de points de repère manuels

Les valeurs de coupures publicitaires spécifiques peuvent être envoyées avec la demande d'insertion manuelle de point de repère. Pour plus de détails, consultez le API en direct : Points de repère et balises publicitaires document.

Problèmes connus

  • SSAI exige que la vidéo diffusée en direct ait une piste audio.
  • Si le VAST renvoyé a le même ID d'annonce, le serveur ne demandera pas le contenu de l'annonce, même si l'URL de l'annonce utilise des variables dynamiques pour en faire une URL unique. Cela fait ne pas s'appliquent si vous utilisez DFP pour les annonces.
  • Avec DFP, même si vous pouvez utiliser le même identifiant publicitaire, il doit toujours exister un identifiant créatif différent. En d'autres termes, vous ne pouvez pas effectuer un simple échange de MediaFile.

  • Si une coupure publicitaire a une durée inférieure à la durée MAX de l'URL de l'annonce (min_ad_duration=0&max_ad_duration=300000), si l'annonce est renvoyée plus longtemps que la coupure publicitaire, l'annonce ne sera pas diffusée.

  • Les annonces VPAID ou cliquables ne sont pas prises en charge pour Brightcove Live SSAI.

  • Lorsqu'une coupure publicitaire a un temps restant plus court que les secondes du segment du flux et qu'une ardoise est affichée, l'ardoise est affichée pour la durée de son segment et la coupure publicitaire réelle sera plus longue que prévu.

  • Ce qui précède peut entraîner la réduction de l'une des coupures publicitaires suivantes en fonction de la durée de latence, pour tenter de ramener la session à la limite du direct.

  • La première fois que l'annonce est vue par notre système, elle ne sera pas diffusée tant qu'elle n'aura pas été transcodée et prête à être diffusée.
  • VMAP pour Live SSAI n'est actuellement pas pris en charge.