Contacter le support | État du système
Contenu de la page

    Aperçu: l'API Audience

    Dans cette rubrique, vous découvrirez l'API Audience. L'API Audience vous permet de récupérer les données d'événement et de prospect collectées par Brightcove Campaign.

    Référence de l'API

    Voir également la référence de l'API.

    URL de base

    L'URL de base de l'API Audience est :

    https://audience.api.brightcove.com/v1

    Chemin du compte

    Dans tous les cas, des demandes seront faites pour un compte Video Cloud spécifique. Vous devrez toujours ajouter le terme « comptes » suivi de votre ID de compte à l'URL de base :

    https://audience.api.brightcove.com/v1/accounts/{account_id} 

    Authentification

    L'API Audience utilise le service OAuth Brightcove pour authentifier les appels.

    Vous devrez d'abord obtenir les informations d'identification client (a client_id et client_secret). Il s'agit d'une opération unique qui peut être effectuée à l'aide de l' interface utilisateur des informations d'identification OAuth. Vous aurez besoin d'autorisations pour les opérations Audience/Lire :

    Required Permissions
    Autorisations requises

    Vous pouvez obtenir les informations d'identification du client directement à partir du service Brightcove OAuth en utilisant boucle ou Facteur.

    Vous aurez également besoin d'un access_token, qui est obtenu en utilisant le client_id et client_secret et transmis dans un en-tête Autorisation avec votre requête API :

    Authorization: Bearer {access_token}

    Le access_token expire après cinq minutes, vous devez donc en obtenir un pour chaque requête, ou vérifier pour vous assurer que votre jeton est toujours valide. Voir Obtenir des jetons d'accès pour une explication détaillée de la façon d'obtenir des jetons d'accès, y compris des exemples de code.

    Traitement des erreurs

    Si une erreur se produit, l'API répondra avec l'un des codes d'état suivants et un code d'erreur correspondant dans le corps de la réponse :

    Code d'état Code d'erreur Description
    400 BAD_REQUEST_ERROR Les paramètres de requête sont invalides
    401 UNAUTHORIZED_ERROR Le jeton d'accès est absent, a expiré ou n'est pas valide
    404 RESOURCE_NOT_TROUVÉ L'URL n'existe pas
    429 REQUEST_THROTTLED_ERROR L'utilisateur a dépassé la stratégie de limitation des taux
    500 INTERNAL_ERROR Une erreur interne s'est produite
    504 GATEWAY_TIMEOUT_ERROR Le serveur a expiré lors de la satisfaction de votre demande

    Voici un exemple de corps de réponse pour une erreur :

    [
       {
        "error_code": "UNAUTHORIZED_ERROR",
        "message": "Permission denied"
       }
    ]

    Paramètres

    Il existe plusieurs paramètres que vous pouvez ajouter aux requêtes pour limiter et filtrer les données récupérées. Ceux-ci s'appliquent à tous les types de demandes décrits dans les sections qui suivent.

    Filtrage des résultats

    Vous pouvez filtrer les résultats à l'aide du where paramètre. La syntaxe des filtres est la suivante :

    where=field1==value1;field2==value2

    Par exemple :

    where=video_id==123456789;video_name==test

    Les virgules sont traitées comme des RO logiques et des points-virgules comme des PAD logiques. Par exemple, where=video_id==1234,5678;video_name=test est interprété comme « où video_id = 1234 OR 5678, AND video_name = test ».

    Sélection des champs à renvoyer

    Une liste de champs peut être spécifiée dans la demande afin de limiter les résultats à ce sous-ensemble de champs. La syntaxe des champs est la suivante :

    fields=field1,field4

    Par exemple :

    fields=video_id,video_name

    Les champs que vous pouvez filtrer et trier sont détaillés pour chaque type de demande dans les sections suivantes.

    Plages de dates

    Les plages de dates peuvent être spécifiées dans from et to les paramètres et sont appliquées à la date de la dernière mise à jour de l'événement view (champ updated_at). Les plages de dates peuvent être indiquées dans les formats suivants :

    • La valeur de texte now qui représente l'heure actuelle
    • Les valeurs temporelles de l'époque en millisecondes, telles que 1377047323000
    • Dates exprimées dans la norme ISO 8601 format international de date: YYYY-MM-DD format, tel que 2013-09-12. Pour les dates exprimées dans ce format :
      • Toute plage de dates spécifiée sera interprétée en UTC
      • L'heure de la date donnée sera interprétée comme minuit ( 00:00:00) à la date spécifiée
    • Dates relatives : vous pouvez exprimer l'une ou l'autre des to et from valeurs par rapport à l'autre dans d (jours), h (les heures), m (minutes), ou s (seconde). Par exemple :
      • from=2015-01-01&to=31d
      • from=-48h&to=now
      • from=-2d&to=now(donnera les mêmes résultats que l'exemple précédent)
      • from=-365d&to=2015-12-31
      • from=-10m&to=now

    Résultats de pagination

    limit Le nombre d'articles à retourner (par défaut: 25 ; maximum: 100). offset est le nombre d'éléments à ignorer (par défaut: 0). Vous pouvez utiliser limit et offset ensemble pour créer une application qui page à travers les résultats. Chacun inclut le limit, offset, et count., que vous pouvez utiliser pour configurer l'itération sur les résultats totaux. Par exemple, en JavaScript, vous pouvez obtenir les itérations totales requises comme ceci :

    // response is the JSON-parsed response from the first request
    var totalRequests = Math.ceil(response.count / response.limit)

    Récupération des événements de vue

    Pour récupérer des événements de vue dans un compte, effectuez une GET demande à la ressource view_events :

    https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events

    Voici un exemple de demande dans cURL

    curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
      -H "Authorization: Bearer {token}"

    La réponse ressemblera à ceci :

    {
        "count": 27,
        "limit": 25,
        "offset": 0,
        "result": [
            {
                "created_at": "2016-04-25T18:30:21.651Z",
                "page_url": "http://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
                "player_id": "V1s6NOwRx",
                "time_watched": 2,
                "updated_at": "2016-04-25T18:30:21.651Z",
                "video_id": "4842718056001",
                "video_name": "Horses Heading to the Track",
                "watched": 19
            },
            {
                "created_at": "2016-04-25T18:31:55.071Z",
                "page_url": "http://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
                "player_id": "BkgFuzyhg",
                "time_watched": 15,
                "updated_at": "2016-04-25T18:32:00.879Z",
                "video_id": "4842718056001",
                "video_name": "Horses Heading to the Track",
                "watched": 99
            }, ...
        }
    ]

    Champs de filtrage et de sélection

    Tous les paramètres peuvent être utilisés avec des view_event requêtes.

    Voici un exemple de requête dans cURL en utilisant les paramètres :

    curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
      -H "Authorization: Bearer {token}"

    Les champs suivants sont pris en charge pour les view_event requêtes lors du filtrage avec une where clause ou lors de la sélection pendant une fields clause :

    Champ Description
    video_id ID vidéo Brightcove
    nom_video_ Nom de la vidéo Brightcove
    tracking_id ID de suivi personnalisé
    external_id Le Marketo, Eloqua ou GUID personnalisé
    player_id ID du lecteur Brightcove qui a créé l'événement view
    page_url URL de la page où l'événement view a été créé
    regardait Pourcentage regardé
    time_watched Secondes de la vidéo regardée
    created_at Date de création
    updated_at Date de dernière mise à jour
    is_syncé Un booléen indiquant si l'événement view a été synchronisé ou non
    event_1 Événements personnalisés
    event_2
    event_3
    metric_1 Mesures personnalisées
    metric_2
    metric_3

    Récupération des pistes

    Pour récupérer des événements de vue dans un compte, effectuez une GET demande à la view_events ressource :

    https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

    Exemple de réponse :

    {
        "count": 2,
        "limit": 25,
        "offset": 0,
        "result": [
            {
                "created_at": "2016-06-30T12:57:11.283Z",
                "email_address": "bbailey@brightcove.com",
                "first_name": "Bob",
                "last_name": "Bailey",
                "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
                "player_id": "Hk4TBqzL",
                "video_id": "4997275041001"
            },
            {
                "created_at": "2016-06-30T12:57:33.301Z",
                "email_address": "rcrooks@brightcove.com",
                "first_name": "Robert",
                "last_name": "Crooks",
                "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
                "player_id": "Hk4TBqzL",
                "video_id": "4997275041001"
            }
        ]
    }

    Champs de filtrage et de sélection

    Tous les paramètres peuvent être utilisés avec des leads requêtes.

    Voici un exemple de requête dans cURL en utilisant les paramètres :

    curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
      -H "Authorization: Bearer {token}"

    Les champs suivants sont pris en charge pour les leads requêtes lors du filtrage avec une where clause ou lors de la sélection pendant une fields clause :

    Champ Description
    video_id ID vidéo Brightcove
    external_id Le Marketo, Eloqua ou GUID personnalisé
    player_id ID du lecteur Brightcove qui a créé l'événement view
    page_url URL de la page où l'événement view a été créé
    created_at Date de création
    adresse email_ L'adresse e-mail du responsable
    nom_prénom Le prénom du plomb s'il est fourni
    nom_last_ Le nom de famille du plomb, s'il est fourni
    téléphone_business_ Le numéro de téléphone de la piste s'il est fourni
    country Le pays du chef de file s'il est fourni
    nom_entreprise_ La société du plomb si elle est fournie
    industrie L'industrie à laquelle appartient le plomb s'il est fourni

    Dernière mise à jour de la page le 10 Dec 2021