Chronik-Events

Die CRM-Erweiterungen ermöglichen es, dass Informationen aus anderen Systemen in HubSpot-Kontakt-, Unternehmens- oder Deal-Objekten angezeigt werden können. Die Chronik-Events-Endpunkte ermöglichen es Ihnen, benutzerdefinierte Chronik-Events zu erstellen. Wenn Sie möchten, dass Ihre Daten von Benutzern bearbeitet werden können, jedoch keines der nativen Objekte Ihren Anforderungen entspricht, sollten Sie überlegen, ob vielleicht benutzerdefinierte Objekte Ihre Anforderungen erfüllen.

Sie möchten z. B. Ihre Kontakte besser anhand ihrer Interaktionen mit Ihrem Unternehmen und Inhalt segmentieren. Dazu benötigen Sie mehr Informationen über sie. Ihre App kann benutzerdefinierte Events erstellen (Kontakte, die sich registriert, jedoch nicht an einem jüngsten Webinar teilgenommen haben; welche Variante eines Registrierungsprozesses einen Kontakt abgeschlossen hat, usw.), die Ihnen mehr Kontext über die Interaktionen von Kontakten mit Ihrem Unternehmen liefern.

Eine Hinweis zum Löschen von Vorlagen für Chronik-Events

Sobald eine Vorlage gelöscht wurde, werden vorhandene Events, die diese Vorlage verwenden, dauerhaft aus Accounts mit Ihrer verknüpften App entfernt. Sie können keine neuen Events mehr für diesen Typ erstellen, sehen aber weiterhin dennoch frühere Event-Daten in Listen und Berichten. Es kann mehrere Stunden dauern, bis diese Änderungen in HubSpot angezeigt werden.

Eine Event-Vorlage erstellen

Bevor Sie Events erstellen können, müssen Sie eine Event-Vorlage erstellen. Event-Vorlagen beschreiben Aktionen, die Ihre App zur Chronik eines Kontakt-, Unternehmens- oder Deal-Objekts in HubSpot hinzufügt. Beispiele für diese Aktionen sind unter anderem das Aufrufen eines Videos, die Registrierung für ein Webinar oder das Ausfüllen einer Umfrage. Eine einzelne App kann bis zu 750 Event-Vorlagen erstellen.

Events werden standardmäßig für Kontakte erstellt, sie können jedoch mithilfe des objectType-Feldes auch für Unternehmen oder Deals erstellt werden. Im Abschnitt zur Erstellung einer Vorlage für Chronik-Events finden Sie weitere Informationen.

Jede Event-Vorlage verfügt über einen eigenen Satz an Token und Vorlagen. Sie können Events für Kontakte als Kriterien beim Erstellen neuer Kontaktlisten oder Workflows verwenden, z. B.: „Erstellen einer Liste aller Kontakte mit einem Video-Like, bei der der Videoname XYZ enthält“, wobei die Event-Vorlage „Video-Like“ heißt und über ein Event-Token mit dem Namen „Videoname“ verfügt.

Erstellen von Event-Vorlagen über die API

In diesem Beispiel erstellen wir eine neue Event-Vorlage vom Typ „Beispiel-Webinar-Registrierung“. Verwenden Sie zur Authentifizierung den Entwickler-API-Schlüssel in Ihrem App-Entwickler-Account.

Ersetzen Sie unbedingt <<appId>> mit Ihrer eigenen App-ID, die Sie sowohl unter „Meine Apps“ als auch auf den App-Detailseiten in Ihrem Entwickler-Account finden können. Sie müssen auch <<developerHapikey>>mit Ihrem eigenen Entwickler-API-Schlüssel ersetzen, den Sie finden, indem Sie zu „Apps“ > „HubSpot-API-Schlüssel abrufen“ gehen.

Die Eigenschaften headerTemplate und detailTemplate könnten auch hier angegeben werden. (Siehe „Definieren von Vorlagen“ unten.)

Diese POST-Anfrage gibt die vollständige, gespeicherte Definition der Event-Vorlage zurück. Beachten Sie unbedingt die id-Eigenschaft in dieser Antwort. Dies ist die Event-Vorlagen-ID, die Sie für alle Aktualisierungen dieser Event-Vorlage oder Token in der Zukunft benötigen.

Sie können alle für eine App definierten Event-Vorlagen über diesen GET-Befehl anzeigen. Dabei werden auch die Event-Vorlagen-IDs zurückgegeben:

Erstellen von Event-Vorlagen über die Benutzeroberfläche

Neben dem Erstellen und Verwalten von Chronik-Event-Vorlagen über die API können Sie auch Event-Vorlagen in Ihrem HubSpot-Entwickler-Account verwalten.

Gehen Sie in Ihren App-Einstellungen zu „Chronik-Events“ und verwenden Sie die Schaltfläche „Event-Typ erstellen“, um eine neue Event-Vorlage für diese App zu erstellen. Wenn Sie bereits Event-Vorlagen erstellt haben, werden diese ebenfalls hier angezeigt

Sie beginnen mit einem Entwurf Ihrer neuen Event-Vorlage. Nachdem Sie den Objekttyp und die Detail- und Header-Vorlagen für das Event festgelegt haben, klicken Sie auf „Erstellen“

Legen Sie beim Erstellen oder Bearbeiten Ihrer Event-Vorlage auf der Registerkarte „Daten“ alle Token fest, die Sie mit ihr verwenden möchten.

2. Definieren von Deal-Token

Nachdem Sie eine Event-Vorlage festgelegt haben, möchten Sie wahrscheinlich auch die Token definieren. Token für Event-Vorlagen ermöglichen es Ihnen, benutzerdefinierte Daten anzuhängen, die in der Chronik angezeigt oder für die Listensegmentierung verwendet werden können. Sie können bis zu 500 Token pro Chronik-Event-Vorlage erstellen.

Erstellen von Event-Token über die API

Mithilfe der in Schritt 1 erstellten Event-Vorlagen-ID fügen wir einige Token hinzu, um das Webinar zu identifizieren, für das sich unsere Kontakte registriert haben.

In ähnlicher Weise werden mit GET alle Token zurückgegeben, die in einer Event-Vorlage definiert sind:

Unterstützte Token-Typen:

• string
• number
• enumeration – Eine aus einer Reihe von Optionen. Siehe webinarType-Beispiel oben.
• date – Alle Datumsangaben müssen in Millisekunden in Unix-Zeit angegeben sein.

Hinweis: Event-Token können nicht Protokoll (log) oder Suche (lookup) benannt werden. Diese Token sind als Helfer von Handlebars.js reserviert, der Bibliothek, die zur Anzeige von Events in Apps verwendet wird. Weitere Informationen finden Sie hier in der Dokumentation von Handlebars.js.

3. Definieren von Header- und Detail-Vorlagen

Header- und Detail-Vorlagen bestimmen, wie Sie ein Chronik-Event angezeigt werden soll. Sie können Markdown-Dokumente mit Handlebars-Vorlagen angeben. Die Header-Vorlage sollte eine einzeilige Beschreibung des Events sein, und die Details-Vorlage ist die Drilldown-Ansicht des Events (Beispiele unten).

Die Event-Token werden als Daten an die Vorlagen übergeben. Anhand unseres Beispiels können Sie die webinarName-Token in der Vorlage mithilfe von referenzieren.

Die extraData eines Events (erläutert unter „Grundlegende zu extraData“) können nur in der Details-Vorlage referenziert werden.

Definieren von Header- und Detail-Vorlagen durch die API

Header- und Detail-Vorlagen können in der Event-Vorlage über die Event-Vorlagen-Endpunkte definiert werden. Wir können beispielsweise Vorlagen zu unserer „Beispiel-Webinar-Registrierung“ hinzufügen, indem dies mit einem PUT modifiziert wird:

Beachten Sie hier die #formatDate-Direktive. Mit ihr möchten wir eine benutzerfreundliche Datumsformatierung ermöglichen.

Sobald ein Event für einen Kontakt mit ihrer Hilfe erstellt wird (siehe „Erstellen eines Events“), wird Folgendes in der Chronik des Kontakts angezeigt:

Klicken auf „Details anzeigen“ stellt die Details-Vorlage dar:

Weitere Informationen dazu, wie Sie Symbol festlegen, das neben den Events angezeigt wird, finden Sie unten unter „Einrichten eines benutzerdefinierten Symbols“.

Der Text „Beispiel-App-Name“ oben ist der Name der App. In der CRM-Chronik können Events nach App gefiltert werden.

4. Definieren aller Aspekte einer Event-Vorlage in einem einzigen Aufruf

Bisher haben Sie gesehen, wie die einzelnen Aspekte einer Event-Vorlage schrittweise definiert wurden. Sie können aber auch alles in einem einzigen POST-Aufruf definieren. 

5. Erstellen eines Events

Nachdem nun eine Event-Vorlage mit Token und Vorlagen eingerichtet ist, sind wir bereit, Events für die Kontakte, Unternehmen, Deals und Tickets unserer Kunden zu erstellen. In den folgenden Beispielen wird davon ausgegangen, dass mit der oben erstellten contacts-Event-Vorlage gearbeitet wird. Wenn die Event-Vorlage oben nicht so eingerichtet ist, dass sie über die Token webinarName und webinarId verfügt, erhalten Sie einen Fehler beim Versuch, das Event zu erstellen. Hier ein Beispiel-POST für das Erstellen eines Events:

Dadurch wird ein Event in der Chronik von a.test.contact@email.com erstellt (ausgehend davon, dass die Vorlagen unter „Definieren von Vorlagen“ verwendet werden):

Da Ihr Entwickler-API-Schlüssel nur für die Einrichtung von Ihrem Entwickler-Account aus verwendet werden kann, können Sie mit ihn keine Events erstellen. Um ein Event zu erstellen, muss der zugehörige HubSpot-Account Zugriff über OAuth auf Ihre App gewähren. Nachdem Sie ein Zugriffstoken erhalten haben, können Sie es zum Hinzufügen von Events in den Kontakten des Accounts verwenden.

Festlegen des Events-Zeitstempels

Der Zeitstempel des Events bestimmt, wo das Event in der Chronik des Objekts angezeigt wird. Standardmäßig wird der Event-Zeitstempel angezeigt, wenn der POST-Befehl gesendet wird. Sie können die Event-Zeit anpassen, indem Sie sie im Anfragetext in einer Zeitstempel-Eigenschaft angeben:

Dies wird bevorzugt, wenn Sie den exakten Zeitpunkt kennen, an dem eine Aktion stattgefunden hat. In diesem Beispiel gilt, wenn wir den Zeitstempel für diese Webinar-Registrierung haben, sollten wir ihn in diesem POST bereitstellen.

Zeitstempel können in Millisekunden-Epoche-Zeit oder im ISO 8601-Format vorliegen.

6. Erstellen eines Events mit einem CRM-Objekt

Um ein Event erstellen zu können, müssen Sie das Event mit einem Kontakt, einem Unternehmen oder einem Deal im Account des Kunden verknüpfen können.

In den obigen Beispielen wurde der objectType auf Kontakt festgelegt und wir haben E-Mail verwendet, um das Event mit einem Kontakt zu verknüpfen. E-Mail-Adressen müssen für Kontakte in HubSpot eindeutig sein. Wenn es einen vorhandenen Kontakt mit der angegebenen E-Mail gibt, wird dieser Kontakt aktualisiert. Wenn kein Kontakt vorhanden ist, wird ein neuer Kontakt erstellt. Standardmäßig verfügt dieser neue Kontakt nur über die angegebene E-Mail-Kontakteigenschaft. Erfahren Sie mehr über das Aktualisieren (Stempeln) von Kontakteigenschaften mit Event-Daten, um zusätzliche Daten zu Kontakteigenschaften hinzuzufügen.

Wenn Sie mit bekannten Kontakten arbeiten, können Sie auch die Kontakt-vid verwenden, um das Event zu verknüpfen. In diesen Fällen würden Sie objectId im Anfrage-JSON verwenden. Sie müssen die VID eines vorhandenen Kontakts einbeziehen, da Sie keine neuen Kontakte mithilfe von objectId erstellen können. Dieses Beispiel verwendet objectId anstelle von „email“:

Sie können ein Event auch nach Benutzertoken, oder utk, einem Kontakt zuordnen. Das Benutzertoken wird vom HubSpot-Tracking-Code zum Nachverfolgen von Besuchern verwendet und wird im hubspotutk-Cookie gespeichert. Verwenden Sie den utk-Parameter, um ein Event nach Benutzertoken einem Kontakt zuzuordnen. Hinweis: Es ist nicht möglich, Events mit anonymen Besuchern mithilfe des Benutzertokens zuzuordnen. Wenn das Event also nur mithilfe des utk-Parameters zugeordnet wird und das angegebene Benutzerertoken nicht bereits einem Kontakt zugeordnet ist, würde kein neuer Kontakt erstellt und das Event wäre nicht in HubSpot sichtbar. Das Event wird jedoch in der Chronik angezeigt, wenn ein neuer Kontakt über andere Methoden mit dem Benutzerertoken verknüpft worden ist, (in der Regel über eine Formulareinsendung, einschließlich des hutk, oder über die Methode des Identifizierens der Tracking-Code-API). Aus diesem Grund empfehlen wir, die email zusätzlich zum utk zu berücksichtigen, um sicherzustellen, dass das Event einem neuen oder vorhandenen Kontakt zugeordnet wird.

Wenn Sie mit einer Event-Vorlage für Kontakte arbeiten, ist es möglich, mehrere Identifikationsparameters mit dem Event zu berücksichtigen, sodass jede Kombination der email-, objectId- und utk-Parameter berücksichtigt werden kann. Wenn mehrere Parameter berücksichtigt werden, hat die objectId (vid) die höchste Priorität beim Bestimmen des Kontakts, der dem Event zugeordnet werden soll, gefolgt von utk und email mit der geringsten Priorität. Dies bedeutet, dass Sie die E-Mail-Adresse eines vorhandenen Objekts aktualisieren können, indem Sie eine neue E-Mail-Adresse im email-Parameter mit der vid eines bekannten Objekts in objectId berücksichtigen können. In diesem Beispiel werden die E-Mail-Adresse und das Benutzertoken zusammen verwendet:

Neben dem Arbeiten mit Kontakten ist es auch möglich, Event-Vorlagen für Unternehmen und Deals zu erstellen. Für diese Event-Vorlagen müssen Sie objectId verwenden, um das Event dem Unternehmen oder Deal zuzuordnen. Für Unternehmen muss die objectId auf die companyId des Unternehmens festgelegt sein, dem das Event zugeordnet werden soll, und für Deals müssten Sie die objectId auf die dealId des Deal-Objekts festlegen.

Wenn im folgenden Beispiel davon ausgegangen wird, dass die Event-Vorlage auf den COMPANY objectType festgelegt wurde, würde dieses Event mit dem Unternehmensobjekt mit der companyId 528253914 zugeordnet:

7. Chronikerweiterungen

Die Chronik-Erweiterungen können verwendet werden, um Daten aus einem externen System mithilfe eines iFrame anzuzeigen. Wenn berücksichtigt, zeigt das Event einen Link an, der ein modales Dialogfenster öffnet, das bei Anklicken den iFrame-Inhalt anzeigt. Die Details für den iFrame werden im timelineIFrame-Feld festgelegt. Dies ist ein Objekt enthält, das die folgenden Felder enthält:

• linkLabel – Der Text, der zur Anzeige des Links, der den IFrame-Inhalt anzeigt, verwendet wird.
• headerLabel – Das Label des modalen Fensters, das die IFrame-Inhalte anzeigt. 
• url – Der URI des IFrame-Contents.
• width – Die Breite des modalen Fensters.
• height – Die Höhe des modalen Fensters.

Bei Verwendung beispielsweise dieser Daten für ein Event:

Würde dieses Event erstellt werden, einschließlich des Links „Externe Daten anzeigen“:

Durch Klicken auf diesen Link würde ein modales Fenster geöffnet, das die in der url festgelegte Seite anzeigt:

8. Aktualisieren (Stempeln) von CRM-Objekteigenschaften mit Event-Daten

In vielen Fällen möchten Sie die Eigenschaften für die Kontakte, Unternehmen oder Deals ändern, für die Sie Events hinzufügen, ändern. Dies geschieht häufig in Fällen, in denen über das Event tatsächlich ein Kontakt erstellt wird – Sie möchten wahrscheinlich die Eigenschaften „Vorname“ und „Nachname“ im Kontakt aktualisieren, damit Sie nicht nur einen Kontakt mit einer E-Mail-Adresse und einem Event erstellen.

Sie können das zugehörige Objekt mit Daten von einem Event aktualisieren (stempeln), indem Sie Ihre benutzerdefinierten Event-Token Kontakt-, Unternehmens- oder Deal-Eigenschaften zuordnen.

Ziehen Sie diesen PUT-Befehl zum Aktualisieren einer benutzerdefinierten Event-Vorlage in Betracht. Beachten Sie dabei das objectPropertyName-Feld:

Dieser verwendet objectPropertyName, um dieses benutzerdefinierte Event-Token der Eigenschaft contact-Objekt zz_webinar_name zuordnen. Das heißt, dass beim Erstellen eines neuen Events, das ein webinarName-Token angibt, auch die zz_webinar_name-Eigenschaft des zugehörigen contact festgelegt wird. Sie können diese auf benutzerdefinierte oder vordefinierte HubSpot-Eigenschaften festlegen.

Angenommen, wir haben beispielsweise bereits eine companyName-Token erstellt, das eine benutzerdefinierte zz_company_name-Eigenschaft im Kontakt referenziert. Dies führt dann dazu, dass bei Erstellen eines Event wie diesem die zz_company_name- und zz_webinar_name-Eigenschaften im Kontakt mit der E-Mail-Adresse a.test.contact@email.com festgelegt werden:

Hinweis: Wenn eine benutzerdefinierte Eigenschaft mit einem Event-Token aktualisiert (gestempelt) wird und diese benutzerdefinierte Eigenschaft für einen HubSpot-Account nicht vorhanden ist, wird der Wert weiterhin für das Event festgelegt, es wird jedoch für das entsprechende Objekt ignoriert.

9. Grundlegendes zu extraData

Sie müssen möglicherweise detaillierte Daten zu einem Event hinzufügen, das nicht der einfachen Token-Wert-Struktur entspricht, die von den Event-Vorlagen-Token verwendet wird. Möglicherweise müssen Sie auch eine Liste oder eine gewisse hierarchische Aufschlüsselung zu einem Integrations-Event hinzufügen. Hier kommt nun extraData ins Spiel.

Sie können ein extraData-Attribut zum JSON-Text eines Events hinzufügen. Der Wert dieses extraData-Attribut kann beliebiger zulässiger JSON sein. Zum Beispiel:

Ein Beispiel für die Verwendung von extraData in einer Details-Vorlage:

Dies führt zu einem Chronik-Event, das wie folgt aussieht:

Hinweis: Das extraData-Attribut kann nur in der Details-Vorlage für ein Event referenziert werden. Es kann weder in der Kopfzeilen-Vorlage oder in der Listensegmentierung verwendet werden.

10. Einrichten eines benutzerdefinierten Symbols

Um Ihre Chronikelemente visuell ansprechender gestalten, sollten Sie ein benutzerdefiniertes Symbol hinzufügen.

Diese Bilddatei für dieses Symbol sollte:

• Ungefähr quadratische Maße aufweisen
• Einen durchsichtigen Hintergrund haben
• Den Inhalt in der Mitte des Symbols haben
• Auf bis zu 30 x 30 Pixel verkleinert werden können
• Über eine Dateigröße von höchstens 5 MB verfügen

Um das Symbol für Chronik Events festzulegen, navigieren Sie zu „Chronik Events“. Klicken Sie auf das Platzhalterbild oder das vorhandene Symbol, um es festzulegen oder zu aktualisieren.

Nachdem Sie das oder die Symbole festgelegt haben, wird es bzw. werden sie neben allen mit dieser Anwendung verknüpften Chronik-Events angezeigt:

Verwandte Dokumente

Grundlegendes zum CRM

CRM-Karten