CMS-API | Media Bridge

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/v1/{appId}/settings/object-definitions durch. Fügen Sie im Anfragetext einen der folgenden Medientypwerte in das mediaTypes-Array ein: VIDEO, AUDIO, DOCUMENT IMAGE 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.

​

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 HubSpot-Account des Kunden installiert ist:

• Gehen Sie zu https://app.hubspot.com/media-bridge-demo/{HubID} und ersetzen Sie dabei {HubID} durch die Account-ID.
• 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 einsehen und Beispielmedien erstellen.

Sobald die Media-Bridge-App im HubSpot-Account des Kunden installiert wurde, können Sie:

• Medienobjekte erstellen
• CMS-Module zum Einbetten Ihrer Medienobjekte erstellen
• Medien-Events senden

​

Ihre Medienobjekte erstellen

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 eine POST-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 werden in den folgenden Tabellen alle verfügbaren Eigenschaften aufgelistet:

Mit * markierte Felder sind Pflichtfelder.

Parameter	Typ	Beschreibung
id	Zahl	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	Zahl	Die Dauer der Medienwiedergabe in Millisekunden.
hs_oembed_url*	Zeichenfolge	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	Zeichenfolge	URL der RAW-Mediendatei. Dies kann in Zukunft verwendet werden, um die Einbettung in Social Media zu unterstützen.
hs_thumbnail_url	Zeichenfolge	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	Zeichenfolge	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	Zeichenfolge	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	Zeichenfolge	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*	Zeichenfolge	Der Name des Mediums. Dies wird innerhalb der HubSpot-Benutzeroberfläche an Orten wie der Medienauswahl angezeigt.
hs_details_page_link	Zeichenfolge	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 verfügbaren Eigenschaften aufgelistet:

Mit * markierte Felder sind Pflichtfelder.

Parameter	Typ	Beschreibung
id	Zahl	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*	Zeichenfolge	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*	Zeichenfolge	Die URL der RAW-Mediendatei. Dies kann in Zukunft verwendet werden, um die Einbettung in Social Media zu unterstützen.
hs_thumbnail_url	Zeichenfolge	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	Zeichenfolge	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	Zeichenfolge	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	Zeichenfolge	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*	Zeichenfolge	Der Name des Mediums. Dies wird innerhalb der HubSpot-Benutzeroberfläche an Orten wie der Medienauswahl angezeigt.
hs_details_page_link	Zeichenfolge	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-Seite 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 die id und der media_type von ausgewählten Medien gespeichert, um das Abfragen des zugrunde liegenden CRcrm_objects-Objekts über die -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 dercrm_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 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-Manager.
• 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, Blogbeiträ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 Einbettung 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: Dies gibt an, dass ein Benutzer mit der Wiedergabe eines Mediums beginnt. Dieses Event ist sowohl in der Kontaktchronik als auch im Berichte-Tool verfügbar.
• Quartil-Event: gibt an, wann ein Benutzer vierteljährliche Meilensteine (0 %, 25 %, 50 %, 75 %, 100 %) in dem Medium erreicht hat, das er wiedergibt. Dieses Event ist nur in der Kontaktchronik verfügbar.
• Aufmerksamkeitsspanne-Event: gibt an, wenn ein Benutzer ein Medium vollständig genutzt hat oder wenn der Benutzer seine Sitzung beendet hat. Dieses Event ist nur innerhalb des Berichte-Tools verfügbar.

Events können gesendet werden, indem Sie eine POST-Anfrage an /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent und /media-bridge/v2/events/attention-span respectively 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.

​

Ein Events mit einem Medium verknüpfen

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 der pageName und die pageUrl berücksichtigt werden.

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

Eigenschaft	Event-Typ	Beschreibung
mediaBridgeObjectId	Alle Events	Die ID des Mediums, auf das sich dieses Event bezieht.
externalId	Zeichenfolge	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. Werden sowohl eine externalId als auch mediaBridgeObjectId angegeben, wird die mediaBridgeObjectId verwendet und die externalId ignoriert.
sessionId	Alle 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	Alle Events	Die ID des Kontakts im System von HubSpot, der das Medium genutzt hat. Diese kann mithilfe vonHubSpots API für das Abrufen von Kontakten anhand des Benutzertokens abgerufen werden. Die API unterstützt auch die Bereitstellung eines Benutzertokens und wandelt dieses automatisch in eine Kontakt-ID um.
contactUtk	All Events	Das Benutzertoken (usertoken, utk), das identifiziert, welcher Kontakt die Medien genutzt hat.
pageId	Alle Events	Die Content-ID der Seite, auf der ein Event aufgetreten ist.
pageName	Alle Events	Der Name oder Titel der Seite, auf der ein Event aufgetreten ist.
pageUrl	Alle Events	Die URL der Seite, auf der ein Event aufgetreten ist.
occurredTimestamp	Alle Events	Der Zeitstempel, zu dem dieses Event aufgetreten ist, in Millisekunden seit der Epoche.
rawDataString / rawDataMap	Aufmerksamkeitsspanne	Dies sind die Rohdaten, die die genauesten Daten zu Zeitspannen des Mediums liefern und wie oft jede Zeitspanne vom Benutzer genutzt wurde. Wenn beispielsweise ein Besucher bei einem 10-Sekunden-Video, bei dem jede Sekunde eine Spanne ist, die ersten 5 Sekunden des Videos ansieht, dann das Video neu startet und die ersten 2 Sekunden erneut ansieht, würde der resultierende rawDataString so aussehen: “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”.
totalPercentPlayed	Aufmerksamkeitsspanne	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	Aufmerksamkeitsspanne	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	Quartil-Event	Ein Quartil-Prozent-Wert (0, 25, 50, 75, 100) dafür, wie viel vom Medium bislang konsumiert wurde.
iframeUrl	Wiedergabe-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	Zeichenfolge	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.