Referenz für App-Events (BETA)

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.

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 für den Header der Aktivitätskarte der CRM-Chronik. Kann bis zu 1.000 Zeichen lang sein.
`detailTemplate`	Zeichenfolge	Der Rendering-Vorlage 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.

 "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: `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.
`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 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.

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

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
  }

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.

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"
  }
},

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.

{
  "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 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.

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. 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.
`email`	Zeichenfolge	Für die Kontakt-Zuordnung können Sie die E-Mail-Adresse des zuzuordnenden Kontakts angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
`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.
`domain`	Zeichenfolge	Für eine Unternehmenszuordnung können Sie die Website Domain eines vorhandenen Unternehmens angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
`timestamp`	Zeichenfolge	Legt 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.
`properties`	Objekt	Schlüsselwert-Paare von Eigenschaftsnamen und -werten für Eigenschaften, 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.
`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.
`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

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.

Integrationen erstellen

Funktionen hinzufügen

Im HubSpot Marketplace veröffentlichen

Referenz für App-Events (BETA)

Projektstruktur

Schema des Event-Typs

Event-Eigenschaften

Automatisches Setzen von Eigenschaften

Rendering von Vorlagen

Verwenden von iframes

Auftreten von Events

Zuordnung von Datensätzen

​Projektstruktur

​Schema des Event-Typs

​Event-Eigenschaften

​Automatisches Setzen von Eigenschaften

​Rendering von Vorlagen

​Verwenden von iframes

​Auftreten von Events

​Zuordnung von Datensätzen

Projektstruktur

Schema des Event-Typs

Event-Eigenschaften

Automatisches Setzen von Eigenschaften

Rendering von Vorlagen

Verwenden von iframes

Auftreten von Events

Zuordnung von Datensätzen