Broadsign Control API d'audience en temps réel

Le Broadsign Control API d'audience en temps réel permet aux développeurs d'intégrer les données d'audience.

Il existe deux principaux types de demandes :

Chaque type de demande a une macro d’action différente. Les autres macros sont les mêmes pour tous les types de requêtes.

L'API d'audience en temps réel comporte deux composants de mesure :

  • Le composant "prédiction" – Broadsign Control Administrator demande à l'API de fournir, en amont du créneau, le nombre estimé ou attendu de spectateurs pour sa diffusion. Cette demande peut être faite jusqu'à 35 secondes à l'avance et est incluse dans les demandes publicitaires de Broadsign Reach.
  • Le composant "mesure" – Broadsign Control Administrator demande à l'API de mesurer, pendant la lecture d'un créneau, le nombre réel de spectateurs. La mesure commence au début de la séquence et s'arrête une fois la lecture terminée. Ces informations sont rapportées avec des POP.

Le protocole d'enchères d'audience en temps réel est basé sur des requêtes HTTP(S) GET, émises par Broadsign Control Player avec une série de macros prises en charge. Les requêtes sont généralement envoyées environ 35 secondes avant le créneau programmatique prévu pour obtenir l'audience attendue à des fins d'enchères.

Exemple de demande d'enchères d'audience en temps réel dans Broadsign Reach

Copier 
GET $URL/{{action_name}}?expected_play_time={{expected_play_time}}&frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

Macros prises en charge

Le tableau suivant répertorie les macros et valeurs prises en charge pour les enchères d'audience en temps réel :

Nom de la macro Valeur substituée
{{action_name}} Champ obligatoire. Elle sera remplacée par la commande interne appropriée.
Macros communes à toutes les actions. Les valeurs substituées sont codées par URL.
{{expected_play_time}} L'heure d'affichage UTC attendue en millisecondes depuis l'époque.
{{frame_id}} L'ID du cadre Broadsign à partir duquel la requête provient.
{{campaign_id}} L'ID de campagne Broadsign à l'origine de la requête.
{{content_id}} L'ID du contenu Broadsign à partir duquel la requête provient.
{{content_name}} Le nom du Contenu Broadsign à l'origine de la requête.
{{expected_duration}} La durée prévue du contenu en millisecondes.
{{app_name}} "Broadsign Control Player"
{{player_id}} L'ID Broadsign Control Player.
{{display_unit_id}} L'ID de l'unité d'affichage Broadsign.
{{external_id}} L'ID de l'unité d'affichage externe Broadsign (pour les systèmes externes).
{{location_code}} Le code d'emplacement de l'unité d'affichage Broadsign.
{{latitude}} La Latitude de l'unité d'affichage Broadsign.
{{longitude}} La Longitude de l'unité d'affichage Broadsign.

Les macros d'URL peuvent être utilisées pour transformer dynamiquement l'URL demandée par Broadsign Control Player.

Reportez-vous à la spécification de l'API HTTP tierce pour tous les champs obligatoires.

Par exemple, si l'URL distante est :

Copier 
"http://localhost:10000/audience/{{action_name}}?frame_id={{frame_id}}&content_name={{content_name}}&player_id={{player_id}}"

et l'action interne actuelle est \"start\", frame_id est 33333, player_id est 555 et content_name est \"video\" , alors l'URL demandée par le lecteur sera :

Copier 
"http://localhost:10000/audience/start?frame_id=33333&content_name=video&player_id=555\n");

Format de réponse

Copier 
{
  "audience_pre": {
    "timestamp": 1429789106,
    "utc_offset": 7200,
    "total": 5,
    "metric": "3AI-F0",
    "gender": {male: 2, female: 3, unknown: 0},
    "age": [
      {
        "min": 0,
        "max": 17,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 18,
        "max": 35,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 36,
        "max": 99,
        "count": {male: 0, female: 1, unknown: 0}
      }
    ],
    "states": ["female"]
  }
}

La réponse devrait être fournie en codage json avec le jeu de caractères utf-8.

  • timestamp : en millisecondes depuis l'époque et doit être en UTC.
  • utc_offset : Le décalage, en secondes, entre UTC et le fuseau horaire fourni.
  • Les réponses HTTP des séries 3XX, 4XX et 5XX sont enregistrées comme une erreur. Les redirections ne sont pas suivies.
  • Sur une réponse 200 OK, le corps devrait être formé comme suit :
    • audience_pre : élément racine de réponse obligatoire
      • total : Obligatoire
      • gender tableau  : facultatif. Si spécifié, est utilisé pour les enchères
      • Tranches d'âge : Facultatif. Si fourni, utilisé en conjonction avec les genres pour les enchères
    • Tous les autres champs de la réponse sont ignorés.
    • Toutes les erreurs d'analyse, les attributs obligatoires manquants ou mal formés seront enregistrés et aucune information d'audience en temps réel ne sera enregistrée.

Le protocole d'audience de preuve de diffusion est également basé sur la requête HTTP(S) GET, avec une série de macros prises en charge. Pour la preuve de diffusion, les requêtes suivantes sont émises :

  • Une action « pre », dont le résultat est utilisé pour Broadsign Reach, et également injecté dans les pages HTML dans BroadSignObject.
  • Une requête « start » lorsque la copie publicitaire commence à être lue.
  • Une requête « stop » lorsque c’est fait.

Les autres macros sont les mêmes pour tous les types de requêtes.

Note : Le nombre total d'impressions est cumulatif lorsque les lecteurs sont configurés avec les fichiers d'audience statistique par plage horaire. Ceci s’applique également aux tranches d’âge et de sexe. Voir Broadsign POP Log.

Exemple de demande de preuve de diffusion pour le public Pre

Copier 
GET {{URL}}{{action_name}}?{{frame_id}}&{{content_name}}&{{player_id}}&{{expected_duration}}

Macros prises en charge

Voici les macros et valeurs prises en charge pour l'audience de preuve de diffusion START.

Nom de la macro Valeur substituée
{{action_name}} "pre"
Toutes les macros courantes (voir Exemple de demande d'enchères d'audience en temps réel dans Broadsign Reach ).

Par exemple:

Copier 
GET http://localhost:10000/audience/pre?frame_id=33333&content_name=video&player_id=555&expected_duration=10000

Exemple de demande pour le public de preuve de diffusion START

Copier 
GET $URL/{{action_name}}?expected_play_time={{expected_play_time}}&frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

Macros prises en charge

Voici les macros et valeurs prises en charge pour l'audience de preuve de diffusion START.

Nom de la macro Valeur substituée
{{action_name}} "start"
Toutes les macros courantes (voir Exemple de demande d'enchères d'audience en temps réel dans Broadsign Reach ).

Format de réponse à « START »

Copier 
{
  “status” : “ok”
}

La réponse devrait être fournie en codage json avec le jeu de caractères utf-8.

  • Les réponses HTTP des séries 3XX, 4XX et 5XX sont enregistrées comme une erreur. Les redirections ne sont pas suivies.
  • Sur une réponse 200 OK, le corps devrait être formé comme suit :
    • status : Obligatoire. Si une réponse autre que « ok » est donnée, elle est enregistrée et ignorée.
    • Tous les autres champs de la réponse sont ignorés.
    • Toutes les erreurs d'analyse, les attributs obligatoires manquants ou mal formés seront enregistrés.

Exemple de requête de preuve de diffusion Audience STOP

Copier 
GET $URL/{{action_name}}?frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

Macros prises en charge

Voici les macros et valeurs prises en charge pour l'audience de preuve de diffusion STOP.

Nom de la macro Valeur substituée
{{action_name}} "stop"
Toutes les macros courantes (voir Exemple de demande d'enchères d'audience en temps réel dans Broadsign Reach ).

Format de réponse à « STOP »

Copier 
{
  "audience_clip": {
    "timestamp": 9,
    "utc_offset": 7200,
    "duration": 3000,
    "total": 5,
    "metric": "3AI-F0"
    "gender": {male: 2, female: 3, unknown: 0},
    "age": [
      {
        "min": 0,
        "max": 17,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 18,
        "max": 35,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 36,
        "max": 99,
        "count": {male: 0, female: 1, unknown: 0}
      }
    ],
    "states": ["female"],
  }
}

La réponse devrait être fournie en codage json avec le jeu de caractères utf-8.

  • timestamp : en millisecondes depuis l'époque et, doit être en UTC.
  • utc_offset : Le décalage entre UTC et le fuseau horaire fourni en secondes.
  • Les réponses HTTP des séries 3XX, 4XX et 5XX sont enregistrées comme une erreur. Les redirections ne sont pas suivies.
  • audience_clip : élément racine de réponse obligatoire.
    • « total : Obligatoire. Cette valeur est enregistrée sous forme d'impressions dans la preuve de diffusion.
    • gender tableau : facultatif. Si spécifié, est utilisé pour la répartition par sexe dans la preuve de jeu.
    • Tranches d'âge : Facultatif. si fourni, est utilisé pour les répartitions par âge dans la preuve de jeu.
  • Tous les autres champs de la réponse sont ignorés.
  • Toutes les erreurs d'analyse, les attributs obligatoires manquants ou mal formés seront enregistrés et ignorés.