> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt > Use this file to discover all available pages before exploring further. # Définir des événements personnalisés > Découvrez-en davantage sur la création d'événements personnalisés à l'aide de l'API de HubSpot. export const ScopesList = ({scopes = [], description = "Cette API requiert l'une des portées suivantes :"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; 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é](/api-reference/events-send-event-completions-v3/guide) à 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](https://knowledge.hubspot.com/fr/reports/create-custom-events). ## 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 : ```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 } ``` 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"` : ```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" } } } ``` 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é. | | `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"`, `""`. 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](#hubspot-s-default-event-properties), 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é](#event-properties). 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](#hubspot-s-default-event-properties). 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](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties) 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](#define-new-properties) et comment [mettre à jour les propriétés des événements personnalisés existants](#update-existing-custom-properties). ### 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é. ```json theme={null} { "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`. ```json theme={null} { "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 : 1. Tous les événements correspondant à cette définition d'événement seront supprimés et irrécupérables. 2. 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.