Benutzerdefinierte Event-Abschlüsse senden

Unterstützte Produkte

Bereichsanforderungen

Benutzerdefinierte Events sind Account-definierte Events, die Event-Details in Event-Eigenschaften speichern. Sie können nicht nur Ihren Tracking-Code anpassen, um Event-Daten an HubSpot zu senden, sondern auch Event-Abschlussdaten über diese API senden. Im Folgenden erfahren Sie, wie Sie die API verwenden, um benutzerdefinierte Events zu erstellen und benutzerdefinierte Event-Daten zu senden bzw. abzurufen.

Das Event definieren

Um Daten zu Event-Abschlüssen an HubSpot zu senden, müssen Sie zunächst das Event selbst definieren, einschließlich seiner Metadaten, CRM-Objektzuordnungen und Eigenschaften. Sie können Events mit der „Benutzerdefinierte Event-Definition“-API definieren, oder wenn Sie ein Marketing Hub Enterprise-Abonnement haben, können Sie das Event in HubSpot erstellen. Bei der Erstellung des Events bietet HubSpot die Möglichkeit, eine Reihe von Standard-Event-Eigenschaften einzubinden, die Sie zum Speichern von Event-Daten verwenden können. Sie können auch zusätzliche Eigenschaften für das Event erstellen. Diese Eigenschaften können jederzeit erstellt oder bearbeitet werden. Sobald Sie Ihr Event eingerichtet haben, können Sie Daten über die API oder durch Anpassen Ihres HubSpot-Tracking-Codes an das Event senden.

Event-Daten senden

Um Event-Daten an HubSpot zu senden, führen Sie eine POST-Anfrage an https://api.hubspot.com/events/v3/send mit Ihren Event-Daten im Anforderungstext durch. Bevor Sie Event-Daten senden, überprüfen Sie die folgenden Beschränkungen, da ein Überschreiten dieser Beschränkungen zu einem Fehler führt.

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

Parameter	Typ	Beschreibung
`eventName`	Zeichenfolge	Der interne Name des Events. Sie finden ihn durch Abfragen Ihrer bestehenden Event-Definitionen oder in der HubSpot-App.
`objectId`	Zeichenfolge	Die ID des CRM-Datensatzes, dem das Event zugeordnet wird. Bei Kontakten können Sie alternativ das `email`-Feld oder das `utk`-Feld verwenden, um den Kontakt anhand der E-Mail-Adresse oder des HubSpot-Benutzer-Tokens zu identifizieren. Alle anderen Objekttypen erfordern `objectId`, es sei denn, für das Event ist eine benutzerdefinierte übereinstimmende ID definiert. Wenn eine `customMatchingId` für das Event definiert ist, nimmt HubSpot Folgendes vor: Die `objectId` wird auf der Grundlage der konfigurierten Zuordnung automatisch festgelegt oder überschrieben. Weitere Informationen finden Sie in der Anleitung für Definitionen für benutzerdefinierte Events.
`occurredAt`	Zeichenfolge	Standardmäßig legt HubSpot den Zeitstempel für den Abschluss des Events auf den Zeitpunkt fest, an dem die Anfrage gesendet wird. Um die Zeit des Event-Abschlusses anzugeben, fügen Sie einen Zeitstempel in ein `occurredAt`-Feld im `POST`-Anforderungstext ein (ISO 8601-Format). Dies kann besonders für die Rückdatierung von Event-Daten hilfreich sein, um die genaue Zeit der Event-Abschlüsse besser widerzuspiegeln.
`properties`	Objekt	Die Event-Eigenschaften, an die Daten gesendet werden sollen. Dies kann die Standard-Event-Eigenschaften von HubSpot oder jede benutzerdefinierte Eigenschaft umfassen, die Sie für die Event definiert haben. Die meisten Standard-Event-Eigenschaften sind Zeichenfolgeneigenschaften, aber Sie können alle Event-Eigenschaften überprüfen, indem Sie entweder die Event Definition abfragen oder zum Event in HubSpot gehen. Wenn eine benutzerdefinierte, übereinstimmende ID für das Event eingerichtet ist, können Sie die `objectId` weglassen. HubSpot versucht, das Event mit einem CRM-Objekt zu verknüpfen, indem die `objectId` zum Event basierend auf der konfigurierten Zuordnung festgelegt wird. Erfahren Sie im Folgenden mehr über Event-Eigenschaften.

Hinweis:

Ein Überschreiten einer der folgenden Beschränkungen führt zu einer fehlgeschlagenen Anfrage:

Das Eigenschaftslabel und der interne Name sind auf 50 Zeichen begrenzt.
URL- und Referrer-Eigenschaften können bis zu 1.024 Zeichen enthalten, alle anderen Eigenschaften dagegen bis zu 256 Zeichen.
Jeder Event-Abschluss kann Daten für bis zu 50 Eigenschaften enthalten.
Interne Eigenschaftsnamen müssen mit einem Buchstaben beginnen und dürfen nur Kleinbuchstaben von a–z, die Zahlen 0–9 sowie Unterstriche enthalten.
Eigenschaften mit dem gleichen internen Namen nach der Kleinschreibung werden als Duplikate betrachtet, und nur eine der Eigenschaften wird beim Abschluss verwendet. HubSpot sortiert in aufsteigender lexikografischer Reihenfolge, wobei die zuletzt angezeigte Eigenschaft unter den ersten 50 Eigenschaften beibehalten wird.
Es gibt ein Limit von 500 eindeutigen Event-Definitionen pro Account.
Es gibt ein Limit von 30 Millionen Event-Abschlüssen pro Monat.

Event-Daten abrufen

Um die Event-Daten abzurufen, führen Sie eine GET-Anfrage an /events/v3/events durch.

Um alle Event-Abschlüsse für ein bestimmtes Event zurückzugeben, fügen Sie den eventType-Parameter zusammen mit dem internen Event-Namen ein (z. B. pe123456_custom_event). Sie können alle Event-Typen mit der Event-Analytics-API abrufen.
Um Event-Abschlüsse für ein bestimmtes Objekt zurückzugeben, schließen Sie den objectType-Parameter zusammen mit den objectId-Parametern oder objectProperty.<property> ein. Unter objectType sollte der Typ des CRM-Objekts angegeben werden (z. B. contact), während die anderen Parameter den eindeutigen Bezeichnerwert für das Objekt angeben (entweder die Datensatz-ID oder einen „Eindeutige ID“-Eigenschaftswert). Für Kontakte können Sie email als eindeutige Eigenschaft zur Identifizierung verwenden.

Um beispielsweise alle Events abzurufen, die von einem bestimmten Kontakt abgeschlossen wurden, könnte Ihre Anfrage-URL wie folgt lauten: /events/v3/events?objectType=contact&objectId=111111. Alternativ können Sie auch die E-Mail-Adresse des Kontakts verwenden: /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com Um die Ergebnisse nach Event-Abschlüssen mit einem bestimmten Event-Eigenschaftswert zu filtern, können Sie den property.<propertyName>-Parameter einschließen. Um beispielsweise Events rund um Seitenbesuche Ihrer Homepage abzurufen, könnte Ihre Anfrage-URL wie folgt lauten: /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

Ersetzen Sie bei Eigenschaftenwerten mit Leerzeichen die Leerzeichen durch entweder %20 oder +. Zum Beispiel: property.hs_page_title=home+page.

In der Referenzdokumentation erfahren Sie mehr über die verfügbaren Parameter.

Event-Eigenschaften

Daten zu Event-Abschlüssen werden in Event-Eigenschaften gespeichert, entweder im Satz der Standard-Event-Eigenschaften oder in benutzerdefinierten Eigenschaften. Fügen Sie beim Senden von Event-Daten ein properties-Objekt mit Schlüssel-Wert-Paaren für die Eigenschaften, die Sie aktualisieren möchten, zusammen mit den zu speichernden Eigenschaftswerten ein.

"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }

Welche Werte Sie senden, hängt vom Typ der Event Eigenschaft ab. Die meisten Standard-Event-Eigenschaften sind einzeiliger Text (Zeichenfolge). Sie können jedoch benutzerdefinierte Eigenschaften beliebigen Typs für jedes Event erstellen. Überprüfen Sie die folgende Tabelle, wenn Sie Eigenschaftswerte formatieren.

Eigenschaftstyp	Beschreibung
`bool`	Ein boolescher Wert, entweder `true` oder `false`.
`enumeration`	Eine Zeichenfolge, die eine Reihe von Optionen enthält. Trennen Sie beim Senden mehrerer Werte diese durch ein Semikolon. In HubSpot entspricht dieser Typ Dropdown-Auswahl-, Optionsfeld-Auswahl und „Mehrere Kontrollkästchen“-Eigenschaften.
`date`	Ein Wert, der 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`	Ein Zeitstempel, der einen bestimmten Tag, einen bestimmten Monat, ein bestimmtes Jahr und eine bestimmte Uhrzeit darstellt. Werte müssen in UTC-Zeit angegeben werden und können als ISO 8601-Zeichenfolgen oder UNIX-Zeitstempel in Millisekunden formatiert werden.
`number`	Ein Zahlenwert mit numerischen Ziffern und höchstens einer Dezimalstelle. In HubSpot entspricht dieser Typ Zahlen- und berechneten Eigenschaften.
`string`	Eine Klartext-Zeichenfolge, die auf 65.536 Zeichen begrenzt ist. In HubSpot entspricht dieser Typ Eigenschaften Eigenschaften der Typen „Einzeiliger Text“ und „Mehrzeiliger Text“.

So zeigen Sie die verfügbaren Eigenschaften eines Events an:

Gehen Sie in Ihrem HubSpot-Account zu Datenmanagement > Benutzerdefinierte Events.
Klicken Sie in der Tabelle auf den Namen des Events.
Klicken Sie oben auf die Registerkarte Eigenschaften.
Zeigen Sie in der Eigenschaftentabelle den Eigenschaftstyp unter dem Namen der Eigenschaft an.

Attribution-Berichterstattung

JavaScript-Events wie Events vom Typ Angeklicktes Element und Aufgerufene URL werden automatisch mit Ressourcentyp- und Interaktionsdaten für Attribution-Berichte ausgefüllt. Um die gleichen Daten für manuell nachverfolgte Events zu berücksichtigen, müssen Sie die Daten manuell mithilfe von Event-Eigenschaften in den Anforderungstext aufnehmen. Erfahren Sie mehr über das Analysieren von benutzerdefinierten Events. Im Folgenden erfahren Sie mehr über die verfügbaren Werte für Ressourcentypen und Interaktionsquellen sowie Beispielanfragen.

Elementtyp

Um einen bestimmten Elementtyp einer benutzerdefinierten Event-Anfrage zuzuschreiben, fügen Sie die hs_page_content_type-Eigenschaft in den Anforderungstext ein. Zum Beispiel:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Sie können auch die hs_asset_type-Eigenschaft verwenden. Wenn sowohl hs_page_content_type als auch hs_asset_type in einer Anfrage enthalten sind, überschreibt hs_page_content_type den hs_asset_type-Wert.

Die Standardinhaltstypen von HubSpot, wie Landingpages und Blogbeiträge, können mit den folgenden Werten dargestellt werden:

Wert	Beschreibung
`STANDARD_PAGE`	Eine Interaktion mit einer Website-Seite.
`LANDING_PAGE`	Eine Interaktion mit einer Landingpage.
`BLOG_POST`	Eine Interaktion mit einem Blogbeitrag.
`KNOWLEDGE_ARTICLE`	Eine Interaktion mit einem Wissensdatenbankartikel.

Verwenden Sie für alle anderen Elementtypen die folgenden Werte:

Wert	Beschreibung
`AD`	Eine Interaktion mit einer Anzeige, z. B. einer Facebook- oder Google-Anzeige.
`CALL`	Eine Interaktion mit einem Anruf.
`CONTACT_IMPORT`	Eine Interaktion über einen Kontaktimport.
`CONVERSATION`	Eine Interaktion im Zusammenhang mit einer HubSpot-Konversation.
`CUSTOM_BEHAVIORAL_EVENT_NAME`	Der interne Name eines benutzerdefinierten Events, z. B. `pe123456_manually_tracked_event`.
`EMAIL`	Eine Interaktion mit einer E-Mail.
`EXTERNAL_PAGE`	Eine Interaktion mit einer externen Seite.
`INTEGRATIONS`	Eine Interaktion über eine Integration.
`MARKETING_EVENT`	Eine Interaktion mit einem Marketingevent.
`MEDIA_BRIDGE`	Eine Interaktion über die Media Bridge.
`MEETING`	Eine Interaktion mit einem Meeting.
`SALES_EMAIL`	Interaktion mit einer persönlichen Vertriebs-E-Mail.
`SEQUENCE`	Eine Interaktion mit einer Sequenz.
`SOCIAL_POST`	Eine Interaktion mit einem Social-Media-Beitrag.
`OTHER`	Eine Interaktion mit einem Inhaltselement, das nicht in eine der oben genannten Kategorien fällt.

Elementtitel

Um ein benutzerdefiniertes Event einem Element zuzuschreiben, schließen Sie die hs_page_title- oder hs_asset_title-Eigenschaft mit einem als Zeichenfolge formatierten Namen des Elements in Ihre Anfrage ein. Zum Beispiel: hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Interaktionsquellen

Um ein benutzerdefiniertes verhaltensorientiertes Event einer bestimmten Quelle zuzuschreiben, schließen Sie die hs_touchpoint_source-Eigenschaft in Ihre Anfrage mit einem der folgenden Werte ein:

Wert	Beschreibung
`CONVERSATION`	Die Interaktionsquelle ist eine Konversation.
`DIRECT_TRAFFIC`	Die Interaktionsquelle ist direkter Traffic.
`EMAIL_MARKETING`	Die Interaktionsquelle ist eine Marketing-E-Mail.
`HUBSPOT_CRM`	Die Interaktionsquelle ist das HubSpot-CRM.
`INTEGRATION`	Die Interaktionsquelle ist eine Integration.
`MARKETING_EVENT`	Die Interaktionsquelle ist ein Marketingevent.
`OFFLINE`	Die Interaktionsquelle ist offline.
`ORGANIC_SEARCH`	Die Interaktionsquelle ist die organische Suche.
`OTHER_CAMPAIGNS`	Die Interaktionsquelle ist von einer nicht kategorisierten Kampagne.
`PAID_SEARCH`	Die Interaktionsquelle ist eine bezahlte Suchanzeige.
`PAID_SOCIAL`	Die Interaktionsquelle ist eine bezahlte Social-Media-Anzeige.
`REFERRALS`	Die Interaktionsquelle ist eine Empfehlung.
`SALES`	Die Interaktionsquelle ist der Vertrieb.
`SOCIAL_MEDIA`	Die Interaktionsquelle ist Social Media (keine bezahlten Social-Media-Anzeigen).

Account & Einstellungen

App-Verwaltung

Authentifizierung

Automatisierung

CMS

Kommunikationseinstellungen

Konversationen

CRM

Veranstaltungen

Dateien

Marketing

Zeitplaner

Webhooks

Benutzerdefinierte Event-Abschlüsse senden

Das Event definieren

Event-Daten senden

Hinweis:

Event-Daten abrufen

Event-Eigenschaften

Attribution-Berichterstattung

Elementtyp

Elementtitel

Interaktionsquellen

​Das Event definieren

​Event-Daten senden

​Hinweis:

​Event-Daten abrufen

​Event-Eigenschaften

​Attribution-Berichterstattung

​Elementtyp

​Elementtitel

​Interaktionsquellen

Das Event definieren

Event-Daten senden

Hinweis:

Event-Daten abrufen

Event-Eigenschaften

Attribution-Berichterstattung

Elementtyp

Elementtitel

Interaktionsquellen