Support kontaktieren | Systemstatus
Seiteninhalt

    Überblick: Zielgruppen-API

    In diesem Thema erfahren Sie mehr über die Zielgruppen-API. Mit der Zielgruppen-API können Sie von Brightcove Campaign erfasste Anzeigeereignis- und Lead-Daten abrufen.

    API-Referenz

    Siehe auch die API-Referenz.

    Basis-URL

    Die Basis-URL für die Zielgruppen-API lautet:

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

    Kontopfad

    In allen Fällen werden Anfragen für ein bestimmtes Video Cloud-Konto gestellt. Sie müssen der Basis-URL immer den Begriff "Konten" gefolgt von Ihrer Konto-ID hinzufügen:

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

    Authentifizierung

    Die Zielgruppen-API verwendet die Brightcove OAuth-Service Anrufe zu authentifizieren.

    Sie müssen zuerst die Client-Anmeldeinformationen abrufen (a client_id und client_secret). Dies ist eine einmalige Operation, die mit dem ausgeführt werden kann Benutzeroberfläche für OAuth-Anmeldeinformationen. Sie benötigen Berechtigungen für Audience / Read-Vorgänge:

    Required Permissions
    Erforderliche Berechtigungen

    Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth-Dienst mithilfe von abrufen cURL oder Postbote.

    Sie benötigen auch eine access_token, die mit dem client_id und erhalten wird client_secret und übergab einen Autorisierungsheader mit Ihrer API-Anfrage:

    Authorization: Bearer {access_token}

    Das access_token läuft nach fünf Minuten ab, daher müssen Sie für jede Anforderung eine erhalten oder überprüfen, ob Ihr Token noch gültig ist. Sehen Zugriffstoken erhalten Hier finden Sie eine ausführliche Erläuterung zum Abrufen von Zugriffstoken, einschließlich Codebeispielen.

    Fehlerbehandlung

    Wenn ein Fehler auftritt, antwortet die API mit einem der folgenden Statuscodes und einem entsprechenden Fehlercode im Antworttext:

    Statuscode Fehlercode Beschreibung
    400 BAD_REQUEST_ERROR Abfrageparameter sind ungültig
    401 UNAUTHORIZED_ERROR Das Zugriffstoken fehlt entweder, ist abgelaufen oder ungültig
    404 RESSOURCE NICHT GEFUNDEN Die URL existiert nicht
    429 REQUEST_THROTTLED_ERROR Der Benutzer hat die Richtlinie zur Ratenbegrenzung überschritten
    500 INTERNER FEHLER Ein interner Fehler ist aufgetreten
    504 GATEWAY_TIMEOUT_ERROR Der Server hat eine Zeitüberschreitung bei der Erfüllung Ihrer Anfrage

    Unten finden Sie ein Beispiel für einen Antworttext für einen Fehler:

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

    Parameter

    Es gibt verschiedene Parameter, die Sie zu Anforderungen hinzufügen können, um die abgerufenen Daten einzuschränken und zu filtern. Diese gelten für alle in den folgenden Abschnitten beschriebenen Anforderungstypen.

    Ergebnisse filtern

    Sie können die Ergebnisse mit dem filtern where Parameter. Die Syntax für Filter lautet:

    where=field1==value1;field2==value2

    Beispielsweise:

    where=video_id==123456789;video_name==test

    Kommas werden als logische ODERs und Semikolons als logische UNDs behandelt. Beispielsweise, where=video_id==1234,5678;video_name=test wird interpretiert als "wobei video_id = 1234 ODER 5678, AND video_name = test".

    Auswählen der zurückzugebenden Felder

    In der Anforderung kann eine Liste von Feldern angegeben werden, um die Ergebnisse auf diese Teilmenge von Feldern zu beschränken. Die Syntax für Felder lautet:

    fields=field1,field4

    Beispielsweise:

    fields=video_id,video_name

    Die Felder, nach denen Sie filtern und sortieren können, werden in den folgenden Abschnitten für jeden Anforderungstyp detailliert beschrieben.

    Datumsbereiche

    Datumsbereiche können in angegeben werden from und to Parameter und werden auf das Datum angewendet, an dem das Ansichtsereignis zuletzt aktualisiert wurde (das Feld update_at). Datumsbereiche können in folgenden Formaten angegeben werden:

    • Der Textwert now welches die aktuelle Zeit darstellt
    • Epochenzeitwerte in Millisekunden, z 1377047323000
    • Daten im internationalen Datumsformat nach ISO 8601: YYYY-MM-DD Format, wie z 2013-09-12. Für Daten in diesem Format:
      • Jeder angegebene Datumsbereich wird in UTC interpretiert
      • Die Uhrzeit für das Datum geben wird am angegebenen Datum als Mitternacht ( 00:00:00) interpretiert
    • Relative Daten: Sie können eines der beiden ausdrücken to und from Werte relativ zum anderen in d (Tage), h (Std), m (Minuten) oder s (sek). Beispielsweise:
      • from=2015-01-01&to=31d
      • from=-48h&to=now
      • from=-2d&to=now(gibt die gleichen Ergebnisse wie im vorherigen Beispiel)
      • from=-365d&to=2015-12-31
      • from=-10m&to=now

    Paging-Ergebnisse

    Das limit ist die Anzahl der zurückzugebenden Elemente (Standard: 25; Maximum: 100). offset ist die Anzahl der zu überspringenden Elemente (Standard: 0). Sie können verwenden limit und offset zusammen, um eine App zu erstellen, die durch die Ergebnisse blättert. Jeder enthält die limit, und offset count., die Sie verwenden können, um festzulegen die Iteration über die Gesamtergebnisse nach oben. In JavaScript können Sie beispielsweise die insgesamt erforderlichen Iterationen wie folgt abrufen:

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

    Ansichtsereignisse abrufen

    Führen Sie a aus, um Ansichtsereignisse in einem Konto abzurufen GET Anforderung an die Ressource view_events:

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

    Hier ist eine Beispielanfrage in 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}"

    Die Antwort sieht folgendermaßen aus:

    {
        "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
            }, ...
        }
    ]

    Felder zum Filtern und Auswählen

    All die Parameter kann mit verwendet werden view_event Anfragen.

    Hier ist eine Beispielanforderung in cURL unter Verwendung der Parameter:

    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}"

    Die folgenden Felder werden unterstützt für view_event Anfragen beim Filtern mit a where Klausel oder bei der Auswahl während a fields Klausel:

    Feld Beschreibung
    video_id Brightcove-Video-ID
    video_name Brightcove-Videoname
    tracking_id Benutzerdefinierte Tracking-ID
    external_id Die Marketo, Eloqua oder benutzerdefinierte GUID
    player_id Die ID des Brightcove-Players, der das Ansichtsereignis erstellt hat
    page_url Die URL der Seite, auf der das Ansichtsereignis erstellt wurde
    schaute Prozent sahen zu
    time_watched Sekunden des Videos gesehen
    hergestellt in Erstellungsdatum
    aktualisiert am Datum der letzten Aktualisierung
    is_synced Ein Boolescher Wert, der angibt, ob das Ansichtsereignis synchronisiert wurde oder nicht
    Ereignis_1 Benutzerdefinierte Ereignisse
    event_2
    event_3
    metric_1 Benutzerdefinierte Metriken
    metric_2
    metric_3

    Leads abrufen

    Führen Sie a aus, um Ansichtsereignisse in einem Konto abzurufen GET Anfrage an die view_events Ressource:

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

    Beispielantwort:

    {
        "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"
            }
        ]
    }

    Felder zum Filtern und Auswählen

    All die Parameter kann mit verwendet werden leads Anfragen.

    Hier ist eine Beispielanforderung in cURL unter Verwendung der Parameter:

    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}"

    Die folgenden Felder werden unterstützt für leads Anfragen beim Filtern mit a where Klausel oder bei der Auswahl während a fields Klausel:

    Feld Beschreibung
    video_id Brightcove-Video-ID
    external_id Die Marketo, Eloqua oder benutzerdefinierte GUID
    player_id Die ID des Brightcove-Players, der das Ansichtsereignis erstellt hat
    page_url Die URL der Seite, auf der das Ansichtsereignis erstellt wurde
    hergestellt in Erstellungsdatum
    email_address Die E-Mail-Adresse des Leads
    Vorname Der Vorname des Leads, falls angegeben
    Nachname Der Nachname des Leads, falls angegeben
    business_phone Die Telefonnummer des Leads, falls angegeben
    Land Das Land der Führung, falls angegeben
    firmaname Die Firma des Leads, falls vorhanden
    Industrie Die Branche, zu der die Führung gehört, wenn sie bereitgestellt wird

    Seite zuletzt aktualisiert am 21 Nov 2021