Letzte Änderung: 11. September 2025
Um App-Event-Daten an HubSpot zu senden, erstellen Sie zunächst einen Event-Typ mithilfe eines Entwicklerprojekts. Der Event-Typ ist ein JSON-Schema, das die Struktur, Eigenschaften und Validierungsregeln für mit dem Auftreten von Events verbundene Daten definiert, die von Ihnen gesendet werden. Dazu gehören der Event-Name, das Anzeigelabel, das Ziel-CRM-Objekt und die Event-Eigenschaften. Event-Typen enthalten auch Definitionen für Anzeige-Vorlagen für die CRM-Chronik-Darstellung.
Die in dieser Dokumentation beschriebenen App-Events sind für Apps gedacht, die mithilfe von Entwicklerprojekten für den App Marketplace erstellt wurden. Um benutzerdefiniertes Event-Reporting für andere Arten von Integrationen zu erstellen, können Sie stattdessen benutzerdefinierte Events verwenden.

​
Voraussetzungen

So nehmen Sie eine Typdefinition für App-Events in Ihr Projekt auf:
  • Dazu müssen Sie die HubSpot CLI-Version 7.5.4 oder eine höhere Version verwenden. Sie können überprüfen, welche Version des CLI Sie haben, indem Sie hs --version ausführen und aktualisieren, indem Sie npm i -g @hubspot/cli@next verwenden.
  • Ihr Projekt muss eingesetzt werden, bevor Sie es aktualisieren können, um eine App-Event-Komponente aufzunehmen.

​
Ihre Projektdateien einrichten

Wenn Sie zuvor eine öffentliche App mit einem Chronik-Event erstellt haben, erfahren Sie hier mehr über deren Migration zur Entwicklerplattform.
1

App-Konfiguration und Projektstruktur

Zum Erstellen einer neuen Typdefinition für App-Events in Ihrem Projekt aktualisieren Sie Ihre der App-Konfiguration dienende hsmeta.json-Datei, um den timeline-Bereich im requiredScopes-Feld zu berücksichtigen. Dies ist erforderlich, damit App-Event-Daten in CRM-Datensatzchroniken angezeigt werden. Installationsprogramme müssen diesen Bereich zulassen, sodass Ihre Event-Daten erfolgreich gesendet werden können.
"requiredScopes": [
  "timeline"
],
Beachten Sie, dass Sie je nach den Funktionen, die Ihre App enthält, möglicherweise weitere Bereiche hinzufügen müssen.
Statten Sie das app/-Verzeichnis Ihres Projekts mit einem app-events-Verzeichnis aus. Anschließend fügen Sie in app-events/ eine JSON-Konfigurationsdatei hinzu, um den App-Event-Typ zu definieren. Diese Datei kann einen beliebigen Namen haben, muss aber mit *-hsmeta.json enden. Sie können bis zu 750 Event-Typen pro App aufnehmen, wobei jeder seine eigene *-hsmeta.json-Datei besitzt.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

Das Event-Typschemas konfigurieren

Richten Sie in der *-hsmeta.json-Event-Typdatei Ihr Event-Typschema ein. Dieses Schema konfiguriert Event-Typattribute wie Name, die Vorlage zum Anzeigen des CRM-Datensatzes in der Chronik und den CRM-Objekttyp, dem Event-Daten zugeordnet werden sollen.Während einige dieser Felder nach der Erstellung aktualisiert werden können, lassen sich die name - und objectType -Felder dann nicht mehr ändern.Das folgende Event-Typschema könnte beispielsweise für die Nachverfolgung von Kundenanmeldungsevents verwendet werden.
{
 "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 sein app-event.
name*ZeichenfolgeDas in HubSpot angezeigte Label (bis zu 50 Zeichen). Dieser Wert kann nach der Erstellung nicht mehr aktualisiert werden.
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 mehr über Eigenschaften, einschließlich Anforderungen und Einschränkungen, in der Referenzdokumentation für App-Events.
3

Änderungen zu HubSpot hochladen

Laden Sie Ihr Projekt mit dem hs project upload-Befehl nach HubSpot hoch.
hs project upload
Während der Erstellungsphase validiert HubSpot den Event-Typ. Bei Fehlern bei der Schemavalidierung gibt das CLI eine Fehlermeldung zurück, die angibt, was zu beheben ist.Standardmäßig setzt HubSpot das Projekt nach einem erfolgreichen Build automatisch ein. Wenn Sie diese Option in Ihren Projekteinstellungen deaktiviert haben, können Sie mithilfe von hs project deploy dies manuell tun.Danach ist Ihr App-Event-Typ verfügbar und kann zum Empfangen von Daten über das Auftreten von Events verwendet werden.

​
fullyQualifiedName abrufen

Um Daten zum Auftreten von Events für den Event-Typ zu senden, müssen Sie den fullyQualifiedName über die App-Events-API abrufen. Dieser Name identifiziert den Event-Typ und muss in allen App-Event-API-Operationen enthalten sein. Um den eventTypeName abzurufen, stellen Sie eine POST-Anfrage an https://api.hubapi.com/integrators/timeline/v4/types/projects. Schließen Sie im Anfragetext Folgendes ein:
  • Ein projectName-Feld, das durch den name-Wert aus der hsproject.json-Datei Ihres Projekts bestimmt wird.
  • Ein developerSymbol-Feld, das durch den uid-Wert aus der *-hsmeta.json-Event-Typ-Konfigurationsdatei bestimmt wird.
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
Die Antwort enthält den Projektnamen, den Event-Typnamen und den fullyQualifiedName. 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
Der fullyQualifiedName-Wert ändert sich nie, sodass Sie ihn bedenkenlos in Ihre Implementierung aufnehmen können. Die API begrenzt die Häufigkeit, mit der dieser Wert pro Tag abrufbar ist, und kann nicht programmgesteuert verwendet werden.

​
Event-Typen verwalten

Um einen Event-Typ nach der Erstellung zu aktualisieren, müssen Sie nur das Event-Typschema in Ihrem Projekt aktualisieren und dann erneut hochladen, um die App zu erstellen und einzusetzen. Wenn Sie einen Event-Typ nicht mehr verwenden möchten, können Sie ihn aus Ihrem Projekt löschen. Bevor Sie jedoch einen Event-Typ löschen, sollten Sie Folgendes beachten:
  • Das Löschen eines Event-Typs kann nicht mehr rückgängig gemacht werden.
  • Wenn Sie einen Event-Typ löschen, werden sowohl der Event-Typ als auch alle Vorkommnisse dieses Typs von allen Accounts entfernt, die die App installiert haben.
  • Nach dem Löschen eines Event-Typs funktionieren andere HubSpot-Tools, die auf diesem Event-Typ basieren, nicht mehr, z. B. Berichte und Workflows. Zum Löschen eines Event-Typs entfernen Sie die *-hsmeta.json-Event-Typ-Konfigurationsdatei aus Ihrem Projekt, laden dann das Projekt hoch und stellen es bereit.

​
Einen vorhandenen Chronik-Event-Typ migrieren

Wenn Sie über eine bestehende öffentliche App mit einem Chronik-Event verfügen, können Sie diese mithilfe des CLI auf die Entwicklerplattform migrieren.
Bevor Sie Ihre App migrieren:
  • Lesen Sie den Migrationsleitfaden für öffentliche Apps, um mehr über die aktuellen Aspekte und Einschränkungen der Beta-Version der Entwicklerplattform zu erfahren.
  • Nach der Migration eines bestehenden Chronik-Event-Typs (v1/v3) auf die Entwicklerplattform haben Sie 7 Tage Zeit, vorhandene v1/v3-Chronik-Event-API-Anfragen auf die neuen v4-Endpunkte zu ändern, einschließlich Event-Typ-Vorkommnisse und Instanz-API-Anfragen. Nach 7 Tagen geben alle vorhandenen Aufrufe von v1/v3-Event-Endpunkte 401-Fehler zurück.
    • Zum Erstellen und Aktualisieren von Event-Typen und Vorlagen müssen Sie die API nicht mehr verwenden. Stattdessen verwalten Sie sie direkt im Projekt über die Event-Typ-Konfigurationsdatei.
    • Zum Senden von Daten über das Auftreten von Events müssen Sie die v4-Endpunkte verwenden, die sowohl über Single- als auch Batch-Send-Endpunkte verfügen.
So migrieren Sie Ihre App:
  • Führen Sie im Terminal hs app migrate aus und folgen Sie dann den Terminalanweisungen, um Ihre App und Chronik-Events zu migrieren.
  • Sobald der Migrationsprozess abgeschlossen ist, befindet sich Ihre App in einem Entwicklerprojekt und ein lokales Projektverzeichnis wird für Sie erstellt.
  • Um das Projekt in HubSpot zu öffnen, gehen Sie zum lokalen Projektverzeichnis und führen dann hs project open aus.
Beachten Sie, dass die generierten Konfigurationsdateien (*-hsmeta.json) Felder mit null-Werten enthalten können. Diese Felder sind Überreste der Migration und können problemlos entfernt werden.

​
Nächste Schritte

Nachdem Sie einen Event-Typ erstellt haben, können Sie nun darüber informieren, wie Sie Daten beim Auftreten von Events über die API senden. Sie können auch die Referenzdokumentation für App-Events lesen, um weitere App-Events zu erstellen und anzupassen.