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

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

Dans cette rubrique, vous apprendrez comment gérer les points de repère et les balises publicitaires lorsque vous utilisez l'Insertion d'annonces côté serveur (SSAI) de Brightcove pour vos travaux de diffusion en direct.

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: "YWJjZGVmZ2g=",	// 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 :

  • Seul avail_in Les points de repère de type sont actuellement pris en charge dans l'entrée 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 en Live API utilisant le en envoyant une POST requête :

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

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

Champ Type Description
duration Entier Durée de la pause en secondes.

La durée du point de repère inséré doit être au moins deux fois la longueur des segments de la tâche. Voir le exemple de durée.
timecode Format SMPTE OPTIONNEL: Un code temporel au format SMPTE, HH:MM:SS:FF (FF = images), pour spécifier quand un ensemble de variables (paires clé/valeur) doit être transmis à ADServer.

S' il est omis, le point de repère sera inséré immédiatement.

Si vous utilisez la propriété Timecode, l'encodeur doit envoyer le code temporel SMPTE formatted (HH:MM:SS:FF) stocké dans la tc propriété via OnFI. Les codes temporels sont à partir du début du flux en direct.
ad_server_data Objet OPTIONNEL: Les paires clé/valeur que vous transmettez dépendent du serveur publicitaire que vous utilisez. Pour plus de détails, consultez la documentation de votre serveur publicitaire et le Ciblage d'annonces à l'aide de macros d'annonces section.

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

Types de balises
Type de balise Description
Load Lancé une fois par session et déclenché uniquement lorsque le manifeste de niveau supérieur est demandé
Play Le contenu a été demandé et le premier segment renvoyé
Heartbeat Durée cible (segment en secondes)
AdStart Annonce individuelle lancée
AdFirstQuartile Premier quartile publicitaire (25 %)
AdMidpoint Deuxième quartile publicitaire (50 %)
AdThirdQuartile Troisième quartile publicitaire (75 %)
AdComplete Annonce individuelle terminée
AdBreakStart La coupure publicitaire a commencé
AdBreakComplete la coupure publicitaire est terminée

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 de configuration des annonces
Variable
Description
session.session_id
identifiant de session unique
job.job_id
ID d'emploi unique
videocloud.video_id
Uniquement disponible pour les travaux créés avec une vidéo VideoCloud.
application_ad_configuration.description
valeur de l'application à la création de la session
random.int32
entier aléatoire 32 bits signé
random.int64
entier aléatoire 64 bits signé
random.uint32
entier aléatoire 32 bits non signé
random.uint64
entier aléatoire 64 bits non signé
random.uuid
uuid aléatoire
server.timestamputc
temps d'époque en millisecondes lorsque l'appel de l'ads-api a été effectué
client.useragent
valeur de l'en-tête de l'agent utilisateur http lors de la création de la session
client.ipaddress
http x-forwarded-for valeur d'en-tête à la création de la session, si fournie, sinon l'adresse distante
client.referrer
valeur de l'en-tête du référent http lors de la création de la session (remarque : c'est l'orthographe correcte)
client.referer
Valeur de l'en-tête du référent http lors de la création de la session (orthographe http)
client.ipuaid
valeur de hachage de client.ipaddress et client.useragent
live.adbreak
(actuellement inutilisé)
live.adbreakdurationms
Durée de la coupure publicitaire en millisecondes
live.adbreakduration
Durée de la coupure publicitaire en secondes à virgule flottante double précision
live.adbreakdurationint
Durée de la coupure publicitaire en nombre entier de secondes
live.adbreak.timestamputc.wallclock
temps d'époque en millisecondes lorsque l'appel au serveur d'annonces a été effectué
live.adbreak.timestamputc.origin
temps d'époque en millisecondes à partir de la liste de morceaux d'origine. Cette valeur indique l'heure à laquelle le morceau de sortie de repère a été créé dans la liste de morceaux d'origine.
live.adbreak.timestamputc.session
temps d'époque en millisecondes à partir de la liste de morceaux ssai. Cette valeur indique l'heure du morceau de sortie dans la liste de morceaux ssai. Étant donné que le contenu adbreak et l'écart adbreak ne sont généralement PAS les mêmes, après le premier adbreak, live.adbreak.timestamputc.origin il est différent de live.adbreak.timestamputc.session . Cette valeur tient compte des ajustements de temps qui ont été effectués dans la SSAI liste de morceaux.

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. Le tableau suivant résume les variables de configuration des annonces SCTE-35.

Variables de configuration des annonces SCTE-35
Variable
Description
scte35_eventID
un identifiant d'événement unique transmis avec un message SCTE35.
scte35_programID
Un identifiant de programme unique transmis avec un message SCTE35.
scte35_availNum
Identifiant pour un temps d'épissure spécifique disponible pour les annonces, envoyé via un message SCTE35.
scte35_breakDuration
Durée de pause de la pause publicitaire, en termes de ticks de l'horloge de 90 kHz du programme, passée avec un message SCTE35.
scte35_spliceTime
Temps d'épissage pour une pause publicitaire, en termes de ticks de l'horloge de 90 kHz du programme, passé avec un message SCTE35.

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 jeu de balises, envoyez un POST demander:

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

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. Soumettre un PUT demander:

Méthode PUT
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
Entête X-API-KEY: your API KEY

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 jeux de balises pour un compte, soumettez un GET demander:

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

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 :

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

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 un GET demander:

Méthode GET
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
Entête X-API-KEY: your API KEY

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 jeu de balises, envoyez un DELETE demander:

Méthode DELETE
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
Entête X-API-KEY: your API KEY

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.

Configuration du point de repère élémentaire
Configuration du point de repère élémentaire