Dernière modification : 11 septembre 2025
Pour envoyer des données d’événement d’application à HubSpot, vous devez d’abord créer un type d’événement à l’aide d’un projet de développeur. Le type d’événement est un schéma JSON qui définit la structure, les propriétés et les règles de validation des données d’occurrence d’événement que vous allez envoyer. Cela comprend le nom de l’événement, le libellé d’affichage, l’objet CRM cible et les propriétés de l’événement. Les types d’événements comprennent également des définitions des modèles d’affichage pour le rendu de la chronologie des fiches d’informations du CRM.
Les événements d’application décrits dans cette documentation sont destinés aux applications créées pour le marketplace des applications à l’aide de projets développeur. Pour créer des rapports sur les événements personnalisé pour d’autres types d’intégrations, vous pouvez utiliser des événements personnalisés à la place.

​
Conditions préalables

Pour inclure une définition de type d’événement d’application dans votre projet :
  • Vous devez utiliser la version 7.5.4 ou une version ultérieure de l’ILC de HubSpot. Vous pouvez vérifier quelle version de l’ILC vous avez en exécutant hs --version, et la mettre à jour en exécutant npm i -g @hubspot/cli@next.
  • Votre projet doit être déployé avant que vous puissiez le mettre à jour pour inclure un composant d’événement d’application.

​
Configurer vos fichiers de projet

Si vous avez déjà créé une application publique avec un événement de chronologie, découvrez comment la migrer vers la plateforme de développement.
1

Configuration de l'application et structure du projet

Pour créer une définition de type d’événement d’application dans votre projet, mettez à jour votre fichier hsmeta.json de configuration d’application pour inclure le domaine timeline dans le champ requiredScopes. Cette donnée est nécessaire pour que les données des événements de l’application apparaissent sur les chronologies des fiches d’informations du CRM. Les installateurs doivent accorder ce domaine pour que vos données d’événement soient correctement envoyées.
"requiredScopes": [
  "timeline"
],
Notez que vous devrez peut-être ajouter d’autres domaines, en fonction des fonctionnalités incluses dans votre application.
Ensuite, dans le répertoire app/ de votre projet, ajoutez un répertoire app-events. Dans app-events/, ajoutez un fichier de configuration JSON pour définir le type d’événement de l’application. Ce fichier peut porter n’importe quel nom, mais doit se terminer par *-hsmeta.json. Vous pouvez inclure jusqu’à 750 types d’événement par application, chacun ayant son propre fichier *-hsmeta.json.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

Configurer le schéma de type d'événement

Dans le fichier *-hsmeta.json de type d’événement, configurez le schéma de votre type d’événement. Ce schéma configurera les attributs du type d’événement tels que le nom, le modèle d’affichage de la chronologie des fiches d’informations du CRM et le type d’objet du CRM auquel associer les données d’événement.Si certains de ces champs peuvent être mis à jour après leur création, les champs name et objectType ne peuvent pas être modifiés une fois que le type d’événement est créé.Par exemple, le schéma de type d’événement suivant peut être utilisé pour suivre les événements de connexion des clients.
{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

Les champs marqués par sont * obligatoires.

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour le type d’événement.
type*Chaînele type de composant. Doit correspondre à app-event.
name*Chaînele libellé affiché dans HubSpot (50 caractères maximum). Cette valeur ne peut pas être mise à jour après la création.
objectType*Chaînele nom complet du type d’objet CRM auquel les occurrences d’événements peuvent être associées. Cette valeur ne peut pas être modifiée après la création. Peut être l’un des éléments suivants : COMPANY, CONTACT, CUSTOM_OBJECT, DEAL, TICKET, APP_OBJECT.
headerTemplateChaînele modèle de rendu de l’en-tête de la carte d’activité CRM chronologie. Peut contenir jusqu’à 1 000 caractères.
detailTemplateChaînele modèle de rendu pour le corps de la carte d’activité CRM chronologie. Peut contenir jusqu’à 10 000 caractères.
propertiesTableaupropriétés définies pour le type d’événement dans lequel vous stockerez les données d’occurrence d’événement. Chaque type d’événement peut avoir jusqu’à 500 propriétés. Découvrez-en davantage sur les propriétés, y compris les exigences et les limitations, dans la documentation de référence sur les événements d’application.
3

Charger vos modifications sur HubSpot

Chargez votre projet sur HubSpot à l’aide de la commande hs project upload.
hs project upload
Pendant la phase de création, HubSpot validera le type d’événement. En cas d’erreurs de validation de schéma, l’ILC renverra une erreur indiquant ce qu’il faut corriger.Par défaut, après une création réussie, HubSpot déploiera automatiquement le projet. Si vous avez désactivé cette option dans les paramètres de votre projet, vous pouvez effectuer un déploiement manuel en utilisant hs project deploy.Après le déploiement, le type d’événement de votre application sera désormais disponible et pourra être utilisé pour recevoir des données d’occurrence d’événement.

​
Récupérez l’élément fullyQualifiedName

Pour envoyer des données d’occurrence d’événement pour le type d’événement, vous devrez récupérer le fullyQualifiedName via l’API d’événements de l’application. Ce nom identifie le type d’événement et devra être inclus dans toutes les opérations d’API d’événement d’application. Pour récupérer l’élément eventTypeName, adressez une demande POST à https://api.hubapi.com/integrators/timeline/v4/types/projects. Dans le corps de la demande, incluez :
  • Un champ projectName, qui doit être défini sur la valeur name du fichier hsproject.json de votre projet.
  • Un champ developerSymbol, qui doit être défini sur la valeur uid du fichier de configuration *-hsmeta.json du type d’événement.
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
La réponse renverra le nom du projet, le nom du type d’événement et le fullyQualifiedName. 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
La valeur fullyQualifiedName ne changera jamais, vous pouvez donc la coder en toute sécurité dans votre onboarding. L’API limite le nombre de fois où vous pouvez récupérer cette valeur par jour et ne peut pas être utilisée par programme.

​
Gestion des types d’événements

Pour mettre à jour un type d’événement après sa création, il vous suffira de mettre à jour le schéma de type d’événement dans votre projet, puis de le recharger pour créer et déployer l’application. Si vous ne souhaitez plus utiliser un type d’événement, vous pouvez le supprimer de votre projet. Toutefois, avant de supprimer un type d’événement, tenez compte des éléments suivants :
  • La suppression d’un type d’événement est une action permanente et irréversible.
  • La suppression d’un type d’événement supprime à la fois le type d’événement et toutes les occurrences de ce type de tous les comptes qui ont installé l’application.
  • La suppression d’un type d’événement va mettre en casse les autres outils HubSpot qui s’appuient sur ce type d’événement, tels que les rapports et les workflows. Pour supprimer le type d’événement, supprimez le fichier de configuration du type d’événement *-hsmeta.json de votre projet, puis chargez et déployez le projet.

​
Migrer un type d’événement de chronologie existant

Si vous avez une application publique existante avec un événement de chronologie, vous pouvez la migrer vers la plateforme de développement en utilisant l’ILC.
Avant de migrer votre application :
  • Consultez le guide de migration d’application publique pour connaître les considérations et les limites actuelles de la version bêta de la plateforme de développement.
  • Une fois que vous avez migré un type d’événement de chronologie (v1/v3) vers la plateforme de développeur, vous aurez 7 jours pour modifier les demandes d’API d’événements de chronologie v1/v3 existants vers les nouveaux points de terminaison v4, y compris les demandes d’API d’occurrence/d’instance d’événement de type d’événement. Après 7 jours, tous les appels existants vers les points de terminaison d’occurrence d’événement v1/v3 renverront des erreurs 401.
Pour migrer votre application :
  • Dans le terminal, exécutez hs app migrate, puis suivez les invites du terminal pour migrer votre application et votre événement de chronologie.
  • Une fois le processus de migration terminé, votre application sera hébergée dans un projet développeur et un répertoire de projet local sera créé pour vous.
  • Pour ouvrir le projet dans HubSpot, accédez au répertoire du projet local, puis exécutez hs project open.
Notez que les fichiers de configuration générés (*-hsmeta.json) peuvent contenir des champs avec des valeurs null. Ces champs sont un artefact de la migration et il peut être supprimé en toute sécurité.

​
Étapes suivantes

Après avoir créé un type d’événement, découvrez comment envoyer des données d’occurrence d’événement via l’API. Vous pouvez également consulter la documentation de référence sur les événements d’application pour continuer à créer et à personnaliser vos événements d’application.