Bereichsanforderungen
Bereichsanforderungen
- 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-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 einePOST-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.
- 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.readmedia_bridge.write
- Verwenden Sie die OAuth-Authentifizierung, wenn Sie Aufrufe Ihrer App authentifizieren. Erfahren Sie mehr über Authentifizierungsmethoden.
- 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.
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 denobjectTypezu finden. - Führen Sie eine
POST-Anfrage an/crm/v3/objects/{objectType}durch, um das Medienobjekt im Account des Benutzers zu erstellen.
VIDEO- und AUDIO-Medienobjekte werden in den folgenden Tabellen alle verfügbaren Eigenschaften aufgelistet:
Mit * markierte Felder sind Pflichtfelder.
Für
IMAGE-Medienobjekte werden in den folgenden Tabellen alle verfügbaren Eigenschaften aufgelistet:
Mit * markierte Felder sind Pflichtfelder.
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 dieoembed_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.
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.
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 diecontactId 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 dermediaID- 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
pageIdangegeben werden. - Wird die Seite nicht in CMS Hub gehostet, müssen der
pageNameund diepageUrlberücksichtigt werden.