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. 

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. 

Um ein Medienobjekt zu definieren, führen Sie eine POST-Anfrage an /media-bridge/v1/{appId}/settings/object-definitions durch. Sie verwenden den mediaTypes-Parameter, um das Objekt zu definieren: 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. 

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

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 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 anzeigen und Beispielmedien erstellen.

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

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

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): 

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

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.

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. 

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 Einbettung aus. 

• Wählen Sie im Abschnitt Unterstützte Quellentypen die Option Medienintegration aus.
• Klicken Sie im Abschnitt Standard-Einbettungscontent 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. 

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.

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.

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.

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: