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. Facultatif : 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.

Régions prises en charge

Le SSAI est pris en charge dans les régions suivantes :

  • nous-ouest-2
  • nous-est-1
  • ap-sud-est-2
  • ap-nord-est-1
  • ap-sud-est-1
  • eu-central-1

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 Customer Success Manager pour obtenir une clé API associée à votre compte.

Créer une configuration d'annonce

Pour créer une nouvelle configuration d'annonce, envoyez une 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_compensation_disable": true,
        "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_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_compensation_disable": true,
          "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_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. Faites une 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_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_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 publicitaires d'un compte, soumettez une 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_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_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 à l'aide de celle-ci application_id en envoyant une 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_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 la configuration d'une annonce, envoyez une 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 envoyer un message « revenez tout de suite » ou tout autre contenu de votre choix.

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 une nouvelle ressource multimédia Slate, envoyez une POST demande :

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 multimédia Slate, envoyez une DELETE demande :

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": "https://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 toutes les sources multimédia Slate pour un compte en envoyant une GET demande :

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": "https://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": "https://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 l'équipe chargée de votre compte 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 un ensemble de publicités en une seule réponse
  • Règles relatives aux publicités DFP : regroupe toutes les publicités disponibles dans la réponse, y compris les publicités définies avant, à mi-parcours et après la diffusion
  • Smart XML : regroupe toutes les publicités disponibles dans la réponse, y compris les publicités définies avant, à mi-parcours et après la diffusion

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 le Créer une configuration d'annonce section).

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éez une configuration d'annonce, votre balise d'annonce ressemble 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 :

      https://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 la durée d'une pause publicitaire est inférieure à la durée MAXIMALE de l'URL de l'annonce (min_ad_duration=0&max_ad_duration=30000), si l'annonce est renvoyée plus longtemps que la pause 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.