> ## 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. # Benutzerdefinierte Events definieren export const ScopesList = ({scopes = [], description = "Diese API erfordert einen der folgenden Bereiche:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; 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](/api-reference/events-send-event-completions-v3/guide) 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](https://knowledge.hubspot.com/de/reports/create-custom-events) 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: ```json theme={null} { "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 eine`customMatchingId` an, die mit einem CRM-Objekteigenschaftsnamen von `"unique_object_property"` und dem Event-Eigenschaftsnamen von `"string_property"` übereinstimmt: ```json theme={null} { "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. | | `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 `""` 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](#hubspot-s-default-event-properties) 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](#event-properties). 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](#hubspot-s-default-event-properties) 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](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties) 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](#define-new-properties) und wie Sie [bestehende benutzerdefinierte Event-Eigenschaften aktualisieren](#update-existing-custom-properties). ### 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. ```json theme={null} { "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`. ```json theme={null} { "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: 1. Es werden alle Events für diese Event-Definition gelöscht und können nicht wiederhergestellt werden. 2. 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.