API en direct : Points de repère et balises publicitaires avec SSAI

Aperçu

L'insertion d'annonces côté serveur vous (SSAI) permet d'afficher des annonces lors d'un événement de diffusion en direct à des heures spécifiées. Pour des informations générales, consultez le API en direct : Insertion d'annonces côté serveur (SSAI) document.

Points de repère

Les coupures publicitaires sont déclenchées par des points de repère, qui peuvent être spécifiés de deux manières :

• Envoyé à Brightcove par l'encodeur
• Points de repère immédiats créés via le Live API

De l'encodeur

Le système de diffusion en direct Brightcove peut interpréter les points de repère soumis par l'encodeur au format AMF :

  AMFDataList
  [0]:onCuePoint
  [1]:{Obj[]:
    time: 1.9889, //Difference from PTS of THIS packet to the first PTS of the 1st video frame in the adbreak
    name: "scte35",
    type: "event",
    ad_server_data: "eyJrZXkiOiJ2YWx1ZSJ9",	// optional introduced by Brightcove. It is a base64 encoded json map of parameters e.g. {"key":"value"}
    parameters: {Obj[]:
      type: "avail_in",
      duration: 12.0
    }
  }

Remarques :

• Comme les codes temporels sont exprimés en HH:MM:SS, il n'est pas possible de savoir de quel jour il s'agit. Cela peut entraîner des problèmes tels que l'envoi d'un point de repère à 23h55:00 pour qu'une pause publicitaire commence à 00:01:00 et que le serveur interprète cela comme s'il s'agissait d'il y a presque 24 heures. Brightcove a mis en œuvre le correctif suivant : pour les points de repère arrivant entre 23 h 50 h 00 et 00 h 00 uniquement, nous supposerons que vous planifiez une pause publicitaire pour le jour suivant.
• Il est possible d'empiler jusqu'à 128 marqueurs dans une seule demande, mais compte tenu des règles de "report" expliquées ci-dessus, les marqueurs ne peuvent pas être envoyés de cette manière pour le jour suivant.
• Les timecodes SMPTE étant associés au flux, il est possible qu'un cue arrive après l'heure prévue dans le flux. Brightcove autorise une tolérance de 5 secondes après le signal pour l'insertion d'un point de repère.
• Seuls avail_in les points avail_out de repère et de type sont actuellement pris en charge dans les entrées RTMP.
• Les points de repère SCTE-35 sont pris en charge dans les entrées RTP et SRT.

Insertion manuelle de points de repère

Vous pouvez créer des points de repère immédiats pour une tâche ou un groupe redondant à l'aide du Live API en envoyant une POST demande :

Incluez un corps de requête spécifiant les éléments suivants :

Exemple de durée

La durée du point de repère inséré doit être au moins deux fois la longueur des segments dans le travail.

Par exemple, l'insertion d'un point de repère de 10 secondes dans une tâche avec "segment_seconds"=4, fonctionnera correctement. Cependant, l'insertion du même point de repère dans un travail avec "segment_seconds"=6 entraînera l'erreur suivante :

  "error": "The parameter duration should be greater than
    or equal to (2 * target duration) of the job"
 

Exemple de corps de requête

  {
    "duration": 30,
    "timecode": "15:50:49:16",
    "ad_server_data" : {
    "adbreakid": 12312
    "breaktheme": "fitness"
    }
  }

Remarques

1. Les encodeurs logiciels tels que Wirecast et OBS ne prennent pas en charge l'envoi de timecode via OnFI paquets dans le flux RTMP
2. Les encodeurs matériels élémentaires prennent en charge l'envoi de timecode via OnFI paquets dans le flux RTMP

Exemple de réponse

  {
    "id": "Job_ID",
    "cue_point": {
      "id": "adBreak-2f58393ada1442d98eca0817fa565ba4",
      "duration": 30,
      "accuracy": "segment", [Can be segment or frame ]
      "inserted_at": "2017-07-21T09:30:46.307Z" [ Time when the cue point was inserted in the stream]
    },
  }

Balises

Les balises sont des points de données sur la lecture envoyés à des analyses tierces pour savoir si et combien d'annonces ont été lues. Dans cette section, nous allons examiner les types de balise qui peuvent être définis à l'aide des variables Live API, et qui peuvent être utilisées pour fournir les données. La section suivante détaillera les requêtes API utilisées pour créer et gérer des ensembles de balises.

Types de balises

Variables balise/annonce

Le tableau ci-dessous montre les variables que vous pouvez utiliser pour fournir des données pour les URL de balise. Pour inclure une variable, entourez-la d'accolades doubles, comme ceci : {{job.job_id}}. Voir la section suivante sur la gestion des jeux de balises pour des exemples complets.

Variables publicitaires SCTE-35

Les Société des ingénieurs en télécommunications par câble (SCTE) définit une norme pour l'insertion dynamique d'annonces pour les flux en direct. Un marqueur publicitaire SCTE-35 définit l'heure et la durée pendant lesquelles une publicité peut être insérée dans le flux.

Si elles sont analysées à partir de SCTE-35, les variables de configuration suivantes peuvent être appliquées à vos balises publicitaires :

Dans le cadre des manifestes HLS, les messages SCTE-35 sont également base64 avec les variables en JSON. Par exemple :

{"scte35_eventID": somevalue, "scte35_programID": somevalue}

Gestion des jeux de balises

Cette section fournit des détails sur les demandes d'API pour gérer les ensembles de balises. Voir la section précédente pour les types et les variables de balise.

Pour ajouter un jeu de balises à une tâche en direct, créez d'abord le jeu de balises, puis incluez l'ID lorsque vous créez la tâche, comme ceci :

{
  "live_stream": true,
  "region": "us-west-2",
  "reconnect_time": 30,
  "ad_insertion": true,
  "beacon_set": "beacon_set_id", ...

Créer un jeu de balises

Pour créer un ensemble de balises, envoyez une POST demande :

Exemple de corps de requête

{
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Load"
      },
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Play"
      }
    ]
  }

Exemple de réponse

{
    "beacon_set": {
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Load"
    },
    {
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Play"
    }],
    "beacon_set_id": "Inserted Beacon Set ID",
    "account_id": "USER's ACCOUNT ID"
    }
    "inserted": true
  }

Mettre à jour un jeu de balises

La mise à jour d'un jeu de balises est similaire à la création d'un. Soumettez une PUT demande :

Exemple de corps de requête

{
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX/play",
      "beacon_type": "Play"
      }
    ]
  }

Exemple de réponse

{
    "beacon_set": {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
      }],
      "updated_beacon_set": {
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
          "beacon_url": "https://myserver.com/beaconRX/load",
          "beacon_type": "Load"
        },
        {
          "beacon_url": "https://myserver.com/beaconRX/play",
          "beacon_type": "Play"
        }],
        "account_id": "User's Account ID"
      }
    }
  }

Obtenez des ensembles de balises

Pour récupérer les ensembles de balises d'un compte, soumettez une GET demande :

Exemple de réponse

[{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

Obtenir des ensembles de balises pour l'utilisateur demandeur

Vous pouvez également obtenir les jeux de balises pour le compte de l'utilisateur demandeur sans inclure l'identifiant du compte dans l'URL de la demande :

Exemple de réponse

[{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

Obtenir une balise définie par id

Pour récupérer une seule balise définie par son identifiant, soumettez une GET demande :

Exemple de réponse

{
      "account_id": "User account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_type": "Load",
        "beacon_url": "https://myserver.com/beaconRX2/load"
    },
    {
      "beacon_type": "Play",
      "beacon_url": "https://myserver.com/beaconRX2/play"
    }]
  }

Supprimer un jeu de balises

Enfin, pour supprimer un ensemble de balises, envoyez une DELETE demande :

Exemple de réponse

La réponse ressemblera à ceci :

{
    "beacon_set_id": "Beacon set ID",
    "deleted": true
  }

Annexe

Vous trouverez ci-dessous une capture d'écran montrant un exemple de configuration de point de repère pour l'encodeur Elemental.