Définir des événements personnalisés

Exigences de portée

Les événements personnalisés vous permettent de définir et de suivre des événements propres à votre entreprise, tels que des événements sur votre site ou dans une application. Vous pouvez configurer des événements pour stocker des informations au sein des propriétés, que vous pouvez ensuite utiliser dans l’ensemble des outils de HubSpot. Pour envoyer des données d’événement personnalisé à HubSpot, vous devez d’abord configurer l’événement. Ceci est similaire aux objets CRM personnalisés, pour lesquels vous devez d’abord définir l’objet personnalisé avant de pouvoir créer des fiches d’informations individuelles pour cet objet. La définition d’un événement comprend des détails tels que ses métadonnées, ses associations d’objets CRM et ses propriétés. Vous trouverez ci-dessous des informations sur la création et la gestion de définitions d’événements à l’aide de l’API. Pour découvrir comment créer des définitions d’événements sans utiliser l’API, consultez la base de connaissances de HubSpot.

Créer une définition d’événement

Pour créer le schéma d’événement personnalisé, effectuez une requête POST à events/v3/event-definitions. Dans le corps de la requête, incluez les définitions de votre schéma d’événement, y compris son libellé, son nom, ses associations d’objets CRM et ses propriétés personnalisées. Le corps de la requête ci-dessous fournit un exemple basique de définition d’événement :

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

Si vous souhaitez lier automatiquement les finalisations d’événements aux fiches d’informations d’un type d’objet CRM spécifique, vous pouvez inclure un customMatchingId dans votre requête POST. Dans ce champ, définissez un objet primaryObjectRule avec deux champs : la propriété d’objet unique que vous avez préalablement configurée comme targetObjectPropertyName, et l’une des propriétés que vous avez définies dans les propertyDefinitions de votre définition d’événement. Par exemple, le corps de la requête suivante spécifie une customMatchingId qui correspond à un nom de propriété d’objet CRM de "unique_object_property" et à un nom de propriété d’événement de "string_property" :

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

Une liste complète des paramètres disponibles pour le corps de la requête est détaillée dans le tableau ci-dessous :

Paramètre	Type	Description
`label`	Chaîne	Le libellé compréhensible de l’événement, qui s’affichera dans HubSpot (jusqu’à 100 caractères). Les longs libellés peuvent être coupés dans certaines parties de l’interface utilisateur de HubSpot.
`name`	Chaîne	Le nom interne unique de l’événement, que vous utiliserez pour référencer l’événement via l’API. Si aucune valeur n’est fournie, HubSpot en générera automatiquement une basée sur le libellé. Cette propriété ne peut pas être modifiée après la création de la définition d’événement. Cette propriété ne peut contenir que des lettres minuscules, des chiffres, des tirets bas et des traits d’union (jusqu’à 50 caractères). Le premier caractère doit être une lettre.
`description`	Chaîne	La description de l’événement, qui s’affichera dans HubSpot.
`primaryObject`	Chaîne	Le type d’objet CRM auquel les données d’événement seront associées. Les événements terminés apparaîtront sur les enregistrements CRM de ce type d’objet. Peut être l’un des suivants : `"CONTACT"` (par défaut), `"COMPANY"`, `"DEAL"`, `"TICKET"`, `"<CUSTOM_OBJECT_NAME>"`. Ce type d’objet ne peut pas être modifié après la création de la définition de l’événement.
`propertyDefinitions`	Tableau	En plus des propriétés d’événement par défaut de HubSpot, vous pouvez inclure ce tableau pour définir événement personnalisé propriétés (jusqu’à 50). Pour chaque objet de propriété, incluez les champs suivants : `name` : le nom interne de la propriété, que vous utiliserez lors de l’envoi de données d’événement via l’API. `label` : le libellé dans l’application de la propriété. `type` : le type de la propriété. La valeur par défaut est `string`. `options` : pour les propriétés de type `enumeration`, ce tableau définit les valeurs disponibles. Doit inclure à la fois un `label` et une `value` pour chaque option. `description` : texte décrivant la propriété.
`customMatchingId`	Objet	Au lieu d’inclure le `objectId` de l’objet cible dans les données de finalisation d’événement, ce champ facultatif définit une règle pour lier automatiquement les achèvements d’événement aux fiches d’informations du type d’objet CRM spécifié. Pour ce faire, faites correspondre la valeur d’une propriété dans les données d’événement avec la valeur d’une propriété unique sur l’objet cible. Cet objet doit inclure un objet `primaryObjectRule` imbriqué, qui à son tour doit inclure deux champs : `targetObjectPropertyName` : une chaîne qui spécifie le nom de la propriété unique sur l’objet CRM cible à utiliser pour la correspondance. `eventPropertyName` : une chaîne qui spécifie le nom de la propriété dans les données de l’événement personnalisé à utiliser pour la correspondance.
`includeDefaultProperties`	Booléen	Champ facultatif qui indique si l’événement doit inclure l’ensemble des propriétés d’événement par défaut. Si aucune valeur n’est fournie, ce champ sera automatiquement défini sur `true`.

Propriétés d’événement

Les propriétés des événements personnalisés sont utilisées pour stocker des informations sur l’achèvement de chaque événement personnalisé. Ces propriétés doivent être utilisées le cas échéant pour l’envoi d’achèvements d’événements, mais elles ne sont pas nécessaires pour qu’un achèvement d’événement soit valide. Pour chaque définition d’événement, HubSpot fournit un ensemble de 32 propriétés par défaut. En outre, vous pouvez créer jusqu’à 50 propriétés personnalisées par définition d’événement. Les propriétés peuvent être des types suivants :

bool : une propriété qui reçoit une valeur booléenne. Les valeurs doivent être représentées par true ou false.
date : une propriété qui reçoit une date représentant un jour, un mois et une année spécifiques. Les valeurs doivent être représentées au format UTC et peuvent être formatées sous forme de chaînes ISO 8601 ou d’horodatages EPOCH en millisecondes (c.-à-d. minuit UTC).
datetime : une propriété avec des valeurs epoch (en millisecondes) ou ISO8601 représentant un horodatage.
enumeration : une propriété avec des options prédéfinies. Lors de la création de ce type de propriété, incluez un tableau options pour définir les valeurs disponibles.
number : une propriété qui reçoit des valeurs numériques avec un maximum d’une décimale.
string : une propriété qui reçoit des chaînes de texte en clair. Si le nom de la propriété contient les mots url, referrer ou link, la valeur de la propriété peut comporter jusqu’à 1 024 caractères. Autrement, les valeurs des propriétés peuvent comporter jusqu’à 256 caractères.

Ci-dessous, vous découvrirez les propriétés des événements par défaut de HubSpot, comment définir de nouvelles propriétés pour les événements existants et comment mettre à jour les propriétés des événements personnalisés existants.

Propriétés d’événement par défaut de 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

Définir de nouvelles propriétés

Pour définir une nouvelle propriété sur un événement personnalisé existant, effectuez une requête POST à events/v3/event-definitions/{eventName}/property. Dans le corps de la requête, incluez la définition de votre propriété.

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

Lorsque vous donnez un nom à votre propriété, gardez à l’esprit les éléments suivants :

Une fois que vous avez créé une propriété, son nom ne peut plus être modifié.
Le nom ne peut contenir que des lettres minuscules, des chiffres, des tirets bas et des tirets.
Le premier caractère du nom de la propriété doit être une lettre.
Le nom de la propriété et le libellé peuvent comporter chacun jusqu’à 50 caractères.
Si aucun nom de propriété n’est fourni, un nom sera généré automatiquement en utilisant le libellé de la propriété.
Les longs libellés peuvent être coupés dans certaines parties de l’interface utilisateur de HubSpot.

Mise à jour des propriétés personnalisées existantes

Pour mettre à jour une propriété existante sur un événement personnalisé, effectuez une requête PATCH à events/v3/event-definitions/{eventName}/property. Les seuls champs qui peuvent être mis à jour sur une propriété sont les champs label, description, et options pour les propriétés d’énumération.

Remarque :

Pour modifier le type de propriété, utilisez le point de terminaison DELETE pour supprimer la propriété et la recréer avec le bon type.

Supprimer une propriété

Pour supprimer une propriété existante sur un événement personnalisé, effectuez une requête DELETE à events/v3/event-definitions/{eventName}/property/{propertyName}. Lorsqu’une propriété est supprimée, elle ne pourra plus être utilisée dans le cadre d’événements futurs. Les achèvements antérieurs conservent leurs valeurs de propriété.

Mise à jour d’un événement

Pour mettre à jour un schéma d’événement personnalisé existant, effectuez une requête PATCH à events/v3/event-definitions/{eventName}. Les seuls champs de définition d’événement qui peuvent être mis à jour sont label et description.

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

Supprimer un événement

Pour supprimer un événement personnalisé, effectuez une requête DELETE à events/v3/event-definitions/{eventName}. La suppression d’un événement personnalisé entraînera sa suppression de tous les autres outils HubSpot qui le référencent, tels que les workflows et les rapports.

Remarque : Lors de la suppression d’un événement :

Tous les événements correspondant à cette définition d’événement seront supprimés et irrécupérables.
Les éléments eventName précédemment supprimés ne peuvent pas être réutilisés. Soyez donc prudent lors de la suppression d’un événement.

Obtenir des définitions d’événements existants

Pour récupérer une seule définition d’événement, effectuez une requête GET à events/v3/event-definitions/{eventName}. Pour rechercher des définitions d’événements selon des critères spécifiques, effectuez une requête GET à events/v3/event-definitions. Vous pouvez fournir les paramètres de requête suivants pour affiner votre recherche :

searchString : recherche les événements qui contiennent les caractères spécifiés dans le champ name. La recherche n’est pas floue, mais il s’agit plutôt d’une recherche naïve de type contains.
after : une chaîne de caractères hachée fournie dans les réponses paginées pour afficher la page suivante des résultats de la recherche.
limit : le nombre maximum de résultats à renvoyer.
includeProperties : une valeur booléenne qui spécifie si les propriétés de l’événement doivent être incluses dans les résultats renvoyés.

Account & Settings

Gestion des applications

Authentification

Automatisation

CMS

Préférences de communication

Conversations

CRM

Événements

Fichiers

Marketing

Planificateur

Webhooks

Définir des événements personnalisés

Créer une définition d’événement

Propriétés d’événement

Propriétés d’événement par défaut de HubSpot

Définir de nouvelles propriétés

Mise à jour des propriétés personnalisées existantes

Remarque :

Supprimer une propriété

Mise à jour d’un événement

Supprimer un événement

Remarque : Lors de la suppression d’un événement :

Obtenir des définitions d’événements existants

​Créer une définition d’événement

​Propriétés d’événement

​Propriétés d’événement par défaut de HubSpot

​Définir de nouvelles propriétés

​Mise à jour des propriétés personnalisées existantes

​Remarque :

​Supprimer une propriété

​Mise à jour d’un événement

​Supprimer un événement

​Remarque : Lors de la suppression d’un événement :

​Obtenir des définitions d’événements existants

Créer une définition d’événement

Propriétés d’événement

Propriétés d’événement par défaut de HubSpot

Définir de nouvelles propriétés

Mise à jour des propriétés personnalisées existantes

Remarque :

Supprimer une propriété

Mise à jour d’un événement

Supprimer un événement

Remarque : Lors de la suppression d’un événement :

Obtenir des définitions d’événements existants