Benutzerdefinierte Events definieren

Bereichsanforderungen

Mit benutzerdefinierten Events können Sie Events definieren und nachverfolgen, die für Ihr Unternehmen spezifisch sind, z. B. Events auf Ihrer Website oder in einer App. Sie können Events konfigurieren, um Informationen in Eigenschaften zu speichern, die Sie dann in allen HubSpot-Tools nutzen können. Um Daten von benutzerdefinierten Events an HubSpot zu senden, müssen Sie zunächst das Event definieren. Dies ist ähnlich wie bei benutzerdefinierten CRM-Objekten, bei denen Sie zunächst das benutzerdefinierte Objekt definieren müssen, bevor Sie einzelne Datensätze für dieses Objekt erstellen können. Eine Event-Definition enthält Details wie Metadaten, CRM-Objektzuordnungen und Eigenschaften. Im Folgenden erfahren Sie mehr über das Erstellen und Verwalten von Event-Definitionen mithilfe der API. Um zu erfahren, wie Sie Event-Definitionen erstellen können, ohne die API zu verwenden, sehen Sie sich diesen Artikel in der Wissensdatenbank von HubSpot an.

Eine Event-Definition erstellen

Um das benutzerdefinierte Event-Schema zu erstellen, führen Sie eine POST-Anfrage an events/v3/event-definitions durch. Fügen Sie in den Anfragetext Definitionen für Ihr Event-Schema ein, einschließlich Label, Name, CRM-Objektzuordnungen und benutzerdefinierte Eigenschaften. Der folgende Anforderungstext enthält ein einfaches Beispiel für eine Event-Definition:

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}

Wenn Sie Event-Abschlüsse automatisch mit Datensätzen eines bestimmten CRM-Objekttyps verknüpfen möchten, können Sie ein customMatchingId in Ihre POST-Anfrage aufnehmen. Definieren Sie in diesem Feld ein primaryObjectRule-Objekt mit zwei Feldern: die eindeutige Objekteigenschaft, die Sie zuvor als targetObjectPropertyName eingerichtet haben, und eine der Eigenschaften, die Sie in den propertyDefinitions aus Ihrer Event-Definition definiert haben. Der folgende Anforderungstext gibt beispielsweise einecustomMatchingId an, die mit einem CRM-Objekteigenschaftsnamen von "unique_object_property" und dem Event-Eigenschaftsnamen von "string_property" übereinstimmt:

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}

Eine vollständige Liste der verfügbaren Parameter für den Anforderungstext finden Sie in der folgenden Tabelle:

Parameter	Typ	Beschreibung
`label`	Zeichenfolge	Das für Menschen lesbare Label des Events, das in HubSpot angezeigt wird (bis zu 100 Zeichen). Lange Labels können in bestimmten Teilen der HubSpot-Benutzeroberfläche abgeschnitten werden.
`name`	Zeichenfolge	Der eindeutige, interne Name des Events, mit dem Sie über die API auf das Event verweisen können. Wenn kein Wert angegeben wird, generiert HubSpot automatisch einen Wert auf der Grundlage des Labels. Diese Eigenschaft kann nach dem Erstellen der Event-Definition nicht mehr geändert werden. Diese Eigenschaft darf nur Kleinbuchstaben, Zahlen, Unterstriche und Bindestriche enthalten (bis zu 50 Zeichen). Das erste Zeichen muss ein Buchstabe sein.
`description`	Zeichenfolge	Die Beschreibung des Events, die in HubSpot angezeigt wird.
`primaryObject`	Zeichenfolge	: Der Typ des CRM-Objekts, dem die Event-Daten zugeordnet werden. Event-Abschlüsse werden in den CRM-Datensätzen dieses Objekttyps angezeigt. Kann entweder `"CONTACT"` (Standard), `"COMPANY"`, `"DEAL"`, `"TICKET"` oder `"<CUSTOM_OBJECT_NAME>"` sein. Diese kann nicht mehr geändert werden, nachdem die Event-Definition erstellt wurde.
`propertyDefinitions`	Array	Zusätzlich zu den standardmäßigen Event-Eigenschaften von HubSpot können Sie dieses Array einschließen, um benutzerdefinierte Event-Eigenschaften (bis zu 50) zu definieren. Fügen Sie für jedes Eigenschaftsobjekt die folgenden Felder hinzu: `name`: der interne Name der Eigenschaft, den Sie beim Senden von Event-Daten über die API verwenden. `label`: das Label der Eigenschaft in der App. `type`: der Eigenschaftstyp. Standardmäßig wird `string` verwendet. `options`: Für Eigenschaften des Typs `enumeration` definiert dieses Array die verfügbaren Werte. Muss sowohl `label` als auch `value` für jede Option enthalten. `description`: Text, der die Eigenschaft beschreibt.
`customMatchingId`	Objekt	Als Alternative zur Aufnahme der `objectId` des Zielobjekts in die Daten zu Event-Abschlüssen definiert dieses optionale Feld eine Regel zur automatischen Verknüpfung von Event-Abschlüssen mit Datensätzen des angegebenen CRM-Objekttyps. Dazu wird der Wert einer Eigenschaft in den Event-Daten mit dem Wert einer eindeutigen Eigenschaft im Zielobjekt abgeglichen. Dieses Objekt muss ein verschachteltes `primaryObjectRule`-Objekt enthalten, das wiederum zwei Felder enthalten muss: `targetObjectPropertyName`: eine Zeichenfolge, die den Namen der eindeutigen Eigenschaft auf dem Ziel-CRM-Objekt angibt, die für den Abgleich verwendet werden soll. `eventPropertyName`: eine Zeichenfolge, die den Namen der Eigenschaft in den benutzerdefinierten Event-Daten angibt, der für den Abgleich verwendet werden soll.
`includeDefaultProperties`	Boolesches Feld	Ein optionales Feld, das angibt, ob das Event den Satz der Standard-Event-Eigenschaften enthalten soll. Wenn kein Wert angegeben wird, wird dieses Feld automatisch auf `true` festgelegt.

Event-Eigenschaften

Benutzerdefinierte Eigenschaften von Events werden verwendet, um Informationen über einzelne benutzerdefinierte Event-Abschlüsse zu speichern. Diese Eigenschaften sollten verwendet werden, wenn sie für das Senden von Event-Abschlüssen geeignet sind, aber sie sind nicht erforderlich, damit ein Event-Abschluss gültig ist. Für jede Event-Definition bietet HubSpot einen Standardsatz von 32 Eigenschaften. Darüber hinaus können Sie bis zu 50 benutzerdefinierte Eigenschaften pro Event-Eigenschaft erstellen. Eigenschaften können einer der folgenden Typen sein:

bool: eine Eigenschaft, die einen booleschen Wert erhält. Werte müssen als true oder false angegeben werden.
date: Eine Eigenschaft, die ein Datum empfängt, das einen bestimmten Tag, einen bestimmten Monat und ein bestimmtes Jahr darstellt. Werte müssen in UTC-Zeit angegeben werden und können als ISO 8601-Zeichenfolgen oder EPOCH-Zeitstempel in Millisekunden (z. B. Mitternacht UTC) formatiert werden.
datetime: Eine Eigenschaft, die Epochen-Millisekunden- oder ISO8601-Werte empfängt, die einen Zeitstempel darstellen.
enumeration: Eine Eigenschaft mit vordefinierten Optionen. Fügen Sie bei der Erstellung dieses Eigenschaftstyps ein options-Array ein, um die verfügbaren Werte festzulegen.
number: eine Eigenschaft, die numerische Werte mit bis zu einer Dezimalstelle empfängt.
string: eine Eigenschaft, die Klartext-Zeichenfolgen empfängt. Wenn der Eigenschaftsname die Wörter url, referrer oder link enthält, kann der Eigenschaftswert bis zu 1024 Zeichen lang sein. Ansonsten können die Eigenschaftswerte bis zu 256 Zeichen lang sein.

Im Folgenden erfahren Sie mehr über die standardmäßigen Event-Eigenschaften von HubSpot, wie Sie neue Eigenschaften für bestehende Events definieren und wie Sie bestehende benutzerdefinierte Event-Eigenschaften aktualisieren.

Standard-Event-Eigenschaften von HubSpot

hs_asset_description
hs_asset_type
hs_browser
hs_campaign_id
hs_city
hs_country
hs_device_name
hs_device_type
hs_element_class
hs_element_id
hs_element_text
hs_language
hs_link_href
hs_operating_system
hs_operating_version
hs_page_content_type
hs_page_id
hs_page_title
hs_page_url
hs_parent_module_id
hs_referrer
hs_region
hs_screen_height
hs_screen_width
hs_touchpoint_source
hs_tracking_name
hs_user_agent
hs_utm_campaign
hs_utm_content
hs_utm_medium
hs_utm_source
hs_utm_term

Neue Eigenschaften definieren

Um eine neue Eigenschaft für ein bestehendes benutzerdefiniertes Event zu definieren, führen Sie eine POST-Anfrage an events/v3/event-definitions/{eventName}/property durch. Fügen Sie im Anfragetext die Definition für Ihre Eigenschaft ein.

{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}

Bei der Benennung Ihrer Eigenschaften sollten Sie Folgendes beachten:

Sobald Sie eine Eigenschaft erstellt haben, kann der Name der Eigenschaft nicht mehr geändert werden.
Der Name darf nur Kleinbuchstaben, Zahlen, Unterstriche und Bindestriche enthalten.
Das erste Zeichen des Eigenschaftsnamens muss ein Buchstabe sein.
Der Eigenschaftsname und das Label können jeweils bis zu 50 Zeichen lang sein.
Wenn kein Eigenschaftsname angegeben wird, wird dieser automatisch anhand des Labels der Eigenschaft generiert.
Lange Label können in bestimmten Teilen der HubSpot-Benutzeroberfläche abgeschnitten werden.

Bestehende benutzerdefinierte Eigenschaften aktualisieren

Um eine bestehende Eigenschaft eines benutzerdefinierten Events zu aktualisieren, führen Sie eine PATCH-Anfrage an events/v3/event-definitions/{eventName}/property durch. Die einzigen Felder, die für eine Eigenschaft aktualisiert werden können, sind die Felder label, description und options für Aufzählungseigenschaften.

Hinweis:

Um den Typ der Eigenschaft zu ändern, verwenden Sie den DELETE-Endpunkt, um die Eigenschaft zu löschen und mit dem richtigen Typ neu zu erstellen.

Eine Eigenschaft löschen

Um eine vorhandene Eigenschaft eines benutzerdefinierten Events zu löschen, führen Sie eine DELETE-Anfrage an events/v3/event-definitions/{eventName}/property/{propertyName} durch. Wenn eine Eigenschaft gelöscht wird, steht sie nicht mehr für die Verwendung in zukünftigen Event-Abschlüssen zur Verfügung. Bei früheren Abschlüssen bleiben die Eigenschaftenwerte erhalten.

Ein Event aktualisieren

Um ein bestehendes benutzerdefiniertes Event-Schema zu aktualisieren, führen Sie eine PATCH-Anfrage an events/v3/event-definitions/{eventName} durch. Die einzigen Event-Definitionsfelder, die aktualisiert werden können, sind label und description.

{
  "label": "Event label",
  "description": "A description of the event"
}

Ein Event löschen

Um ein benutzerdefiniertes Event zu löschen, führen Sie eine DELETE-Anfrage an events/v3/event-definitions/{eventName} durch. Wenn Sie ein benutzerdefiniertes Event löschen, wird es aus allen anderen HubSpot-Tools entfernt, die darauf verweisen, z. B. aus Workflows und Berichten.

Bitte beachten Sie beim Löschen eines Events Folgendes:

Es werden alle Events für diese Event-Definition gelöscht und können nicht wiederhergestellt werden.
Zuvor gelöschte eventName-Eigenschaften können nicht mehr verwendet werden. Seien Sie also vorsichtig, wenn Sie ein Event löschen.

Vorhandene Event-Definitionen abrufen

Um eine einzelne Event-Definition abzurufen, führen Sie eine GET-Anfrage an events/v3/event-definitions/{eventName} durch. Um Event-Definitionen nach bestimmten Kriterien zu durchsuchen, führen Sie eine GET-Anfrage an events/v3/event-definitions durch. Sie können die folgenden Abfrageparameter angeben, um Ihre Suche zu verfeinern:

searchString: sucht nach Events, die die angegebenen Zeichen im Feld name enthalten. Die Suche ist nicht unscharf, sondern ist eine naive contains-Suche.
after: eine gehashte Zeichenfolge, die in seitenweisen Antworten zum Anzeigen der nächsten Seite der Suchergebnisse bereitgestellt wird.
limit: die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen.
includeProperties: ein boolescher Wert, der angibt, ob Event-Eigenschaften in die zurückgegebenen Ergebnisse aufgenommen werden sollen.

Account & Einstellungen

App-Verwaltung

Authentifizierung

Automatisierung

CMS

Kommunikationseinstellungen

Konversationen

CRM

Veranstaltungen

Dateien

Marketing

Zeitplaner

Webhooks

Benutzerdefinierte Events definieren

Eine Event-Definition erstellen

Event-Eigenschaften

Standard-Event-Eigenschaften von HubSpot

Neue Eigenschaften definieren

Bestehende benutzerdefinierte Eigenschaften aktualisieren

Hinweis:

Eine Eigenschaft löschen

Ein Event aktualisieren

Ein Event löschen

Bitte beachten Sie beim Löschen eines Events Folgendes:

Vorhandene Event-Definitionen abrufen

​Eine Event-Definition erstellen

​Event-Eigenschaften

​Standard-Event-Eigenschaften von HubSpot

​Neue Eigenschaften definieren

​Bestehende benutzerdefinierte Eigenschaften aktualisieren

​Hinweis:

​Eine Eigenschaft löschen

​Ein Event aktualisieren

​Ein Event löschen

​Bitte beachten Sie beim Löschen eines Events Folgendes:

​Vorhandene Event-Definitionen abrufen

Eine Event-Definition erstellen

Event-Eigenschaften

Standard-Event-Eigenschaften von HubSpot

Neue Eigenschaften definieren

Bestehende benutzerdefinierte Eigenschaften aktualisieren

Hinweis:

Eine Eigenschaft löschen

Ein Event aktualisieren

Ein Event löschen

Bitte beachten Sie beim Löschen eines Events Folgendes:

Vorhandene Event-Definitionen abrufen