> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.de/docs/llms.txt > Use this file to discover all available pages before exploring further. # Referenz für App-Events (BETA) > Referenzinformationen für App-Events in der neuesten Version der Entwicklerplattform. 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. ```shell theme={null} 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](/apps/developer-platform/build-apps/app-configuration). * 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. ```json theme={null} { "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.

| Feld | Typ | Beschreibung | | ------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `uid`\* | Zeichenfolge | Eine interne eindeutige ID für den Event-Typ. | | `type`\* | Zeichenfolge | Der Typ der Komponente. Muss `app-event` sein. | | `name`\* | Zeichenfolge | Das in HubSpot angezeigte Label (bis zu 50 Zeichen). Dieser Wert lässt sich nach der Erstellung nicht mehr aktualisieren. | | `objectType`\* | Zeichenfolge | Der 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`. | | `headerTemplate` | Zeichenfolge | Die [Rendering-Vorlage](#rendering-templates) für den Header der Aktivitätskarte der CRM-Chronik. Kann bis zu 1.000 Zeichen lang sein. | | `detailTemplate` | Zeichenfolge | Der [Rendering-Vorlage](#rendering-templates) für den Text der CRM Chronik Aktivitätskarte. Kann bis zu 10.000 Zeichen lang sein. | | `properties` | Array | Eigenschaften, 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. ```json theme={null} "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.

| Feld | Typ | Beschreibung | | -------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name`\* | Zeichenfolge | Der 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`\* | Zeichenfolge | Das in HubSpot angezeigte Label. Muss klein geschrieben werden und zwischen 1 und 500 Zeichen enthalten. | | `type`\* | Zeichenfolge | Der Typ der in der Eigenschaft erfassten Daten. Dieser kann einer der folgenden sein: `STRING`, `NUMBER`, `DATE`,`ENUMERATION`. | | `options` | Array | Für `ENUMERATION`-Typeigenschaften gibt dieses Feld die verfügbaren Optionen an. Muss mindestens eine Option enthalten. Jede Option ist ein Objekt mit Folgendem: Der `name` und das `label` müssen innerhalb des Event-Typs eindeutig sein. | | `objectPropertyName` | Zeichenfolge | Falls 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 `customerName`enthalten, wird `custom_property_name` im zugehörigen CRM-Datensatz aktualisiert. ```json theme={null} "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](https://www.markdownguide.org/basic-syntax/) mit [Handlebars-Vorlagen](https://handlebarsjs.com/guide/) 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](#event-occurrences). ![Screenshot, der zeigt, wie das folgende Beispiel einer Rendering-Vorlage auf der Chronik eines Kontakts aussieht.](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/example-timeline-event-rendering-template.png) ```json theme={null} "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` ](https://handlebarsjs.com/guide/builtin-helpers.html#if)-Helper, um Inhalte bedingt wiederzugeben, je nachdem, ob die Daten des Event-Vorkommnisses das `surveyData`-Feld in `extraData` aufweisen. * Wenn `extraData` `surveyData`enthä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.](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/if-helper-in-handlebars-template.png) ```json theme={null} "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](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/app-events-timeline-card-iframe-link.png) ```json theme={null} "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 } ``` | Feld | Typ | Beschreibung | | ------------- | ------------ | --------------------------------------------------------------- | | `linkLabel` | Zeichenfolge | Der Hyperlink-Text, der den iframe beim Klicken startet. | | `headerLabel` | Zeichenfolge | Das Label des modalen Fensters, das die iframe-Inhalte anzeigt. | | `url` | Zeichenfolge | Die URL des iframe-Contents. | | `width` | Ganzzahl: | Die Breite des iframe-modalen Dialogfelds. | | `height` | Ganzzahl: | 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. 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. ```json theme={null} { "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000", "objectId": "123456", "id": "login-1", "properties": { "customerName": "Mark S.", "loginLocation": "mobileApp" } }, ``` Um einen Batch von Event-Vorkommnissen zu senden, führen Sie eine `POST`-Anfrage an `/integrators/timeline/v4/events/batch` durch. Der Anfragetext kann bis zu 500 durch Kommata getrennte Event-Vorkommnisobjekte innerhalb eines `inputs`-Arrays enthalten. Auch wenn Vorkommnisse nicht validiert werden können, werden erfolgreich validierte weiterhin akzeptiert und beibehalten. ```json theme={null} { "inputs": [ { "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000", "id": "login_event_100", "objectId": "769851", "properties": { "customerName": "Tim", "loginLocation": "mobileApp" }, "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" } ] } }, { "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000", "id": "login_event_101", "objectId": "769851", "properties": { "customerName": "Tim", "loginLocation": "website" }, "extraData": {} } ] } ``` 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](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) können. ```json theme={null} { "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.

| Feld | Typ | Beschreibung | | ---------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eventTypeName`\* | Zeichenfolge | Der 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](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname). Dieser Wert kann nach der Erstellung nicht mehr geändert werden. | | `objectId`\* | Zeichenfolge | Die 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](#crm-record-association). | | `email` | Zeichenfolge | Für die Kontakt-Zuordnung können Sie die E-Mail-Adresse des zuzuordnenden Kontakts angeben. Erfahren Sie mehr über [CRM-Datensatzzuordnung](#crm-record-association). | | `utk` | Zeichenfolge | Für die Kontaktzuordnung können Sie das Benutzer-Token eines vorhandenen Kontakts angeben, der zugeordnet werden soll. Erfahren Sie mehr über [CRM-Datensatzzuordnung](#crm-record-association). | | `domain` | Zeichenfolge | Für eine Unternehmenszuordnung können Sie die Website Domain eines vorhandenen Unternehmens angeben. Erfahren Sie mehr über [CRM-Datensatzzuordnung](#crm-record-association). | | `timestamp` | Zeichenfolge | Legt den Zeitpunkt des Auftretens des Events fest ([ISO 8601-Format](https://en.wikipedia.org/wiki/ISO_8601)). Wenn nichts angegeben wird, verwendet HubSpot standardmäßig den Zeitstempel, an dem die Daten des Event-Vorkommnisses gesendet werden. | | `properties` | Objekt | Schlüsselwert-Paare von Eigenschaftsnamen und -werten für [Eigenschaften](/apps/developer-platform/add-features/app-events/reference#event-properties), die Sie für den Event-Typ definiert haben. | | `extraData` | Array | Falls 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](#rendering-templates). | | `timelineIFrame` | Objekt | Wenn 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](#using-iframes). | | `id` | Zeichenfolge | Eine 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](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/timeline-events-api-error-validation-example.png) ### 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.