Media-Bridge-API

Die Media-Bridge-API ermöglicht es Integratoren, Medienobjekte wie Video- und Audiodateien sowie Mediennutzungsdaten nach HubSpot zu übertragen. Außerdem werden mit ihr die folgenden Funktionen im HubSpot-Account des Benutzers erstellt: 

  • Module zum Einbetten von Medienobjekten in die Drag-&-Drop-Editoren von HubSpot für Seiten und E-Mails. 
  • CRM-Chronik-Events, die zeigen, wann Interessenten oder Kunden mit Videos, Audio und anderen Medientypen interagiert haben. 
  • Segmentierte Listen für zielgerichtete und personalisierte Erlebnisse.
  • Workflows zur Automatisierung von Interaktionen, basierend auf Mediennutzungs-Events.
  • Berichte zur Messung der Auswirkungen von Mediaelementen.

Die Media Bridge verwendet sowohl benutzerdefinierte Objekte als auch „Vereinheitlichte Events“, das Event-Tracking-System von HubSpot. Dies bedeutet, dass Sie sowohl mithilfe der Media-Bridge-API als auch der API für benutzerdefinierte Objekte Ihre Integration erstellen können. 

Die Media-Bridge-API verwenden

Sie benötigen einen HubSpot-Entwickler-Account, um Ihre Media-Bridge-App zu registrieren und Ihre ersten Medienobjektdefinitionen einzurichten, bevor Sie Ihre App mit dem Account eines HubSpot-Benutzers verknüpfen. 

Ihre Medienobjektdefinitionen erstellen und anpassen

Um ein Medienobjekt zu definieren, führen Sie eine POST-Anfrage an /media-bridge/{appId}/settings/object-definitions durch. Sie verwenden den mediaTypes-Parameter, um das Objekt zu definieren: VIDEO, AUDIO, DOCUMENTIMAGE oder OTHER

Nachdem Sie Ihre Medienobjekte definiert haben, erstellen und ändern Sie die Medienobjekteigenschaften, indem Sie eine PATCH-Anfrage an/media-bridge/v1/{appId}/schemas/{objectType} und eine POST-Anfrage an /media-bridge/v1/{appId}/properties/{objectType} durchführen. 

Alle API-Aufrufe enthalten Ihre Entwickler-Account-ID als portalID-Abfrageparameter. 

Ihre Media-Bridge-App mit dem Account eines HubSpot-Benutzers verknüpfen

Um Ihre Media-Bridge-App mit dem Account eines HubSpot-Benutzers zu verknüpfen, müssen Sie für diese eine App-Definition im Account Ihres HubSpot-Entwicklers erstellen. App-Definitionen umfassen:

  • Details wie das Logo und den Text, das bzw. der dem HubSpot-Benutzer angezeigt werden soll, wenn Ihre Integration versucht, eine erste Verknüpfung zu dessen Account zu erstellen.
  • Bereiche, die Ihre Integration im HubSpot-Account des Benutzers benötigt. 

So verknüpfen Sie Ihre Media-Bridge-App mit dem Account eines HubSpot-Benutzers: 

  • Erstellen Sie eine Anwendungsdefinition in Ihrem Entwickler-Account für die Media-Bridge-App.
  • Fügen Sie beim Definieren Ihrer Anwendung die folgenden Bereiche hinzu: 
    • media_bridge.read
    • media_bridge.write
  • Verwenden Sie die OAuth-Authentifizierung, wenn Sie Aufrufe Ihrer App authentifizieren. Erfahren Sie mehr über Authentifizierungsmethoden.

So überprüfen Sie, ob die App korrekt im Portal eines Kunden installiert ist:

  • Besuchen Sie http://app.hubspot.com/media-bridge-demo/{accountId}. 
  • Klicken Sie oben rechts auf das Dropdown-Menü „App“ und wählen Sie Ihre Media-Bridge-App aus. 
  • In der App können Sie die von der App unterstützten Medientypen anzeigen und Beispielmedien erstellen.

Sobald die Media-Bridge-App im Kundenportal installiert wurde, können Sie:

Create your media objects

Nachdem Sie Ihre Medienobjektdefinitionen erstellt und Ihre Media-Bridge-App im Account eines Benutzers installiert haben, können Sie das OAuth-Token verwenden, um Medienobjekte im Account zu erstellen und zu ändern. Da Medienobjekte benutzerdefinierte Objekte sind, verwenden Sie die API-Endpunkte für benutzerdefinierte Objekte, um sie zu erstellen:

  • Führen Sie eine GET-Anfrage an /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} durch, um den objectType zu finden.
  • Führen Sie einePOST-Anfrage an /crm/v3/objects/{objectType} durch, um das Medienobjekt im Account des Benutzers zu erstellen. 

Ein Medienobjekt stellt ein einbettbares Content-Element in einem Drittanbietersystem dar. Sobald ein Medienobjekt zur Media Bridge hinzugefügt wurde, kann es in CMS-Inhalte von HubSpot eingebettet und mit Medien-Events verknüpft werden.

Für VIDEO- und AUDIO-Medienobjekte sind in den folgenden Tabellen alle Standard- und erforderlichen Eigenschaften aufgeführt (* bedeutet erforderlich): 

Default Required properties of the audio video media types
ParameterTypeDescription
id
Number

Eine ID, die verwendet wird, um das spezifische Medium im Media Bridge-System von HubSpot zu identifizieren. Dies wird von HubSpot automatisch generiert und kann von Entwicklern nicht festgelegt werden.

hs_duration
Number

Die Dauer der Medienwiedergabe in Millisekunden.

hs_oembed_url*
String

Eine URL, die eine gültige oEmbed-Antwort zurückgeben muss, die der oEmbed-Spezifikation  folgt. Erfordert den video- oder rich-Typ mit einem iframe in html.

hs_file_url
String

URL der RAW-Mediendatei. Dies kann in Zukunft verwendet werden, um die Einbettung in Social Media zu unterstützen.

hs_thumbnail_url
String

URL eines Bilds, das als Thumbnail zum Einbetten des Mediums in Inhalte verwendet wird. Die ideale Größe für dieses Thumbnail ist 640 x 480 Pixel.

hs_poster_url
String

URL eines Bilds, das das Medium darstellt. Dieses Bild sollte die gleichen Maße wie das Originalmedium haben und kann an Stellen verwendet werden, an denen ein Bildplatzhalter benötigt wird (z. B. wenn das Medium in eine E-Mail eingefügt wird).

hs_external_id
String

Die ID des Mediums im System des Drittanbieters. Dies gibt Integratoren die Möglichkeit, Medien aus der Media Bridge abzurufen, basierend auf der gleichen ID, die sie in ihrem eigenen System verwenden. (Dies ist der API-Endpunkt, der diese Zuordnung nutzt)

hs_folder_path
String

Ein vom Anbieter bereitgestellter Pfad zum Objekt, der den Speicherort des Objekts im Ordnersystem des Drittanbieters darstellen soll (falls vorhanden). HubSpot versucht, diese Verzeichnisstruktur bei der Anzeige dieser Objekte für den Benutzer darzustellen, verschachtelt jedoch möglicherweise die Objekte und Ordner jedes Anbieters in einem nach dem Anbieter benannten Ordner der obersten Ebene.

hs_title*
String

Der Name des Mediums. Dies wird innerhalb der HubSpot-Benutzeroberfläche an Orten wie der Medienauswahl angezeigt.

hs_details_page_link
String

URL, die es einem Benutzer ermöglicht, das Medium im System des Medienanbieters anzuzeigen oder mit ihm zu interagieren. Dies wird in der HubSpot-Benutzeroberfläche verwendet, um Benutzern die Möglichkeit zu geben, das Medium zu identifizieren, ohne sich nur auf den Titel zu verlassen.

Für IMAGE-Medienobjekte werden in den folgenden Tabellen alle Standard- und erforderlichen Eigenschaften aufgelistet (* bedeutet erforderlich): 

Default Required properties of the audio video media types
ParameterTypeDescription
id
Number

Eine ID, die verwendet wird, um das spezifische Medium im Media Bridge-System von HubSpot zu identifizieren. Dies wird von HubSpot automatisch generiert und kann von Entwicklern nicht festgelegt werden.

hs_oembed_url*
String

Eine URL, die eine gültige oEmbed-Antwort zurückgeben muss, die der oEmbed-Spezifikation  folgt. Erfordert den video- oder rich-Typ mit einem iframe in html.

hs_file_url*
String

Die URL der RAW-Mediendatei. Dies kann in Zukunft verwendet werden, um die Einbettung in Social Media zu unterstützen.

hs_thumbnail_url
String

URL zu einem Bild, das als Thumbnail zum Einbetten des Mediums in Inhalt an Orten wie der Medienauswahl verwendet wird. Die ideale Größe für dieses Thumbnail ist 640 x 480 Pixel.

hs_poster_url
String

URL eines Bilds, das das Medium darstellt. Dieses Bild sollte die gleichen Maße wie das Originalmedium haben und kann an Stellen verwendet werden, an denen ein Bildplatzhalter benötigt wird (z. B. wenn das Medium in eine E-Mail eingefügt wird).

hs_external_id
String

Die ID des Mediums im System des Drittanbieters. Dies gibt Integratoren die Möglichkeit, Medien aus der Media Bridge abzurufen, basierend auf der gleichen ID, die sie in ihrem eigenen System verwenden. (Dies ist der API-Endpunkt, der diese Zuordnung nutzt)

hs_folder_path
String

Ein vom Anbieter bereitgestellter Pfad zum Objekt, der den Speicherort des Objekts im Ordnersystem des Drittanbieters darstellen soll (falls vorhanden). HubSpot versucht, diese Verzeichnisstruktur bei der Anzeige dieser Objekte für den Benutzer darzustellen, verschachtelt jedoch möglicherweise die Objekte und Ordner jedes Anbieters in einem nach dem Anbieter benannten Ordner der obersten Ebene.

hs_title*
String

Der Name des Mediums. Dies wird innerhalb der HubSpot-Benutzeroberfläche an Orten wie der Medienauswahl angezeigt.

hs_details_page_link
String

Eine URL, die es einem Benutzer ermöglicht, das Medium im System des Medienanbieters anzuzeigen oder mit ihm zu interagieren. Dies wird in der HubSpot-Benutzeroberfläche verwendet, um Benutzern die Möglichkeit zu geben, das Medium zu identifizieren, ohne sich nur auf den Titel zu verlassen.

CMS-Module zum Einbetten von Medien erstellen

Jeder Media-Bridge-App-Anbieter ist dafür verantwortlich, ein eigenes Modul zu erstellen, um seine Medien im CMS-System von HubSpot zu rendern. 

Wenn eine Media-Bridge-App in einem HubSpot-Account installiert ist, verfügt das Einbettungsfeld im Modul über einen zusätzlichen Quellentyp für Medienintegration. Dies ermöglicht es dem Benutzer, Medien von der installierten App auszuwählen, die auf seiner Webseite eingebettet werden sollen.

Nachdem der Benutzer ein einzubettendes Medium ausgewählt hat, sind die oembed_url und oembed_response des Mediums in HubL verfügbar, um mühelos Player zu rendern. Zusätzlich werden id und media_type von ausgewählten Medien gespeichert, um das Abfragen des zugrunde liegenden CRM-Objekts über die crm_objects-Hubl-Funktion zu ermöglichen. Dies kann verwendet werden, um einige oder alle Eigenschaften abzurufen, die Teil eines Medienobjekts sind.

Ein Beispiel für die Verwendung der crm_objects-HubL-Funktion mit einem Medienobjekt, bei dem die IDs 459 und 922 sind:

{% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }}

So rufen Sie ein bestimmtes Bild mit demselben Objekt ab: {% set object = crm_object("a123_Images", 459) %} {{ object }}

Apps können den Objekttyp (im Beispiel „a123_Videos“) abrufen, indem sie eine GET-Anfrage an /media-bridge/{appId}/settings/object-definitions/{mediaType} durchführen.

Entwickler sollten die CMS-Quellcode-API-Endpunkte verwenden, um ihren benutzerdefinierten Modulcode in die Accounts von Kunden zu übertragen, sobald Kunden sich über oAuth verbunden haben. Ist der Modulcode dann in den Account des Kunden übertragen, kann er automatisch das Modul des Entwicklers in seinem Inhalt verwenden.

 

Eine OEmbed-Domain einrichten

Um die oEmbed-HubL-Funktion zu verwenden, muss die Domain, die zum Abrufen der oEmbed-Antwort verwendet wird, registriert werden, indem eine Anfrage an/media-bridge/v1/{appId}/settings/oembed-domains durchgeführt wird. Die folgenden Parameter müssen enthalten sein:

  • Schema: Das URL-Muster für die Medien-URLs. Dieses URL-Muster wird verwendet, um die URL, die an die oEmbed-HubL-Funktion übergeben wird, Ihrer oEmbed-API zuzuordnen. Platzhalterwerte werden mit * (z. B. www.domain.com/*) unterstützt.
  • URL: Die URL Ihrer oEmbed-API. Die Medien-URL wird über einen URL-Parameter an diese URL übergeben. 
  • Discovery (Boolesch): Bestimmt, ob Ihre oEmbed-API die Discovery-Funktion von oEmbed unterstützt oder nicht. 

Standardmäßig werden die registrierten oEmbed-Domains allen Kunden zur Verfügung gestellt, die Ihre App installiert haben. Wenn Sie benutzerdefinierte Domains haben, die für jeden Kunden einzigartig sind, können Sie beim Einrichten der oEmbed-Domain angeben, in welchem Account eine oEmbed-Domain verwendet werden darf, indem Sie beim Einrichten der oEmbed-Domain einen portalId-Wert in die API-Anfrage übergeben. Dadurch wird sichergestellt, dass nur der angegebene HubSpot-Account diese oEmbed-Domain verwenden kann. 

Ein benutzerdefiniertes Modul erstellen

So erstellen Sie ein benutzerdefiniertes Modul:

  • Gehen Sie zu „Marketing“ > „Dateien und Vorlagen“ > „Design-Tools“
  • Klicken Sie oben links auf „Datei“ > „Neue Datei“.
  • Klicken Sie im Dialogfeld auf das Dropdown-Menü „Was möchten Sie erstellen?“ und wählen Sie „Modul“ aus. 
  • Klicken Sie auf „Weiter“. 
  • Aktivieren Sie das Kontrollkästchen neben jedem Inhaltstyp, in dem Ihr Modul verwendet wird: Seiten, Blog-Beiträge, Blog-Listings, E-Mails oder Angebote. In E-Mail-Vorlagen verwendete Module dürfen kein CSS oder JavaScript enthalten. 
  • Wählen Sie aus, ob dieses Modul ein lokales Modul oder ein globales Modul sein soll. Wenn Sie ein globales Modul erstellen, wird durch Bearbeiten des Inhalts dieses Moduls jeder Ort aktualisiert, an dem das Modul verwendet wird. 
  • Geben Sie einen Dateinamen für Ihr Modul ein und klicken Sie dann auf „Erstellen“.
  • Klicken Sie im Abschnitt „Felder“ auf der rechten Seite auf das Dropdown-Menü „Feld hinzufügen“ und wählen Sie „Einbetten“ aus. 

  • Wählen Sie im Abschnitt „Unterstützte Quellentypen“ die Option „Medienintegration“ aus.
  • Klicken Sie im Abschnitt „Standard-Einbettungs-Content“ auf „Von [Media-Bridge-App] auswählen“.
    • Wählen Sie im rechten Bereich das Medium aus, das Sie in das Modul einbetten möchten. 
    • Legen Sie gegebenenfalls Editor-Optionen, Feldanzeigebedingungen und Repeater-Optionen fest. 
  • Klicken Sie unter „HubL-Variablenname“ auf „Kopieren“ > „Snippet kopieren“.
  • Fügen Sie das Snippet in den module.html-Abschnitt ein.
  • Um eine Vorschau des Moduls auf Ihrer Seite anzuzeigen, klicken Sie auf „Vorschau“.
  • Klicken Sie im linken Abschnitt auf „Von [Media-Bridge-App] auswählen“ und wählen Sie dann das Medium aus, das Sie in der Vorschau anzeigen möchten. 

Ihre Medien-Events senden

Ein Medien-Event ist ein Event, das in Bezug zu einem Medienobjekt stattfindet, z. B. ein Wiedergabe-Event. Sobald ein Medien-Event an die Media-Bridge-App gesendet wurde, kann es in Berichten und in Chronik-CRM-Karten verwendet werden. 

Es gibt drei Typen von Medien-Events:

  • Wiedergabe-Event: Gibt an, dass ein Benutzer mit der Wiedergabe eines Mediums beginnt. 
  • Quartil-Event: Gibt an, wann ein Benutzer vierteljährliche Meilensteine (0 %, 25 %, 50 %, 75 %, 100 %) in dem Medium erreicht hat, das er wiedergibt. 
  • Aufmerksamkeitsspanne-Event: Gibt an, wenn ein Benutzer ein Medium vollständig genutzt hat oder wenn der Benutzer seine Sitzung beendet hat.

Events können gesendet werden, indem Sie eine POST-Anfrage an jeweils /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent und /media-bridge/v2/events/attention-span durchführen. 

Damit Medien-Events in der Kontaktchronik des Benutzers in HubSpot angezeigt werden, muss für jede Sitzung ein Wiedergabe-Event an die Media-Bridge-App gesendet werden. Events aus einer einzelnen Sitzung werden in der Chronik der Kontaktaktivitäten auf einer Karte angezeigt. 

Wenn Events mit den v2-Event-Endpunkten gesendet werden, werden sie im Gegensatz zu über die v1-Endpunkte gesendeten asynchron verarbeitet. Daher empfehlen wir Folgendes:

  • Die v1-Version der Endpunkte sollte für alle Tests verwendet werden, da eine fehlerhafte Anfrage sofort einen Fehler verursacht.
  • Die v2-Version der Endpunkte sollte in der Produktion verwendet werden, da ihr asynchroner Charakter hilft, Verzögerungen im Client zu vermeiden, während das Event in die Media Bridge geschrieben wird. Events werden außerdem im Falle eines vorübergehenden Ausfalls des Servers in der Media Bridge behalten und erneut versucht.

Ein Event mit einem Kontaktdatensatz verknüpfen

Um ein Medien-Event mit einem Kontaktdatensatz zu verknüpfen, müssen Sie entweder die contactId oder ein contactUtk angeben. Wird nur ein contactUtk angegeben, wird es in eine contactId umgewandelt. Wenn beide in der Anfrage angegeben sind, wird die contactId als zentrale Quelle verwendet. Mit diesem Parameter kann die Media-Bridge-App eine Zuordnung zwischen dem Kontaktdatensatz und dem Event erstellen.

Sobald ein Medien-Event mit einem Kontaktdatensatz verknüpft wurde, kann das Event in objektübergreifenden Berichten verwendet werden. Dies ermöglicht es Kunden, ihre Medien-Events mit Kontaktaufzeichnungen sowie zugeordneten Unternehmen und Deals zu verknüpfen.

Verknüpfen eines Events mit einem Medium

Um ein Medien-Event einem Medium zuzuordnen, muss entweder der mediaID- oder der externalID-Parameter in der Anfrage berücksichtigt werden. Wird beides angegeben, wird die mediaID als zentrale Quelle verwendet.

Ein Event mit einer Seite verknüpfen

Um ein Medien-Event einer HubSpot-Seite zuzuordnen, müssen die folgenden Parameter in der Anfrage enthalten sein:

  • Wird die Seite in CMS Hub gehostet, muss die pageId angegeben werden.
  • Wird die Seite nicht in CMS Hub gehostet, müssen pageName und pageUrl berücksichtigt werden.

In der folgenden Tabelle sind unterstützte Eigenschaften für die drei Medien-Events aufgeführt:

Use this table to describe parameters / fields
EigenschaftEvent-TypDescription
mediaBridgeObjectId
All Events

Die ID des Mediums, auf das sich dieses Event bezieht.

externalId
String

Die ID des Mediums im System des Drittanbieters. Dies gibt Entwicklern die Möglichkeit, anhand der gleichen ID, die sie in ihrem eigenen System verwenden, auf Medien in der Media Bridge zu verweisen. Dies kann anstelle der mediaBridgeObjectId in Events verwendet werden. Wenn sowohl eine externalId als auch eine mediaBridgeObjectId bereitgestellt werden, wird die mediaBridgeObjectId verwendet und die externalId wird ignoriert.

sessionId
All Events

Eine eindeutige ID, um eine Ansichtssitzung darzustellen. Dies kann für verschiedene Anbieter verschiedene Dinge bedeuten, und HubSpot lässt Anbieter entscheiden, was eine Sitzung für sie bedeutet. Dies wird verwendet, um Events zu gruppieren, die in derselben Sitzung stattgefunden haben. Es wird erwartet, dass dies durch das System des Drittanbieters generiert wird.

contactId
All Events

Die ID des Kontakts im System von HubSpot, der das Medium genutzt hat. Sie erhalten diese mithilfe derUTK-API zum Abrufen des Kontakts von HubSpot. Die API unterstützt außerdem das Bereitstellen eines UTK und übernimmt automatisch das Umwandeln in eine Kontakt-ID.

contactUtk
All Events

Das UTK-Token, das identifiziert, welcher Kontakt das Medium konsumiert hat.

pageId
All Events

Die Content-ID der Seite, auf der ein Event aufgetreten ist.

pageName
All Events

Der Name oder Titel der Seite, auf der ein Event aufgetreten ist.

pageUrl
All Events

Die URL der Seite, auf der ein Event aufgetreten ist.

occurredTimestamp
All Events

Der Zeitstempel, zu dem dieses Event aufgetreten ist, in Millisekunden seit der Epoche.

attentionSpanMapString/attentionSpanMap
Attention Span

Dies sind die Rohdaten, die die genauesten Daten zu Zeitspannen des Mediums liefern und wie oft jede Zeitspanne vom Benutzer genutzt wurde. 

Beispiel: Betrachten Sie ein 10-Sekunden-Video, bei dem jede Sekunde eine Spanne ist. Wenn ein Besucher die ersten 5 Sekunden des Videos ansieht, dann das Video neu startet und die ersten 2 Sekunden erneut ansieht, würde der resultierende attentionSpanMapString so aussehen: “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”-

totalPercentPlayed
Attention Span

Der Prozentsatz des Mediums, den der Benutzer konsumiert hat. Anbieter können dies unterschiedlich berechnen, je nachdem, wie sie wiederholte Ansichten des gleichen Teils des Mediums berücksichtigen. Aus diesem Grund versucht die API nicht, totalPercentWatched anhand der Informationen zur Aufmerksamkeitsspanne für das Event zu validieren. Wenn dieser Wert fehlt, berechnet HubSpot ihn von der Aufmerksamkeitsspanne wie folgt: (Anzahl der Spannen mit einem Wert von 1 oder mehr)/(Gesamtzahl der Spannen).

totalSecondsPlayed
Attention Span

Die Sekunden, die ein Benutzer mit dem Konsum des Mediums verbracht hat. Die Media Bridge berechnet dies als totalPercentPlayed*mediaDuration. Wenn ein Anbieter möchte, dass dies anders berechnet wird, kann er den vorab berechneten Wert angeben, wenn er das Event erstellt

playedPercent
Quartile Event

Ein Quartil-Prozent-Wert (0, 25, 50, 75, 100) dafür, wie viel vom Medium bislang konsumiert wurde.

iframeUrl
Played Event

Eine URL, die verwendet werden, um Daten aus einem externen System mithilfe eines iFrame anzuzeigen. Wenn berücksichtigt, zeigt das Event in der Kontaktchronik einen Link an, der ein modales Dialogfenster öffnet, das bei Anklicken den iFrame-Inhalt anzeigt.

mediaType
String

Der Medientyp, zu dem das Event gehört (zum Beispiel VIDEO oder AUDIO). Dies ermöglicht es uns, das Event den richtigen Objekten zuzuordnen, wenn ein einzelner Anbieter mehrere Medientypen unterstützt.


War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.