Zum Hauptinhalt springen
Letzte Änderung: 8. Oktober 2025
Nachfolgend finden Sie Referenzinformationen für die Verwendung von App-Events, einschließlich Event-Typschemata, Vorlagen für das Rendering von Event-Chronik, Felder für das Auftreten von Events und mehr.

​
Projektstruktur

Im Kontext eines Projekts legen Sie Event-Typdefinitionen in einem app-events-Verzeichnis innerhalb von app/ab. Das app-events-Verzeichnis sollte eine JSON-Schemadefinitionsdatei für jeden Event-Typ (*-hsmeta.json) enthalten. 
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
Um Event-Typdefinitionen in ein Projekt aufzunehmen, ist Folgendes erforderlich:
  • Ihre App muss die OAuth-Authentifizierung verwenden und für die Verteilung über den App Marketplace konfiguriert sein. Darüber hinaus muss die App eine timeline in ihrer requiredScopes enthalten. Erfahren Sie mehr über die App-Konfiguration.
  • Erst nach erfolgreichem Deployment Ihres Projekts können Sie eine App-Event-Komponente einbinden.

​
Schema des Event-Typs

Im Folgenden finden Sie die Konfigurationsoptionen, die für Event-Typ-Schemata (*-hsmeta.json) verfügbar sind. Beachten Sie bitte, dass einige der folgenden Attribute sich nach dem Erstellen des Event-Typs nicht mehr ändern lassen.
Jede App ist auf 750 Event-Typen beschränkt.
{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in.",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

Mit * markierte Felder sind Pflichtfelder.

FeldTypBeschreibung
uid*ZeichenfolgeEine interne eindeutige ID für den Event-Typ.
type*ZeichenfolgeDer Typ der Komponente. Muss app-event sein.
name*ZeichenfolgeDas in HubSpot angezeigte Label (bis zu 50 Zeichen). Dieser Wert lässt sich nach der Erstellung nicht mehr aktualisieren.
objectType*ZeichenfolgeDer vollständig qualifizierte Name des CRM-Objekttyps, dem Event-Vorkommnisse zugeordnet werden können. Dieser Wert kann nach der Erstellung nicht mehr geändert werden. Kann eines der folgenden sein: COMPANY, CONTACT, CUSTOM_OBJECT, DEAL, TICKET, APP_OBJECT.
headerTemplateZeichenfolgeDie Rendering-Vorlage für den Header der Aktivitätskarte der CRM-Chronik. Kann bis zu 1.000 Zeichen lang sein.
detailTemplateZeichenfolgeDer Rendering-Vorlage für den Text der CRM Chronik Aktivitätskarte. Kann bis zu 10.000 Zeichen lang sein.
propertiesArrayEigenschaften, die für den Event-Typ definiert sind, in dem Sie Daten zum Auftreten von Events speichern. Jeder Event-Typ kann über bis zu 500 Eigenschaften verfügen. Erfahren Sie im Folgenden mehr über Event-Eigenschaften.

​
Event-Eigenschaften

Verwenden Sie beim Definieren des Event-Schemas das properties-Array, um die Felder zu definieren, an die Sie Daten zum Auftreten von Events senden. Jeder Event-Typ kann über bis zu 500 Eigenschaften verfügen. 
 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]

Mit * markierte Felder sind Pflichtfelder.

FeldTypBeschreibung
name*ZeichenfolgeDer interne Name der Eigenschaft. Muss klein geschrieben werden und zwischen 1 und 500 Zeichen enthalten. Eigenschaft Eigenschaftsnamen müssen eindeutig sein pro Event-Typ. Dieser Wert darf nicht mit dem "[A-Za-z0-9_\\-.]+"-Regex übereinstimmen oder mit hs_beginnen.
label*ZeichenfolgeDas in HubSpot angezeigte Label. Muss klein geschrieben werden und zwischen 1 und 500 Zeichen enthalten.
type*ZeichenfolgeDer Typ der in der Eigenschaft erfassten Daten. Dieser kann einer der folgenden sein: STRING, NUMBER, DATE,ENUMERATION.
optionsArrayFür ENUMERATION-Typeigenschaften gibt dieses Feld die verfügbaren Optionen an. Muss mindestens eine Option enthalten. Jede Option ist ein Objekt mit Folgendem:
  • name: das Label für die in HubSpot angezeigte Option.
    • value
  • : der interne Wert, der durch das Auftreten des Events bereitgestellt wird.
Der name und das label müssen innerhalb des Event-Typs eindeutig sein.
objectPropertyNameZeichenfolgeFalls enthalten, der Name der CRM-Objekt Eigenschaft, die aktualisiert werden soll, wenn Event-Daten an HubSpot gesendet werden. Der Wert in dieser Eigenschaft überschreibt alle anderen in dieser Eigenschaft vorhandenen Werte. Im Folgenden erfahren Sie mehr über das automatische Setzen von CRM-Datensatzeigenschaften.

​
Automatisches Setzen von Eigenschaften

In einigen Fällen möchten Sie möglicherweise die Eigenschaften des CRM-Datensatzes auf Grundlage von App-Daten zum Auftreten von Events ändern. Sie können zum Beispiel den Vor- und Nachnamen eines Kontakts mit neuen, durch das Vorkommnis (z. B. Formularübermittlung ) festgelegten Werten aktualisieren. Um CRM-Datensatzeigenschaften über das Auftreten von Events zu aktualisieren, können Sie eine Event-Eigenschaft mit einer CRM-Eigenschaft innerhalb des Event-Typschemas verknüpfen. Fügen Sie in den Definitionsfeldern für eine bestimmte Event-Eigenschaft das objectPropertyName-Feld ein und geben Sie die zu verknüpfende CRM-Eigenschaft an. Sobald eine Eigenschaft verknüpft ist, aktualisiert HubSpot immer den Wert der Eigenschaft im CRM-Datensatz mithilfe des Werts aus dem letzten Vorkommnis basierend auf dem timestamp-Feld. Das folgende Event-Typschema verknüpft beispielsweise die Event-Eigenschaft customerName mit einer benutzerdefinierten Kontakteigenschaft namens custom_property_name. Wenn die Daten des Event-Vorkommnisses einen Wert für customerNameenthalten, wird custom_property_name im zugehörigen CRM-Datensatz aktualisiert. 
 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

​
Rendering von Vorlagen

Event-Typ-Schemata können headerTemplate- und detailTemplate-Felder enthalten, um zu konfigurieren, wie das Auftreten von Events in CRM-Datensatzchroniken dargestellt wird.
  • headerTemplate: eine einzeilige Beschreibung des Events oben auf der Aktivitätskarte (bis zu 1.000 Zeichen).
  • detailTemplate: die Details des Events im Hauptteil der Aktivitätskarte (bis zu 10.000 Zeichen).
Rendering-Vorlagen werden mithilfe von Markdown mit Handlebars-Vorlagen geschrieben. Diese Vorlagen sind in der Lage, Daten zum Auftreten von Events wie folgt zu rendern:
  • In beiden Vorlagen können Sie auf alle property-Daten zugreifen, die durch das Auftreten des Events mithilfe der Syntax {{propertyName}} übermittelt werden.
  • Im detailTemplate können Sie zusätzlich auf extraData-Werte zugreifen, die durch das Auftreten des Events mithilfe der Syntax {{extraData.fieldName}} übermittelt werden. Sie haben auf jede Stufe von Attributen in extraData anhand von Punktnotation Zugriff; hier ein Beispiel: {{extraData.person1.preferredName}}.
Das extraData-Objekt darf nur gültige JSON-Information enthalten. Ist diese faslch formatiert, wird das Vorkommnis abgelehnt und Sie erhalten eine Fehlerantwort.
Die folgenden Vorlagen verwenden beispielsweise die customerName- und loginLocation-Eigenschaftsdaten zusammen mit dem surveyData-Feld von extraData und wurden durch das Event-Vorkommnis übersendet. Screenshot, der zeigt, wie das folgende Beispiel einer Rendering-Vorlage auf der Chronik eines Kontakts aussieht. 
"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
Da Vorlagen mit Markdown und Handlebars erstellt werden, können Sie die Vorteile von Handlebars-Helpers nutzen, um den Inhalt dynamischer zu gestalten. Die folgende detailTemplate-Vorlage beinhaltet beispielsweise den #if -Helper, um Inhalte bedingt wiederzugeben, je nachdem, ob die Daten des Event-Vorkommnisses das surveyData-Feld in extraData aufweisen.
  • Wenn extraData surveyDataenthält, wird die Umfrageantworten nach der Anmeldung angezeigt.
  • Wenn im Event-Vorkommnis keine surveyData enthalten sind, wird No additional information. gerendert.
Screenshot, der zeigt, wie der folgende Beispielcode in der Chronik des Kontakts aussehen würde. 
"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

​
Verwenden von iframes

Wenn Daten zum Event-Vorkommnis das timelineIFrame-Feld enthalten, verfügt die Aktivitätskarte der Chronik über einen Hyperlink, auf den Benutzer klicken können, um die verlinkten Inhalte in einem iframe zu öffnen. Screenshot eines Links, der aufgrund des timelineIFrame-Feldes in einer Aktivitätskarte erscheint 
"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }
FeldTypBeschreibung
linkLabelZeichenfolgeDer Hyperlink-Text, der den iframe beim Klicken startet.
headerLabelZeichenfolgeDas Label des modalen Fensters, das die iframe-Inhalte anzeigt.
urlZeichenfolgeDie URL des iframe-Contents.
widthGanzzahl:Die Breite des iframe-modalen Dialogfelds.
heightGanzzahl:Die Höhe des modalen iframe.

​
Auftreten von Events

Um Event-Vorkommnisse für einen bestimmten Event-Typ zu senden, führen Sie eine POST-Anfrage an die im Folgenden genannten Endpunkte durch. Die App-Events-API enthält Endpunkte zum Senden von einzelnen Vorkommnissen sowie von Batches mit mehreren Vorkommnissen. Für beide Endpunkte müssen die Daten zum Auftreten von Events anhand eines vorhandenen Event-Typschemas validiert werden, das Sie mit eventTypeName im Anfragetext angeben.
  • Ein einzelnes Vorkommen senden
  • Ein Batch von Vorkommnissen senden
Um ein einzelnes Event-Vorkommnis zu senden, stellen Sie eine POST-Anfrage an /integrators/timeline/v4/events.Fügen Sie im Anfragetext die Daten über das Auftreten des Events ein und halten Sie sich dabei an das definierte Schema des Event-Typs.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},
Schließen Sie im Anfragetext Daten basierend auf dem definierten Event-Typschema ein. Der Anfragetext muss den eventTypeName enthalten, den Sie über die API abrufen können. 
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

Mit * markierte Felder sind Pflichtfelder.

FeldTypBeschreibung
eventTypeName*ZeichenfolgeDer vollständig qualifizierte Name des Event-Typs, den Sie verwenden, um das Event über die API zu identifizieren. Dieser Wert wird von HubSpot automatisch festgelegt und lässt sich nach der Erstellung des Event-Typs über die API abrufen. Dieser Wert kann nach der Erstellung nicht mehr geändert werden.
objectId*ZeichenfolgeDie ID des CRM-Datensatzes, der dem Auftreten des Events zugeordnet werden soll. Dieses Feld kann für alle Arten von CRM-Datensätzen verwendet werden und ist die empfohlene ID. Erfahren Sie mehr über CRM Datensatzzuordnung.
emailZeichenfolgeFür die Kontakt-Zuordnung können Sie die E-Mail-Adresse des zuzuordnenden Kontakts angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
utkZeichenfolgeFür die Kontaktzuordnung können Sie das Benutzer-Token eines vorhandenen Kontakts angeben, der zugeordnet werden soll. Erfahren Sie mehr über CRM-Datensatzzuordnung.
domainZeichenfolgeFür eine Unternehmenszuordnung können Sie die Website Domain eines vorhandenen Unternehmens angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
timestampZeichenfolgeLegt den Zeitpunkt des Auftretens des Events fest (ISO 8601-Format). Wenn nichts angegeben wird, verwendet HubSpot standardmäßig den Zeitstempel, an dem die Daten des Event-Vorkommnisses gesendet werden.
propertiesObjektSchlüsselwert-Paare von Eigenschaftsnamen und -werten für Eigenschaften, die Sie für den Event-Typ definiert haben.
extraDataArrayFalls eingefügt, werden zusätzliche Informationen für das Rendern der Chronik bereitgestellt. Muss ein gültiges JSON-Format aufweisen. Erfahren Sie mehr über zusätzliche Daten in Rendering-Vorlagen.
timelineIFrameObjektWenn dies verwendet wird, enthält die Chronik-Karte einen Hyperlink, der es Benutzern ermöglicht, die verlinkten Inhalte in einem iframe zu öffnen. Erfahren Sie mehr über die Verwendung von iframes.
idZeichenfolgeEine eindeutige ID für das jeweilige Event-Vorkommnis. Muss innerhalb des Event-Typs eindeutig sein. Falls nicht anders angegeben, generiert HubSpot eine zufällige UUID. Wenn mehrere Events die gleiche ID haben, wird die erste akzeptiert und alle anderen abgelehnt.
Auch wenn Vorkommnisse nicht validiert werden können, werden erfolgreich validierte weiterhin akzeptiert und beibehalten. Die Fehlernachricht gibt Aufschluss darüber, was Sie beheben müssen. Screenshot einer Beispielfehlermeldung, die beim Senden von Daten über das Auftreten von Events angezeigt wird

​
Zuordnung von Datensätzen

Jedes Auftreten eines Events muss einem CRM-Datensatz zugeordnet werden, wobei der CRM-Objekttyp durch das Event-Typschema definiert ist. Die App-Events-API enthält mehrere Felder, mit denen sich Daten von Event-Vorkommnissen CRM-Datensätzen zuordnen lassen. Für alle unterstützten CRM-Objekte wird empfohlen, das objectId-Feld zu verwenden. Es gibt jedoch einige Situationen, in denen Sie vielleicht andere Felder bevorzugen.
  • utk/email: Wenn Sie die ID des Kontakts nicht kennen, verwenden Sie das utk-Feld und/oder email-Feld zur Identifizierung. Die Angabe dieser beiden IDs ermöglicht es Ihnen auch, Kontakte zu erstellen und zu aktualisieren. Zum Beispiel:
    • Wenn utk mit einem vorhandenen Kontakt übereinstimmt, jedoch email nicht, aktualisiert HubSpot den Kontakt mit der neuen E-Mail-Adresse.
    • Ist kein objectId angegeben, wird das Auftreten des Events einem vorhandenen Kontakt zugeordnet, der mit utk/email übereinstimmt, oder HubSpot erstellt einen neuen Kontakt, wenn keine Übereinstimmung vorliegt.
    • Beachten Sie bitte, dass anhand von utk allein kein neuer Kontakt erstellt werden kann. Sie sollten immer email zusammen mit utk erwähnen, um eine ordnungsgemäße Zuordnung zu gewährleisten.
  • domain: Für Unternehmenszuordnungen müssen Sie das objectId angeben, können aber auch domain einschließen, um die domain-Eigenschaft dieses Unternehmens zu aktualisieren.