Référence des événements d'application (BÊTA)

Vous trouverez ci-dessous des informations de référence relatives à l’utilisation des événements d’application, notamment les schémas de type d’événement, les modèles de rendu de chronologie d’événement, les champs d’occurrence d’événement, etc.

Structure du projet

Dans le contexte d’un projet, vous placerez les définitions des types d’événements dans un répertoire app-events sous app/. Le répertoire app-events doit contenir un fichier de définition de schéma JSON pour chaque type d’événement (*-hsmeta.json).

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json

Pour inclure des définitions de types d’événement dans un projet, procédez comme suit :

Votre application doit utiliser l’authentification OAuth et être configurée pour la distribution sur le marketplace des applications. En outre, l’application doit inclure timeline dans son requiredScopes. Découvrez-en davantage sur la configuration de l’application.
Votre projet doit être correctement déployé avant de pouvoir inclure un composant d’événement d’application.

Schéma de type d’événement

Voici les options de configuration disponibles pour les schémas de type d’événement (*-hsmeta.json). Notez que certains des attributs ci-dessous ne peuvent pas être modifiés après la création du type d’événement.

Chaque application est limitée à 750 types d’événements.

{
  "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 requis.

Champ	Type	Description
`uid`*	Chaîne	un identifiant unique interne pour le type d’événement.
`type`*	Chaîne	le type de composant. Doit correspondre à `app-event`.
`name`*	Chaîne	le libellé affiché dans HubSpot (50 caractères maximum). Cette valeur ne peut pas être mise à jour après la création.
`objectType`*	Chaîne	le 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`.
`headerTemplate`	Chaîne	le modèle de rendu de l’en-tête de la carte d’activité CRM chronologie. Peut contenir jusqu’à 1 000 caractères.
`detailTemplate`	Chaîne	le modèle de rendu pour le corps de la carte d’activité CRM chronologie. Peut contenir jusqu’à 10 000 caractères.
`properties`	Tableau	proprié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 d’événement ci-dessous.

Propriétés d’événement

Lors de la définition du schéma d’événement, utilisez le tableau properties pour définir les champs vers lesquels vous enverrez les données d’occurrence d’événement. Chaque type d’événement peut avoir jusqu’à 500 propriétés.

 "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 requis.

Champ	Type	Description
`name`*	Chaîne	le nom interne de la propriété. Doit être en minuscules et comporter entre 1 et 500 caractères. Les noms de propriété doivent être uniques par type d’événement. Cette valeur ne peut pas correspondre à la regex `"[A-Za-z0-9_\\-.]+"` ou commencer par `hs_`.
`label`*	Chaîne	le libellé affiché dans HubSpot. Doit être en minuscules et comporter entre 1 et 500 caractères.
`type`*	Chaîne	le type de données capturées dans la propriété. Peut être l’un des éléments suivants `STRING`, `NUMBER`, `DATE`, `ENUMERATION`.
`options`	Tableau	pour les propriétés de type `ENUMERATION`, ce champ fournit les options disponibles. Doit contenir au moins une option. Chaque option est un objet qui contient : `name` : le libellé de l’option affichée dans HubSpot. `value` : la valeur interne fournie par l’occurrence de l’événement. Le `name` et le `label` doivent être uniques dans le type d’événement.
`objectPropertyName`	Chaîne	le cas échéant, le nom de la propriété d’objet CRM qui doit être mise à jour lorsque des données d’événement sont envoyées à HubSpot. La valeur de cette propriété remplacera toutes les valeurs existantes dans cette propriété. Découvrez-en davantage sur l’horodatage des propriétés des fiches d’informations CRM ci-dessous.

Horodatage de propriété

Dans certains cas, vous souhaiterez peut-être modifier les valeurs des propriétés de la fiche d’informations CRM en fonction des données d’occurrence d’événement de l’application. Par exemple, vous pouvez vouloir mettre à jour le prénom et le nom de famille d’un contact avec de nouvelles valeurs définies par l’occurrence (par exemple, soumission de formulaire). Pour mettre à jour les propriétés des fiches d’informations CRM via des occurrences d’événement, vous pouvez lier une propriété d’événement à une propriété CRM dans le schéma de type d’événement. Dans les champs de définition d’une propriété d’événement donnée, incluez le champ objectPropertyName et précisez la propriété CRM à associer. Une fois qu’une propriété est liée, HubSpot mettra toujours à jour la valeur de la propriété sur la fiche d’informations CRM en utilisant la valeur de l’occurence la plus récente en fonction du champ timestamp. Par exemple, le schéma de type d’événement ci-dessous associe la propriété d’événement customerName à une propriété de contact personnalisée nommée custom_property_name. Lorsque les données d’occurrence d’événement incluent une valeur pour customerName, custom_property_name sera mise à jour pour la fiche d’informations CRM associée.

 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

Modèles de rendu

Les schémas de type d’événement peuvent inclure les champs headerTemplate et detailTemplate pour configurer le rendu des occurrences d’événement sur les chronologies des fiches d’informations CRM.

headerTemplate : une description d’une ligne de l’événement en haut de la carte d’activité (jusqu’à 1 000 caractères).
detailTemplate : les détails de l’événement dans le corps de la carte d’activité (jusqu’à 10 000 caractères).

Les modèles de rendu sont écrits à l’aide de Markdown avec les modèles Handlebars. Ces modèles peuvent restituer les données d’occurrence d’événement comme suit :

Dans les deux modèles, vous pouvez accéder à toutes données de property transmises par l’occurrence d’événement à l’aide de la syntaxe {{propertyName}}.
Dans le detailTemplate, vous pouvez également accéder aux valeurs extraData transmises par l’occurrence d’événement à l’aide de la syntaxe {{extraData.fieldName}}. Vous pouvez accéder à n’importe quel niveau d’attribut en notation par points extraData, tel que {{extraData.person1.preferredName}}.

L’objet extraData peut seulement contenir un JSON valide. Si le JSON est erroné, l’occurrence sera rejetée et vous recevrez une réponse d’erreur.

Par exemple, les modèles ci-dessous utilisent les données de propriété customerName et loginLocation, ainsi que le champ surveyData de extraData envoyé via l’occurrence d’événement. Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact.

Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact.

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

Les modèles étant conçus avec Markdown et Handlebars, vous pouvez tirer parti des aides de Handlebars pour rendre le contenu plus dynamique. Par exemple, l’élément suivant detailTemplate inclut l’assistant #if pour effectuer une restitution conditionnelle du contenu selon que les données d’occurrence d’événement incluent ou non le champ surveyData dans extraData.

Si extraData contient surveyData, afficher les réponses à l’enquête après connexion.
En l’absence de surveyData lors de l’occurrence de l’événement, afficher No additional information..

Capture d'écran montrant l'affichage de l'exemple de code ci-dessous sur la chronologie d'un contact.

"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

Utilisation d’iframes

Lorsque les données d’occurrence d’événement contiennent le champ timelineIFrame, la carte d’activité de la chronologie inclura un lien hypertexte sur lequel les utilisateurs pourront cliquer pour ouvrir le contenu lié dans un iframe. Capture d'écran d'un lien inclus dans une carte d'activité de chronologie en raison du champ timelineIFrame

Capture d'écran d'un lien inclus dans une carte d'activité de chronologie en raison du champ timelineIFrame

"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }

Champ	Type	Description
`linkLabel`	Chaîne	le texte du lien hypertexte qui lancera l’iframe au clic.
`headerLabel`	Chaîne	le libellé de la fenêtre modale qui affiche le contenu iFrame.
`url`	Chaîne	l’URL du contenu de l’iframe.
`width`	Entier	la largeur de la fenêtre modale de l’iframe.
`height`	Entier	la hauteur de la fenêtre modale de l’iframe.

Occurrence de l’événement

Pour envoyer des occurrences d’événements pour un type d’événement donné, effectuez une requête POST aux points de terminaison ci-dessous. L’API d’événements d’application comprend des points de terminaison pour l’envoi d’occurrences d’événements uniques et de lots d’occurrences de plusieurs événements. Pour les deux points de terminaison, les données d’occurrence d’événement devront être validées par rapport à un schéma de type d’événement existant, que vous indiquerez eventTypeName dans le corps de la requête.

Envoyer une occurrence unique
Envoyer un lot d'occurrences

Pour envoyer une occurrence d’événement unique, effectuez une requête POST à /integrators/timeline/v4/events.Dans le corps de la requête, incluez les données d’occurrence d’événement, en respectant le schéma défini du type d’événement.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Pour envoyer un lot d’occurrences d’événements, effectuez une demande POST à /integrators/timeline/v4/events/batch.Dans le corps de la requête, incluez jusqu’à 500 objets d’occurrence d’événement séparés par des virgules dans un tableau inputs. Si certaines occurrences ne sont pas validées, les occurrences validées avec succès seront toujours acceptées et persistées.

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

Dans le corps de la requête, incluez les données basées sur le schéma de type d’événement défini. Le corps de la requête doit inclure l’événement eventTypeName, que vous pouvez récupérer via l’API.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

Les champs marqués par * sont requis.

Champ	Type	Description
`eventTypeName`*	Chaîne	le nom entièrement qualifié du type d’événement, que vous utiliserez pour identifier l’événement via l’API. Cette valeur est automatiquement définie par HubSpot et peut être obtenue via l’API après la création du type d’événement. Cette valeur ne peut pas être modifiée après la création.
`objectId`*	Chaîne	l’ID de la fiche d’informations de CRM à associer à l’événement. Ce champ peut être utilisé pour tous les types de fiches d’informations de CRM et constitue l’identifiant recommandé. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`email`	Chaîne	pour l’association de contact, vous pouvez fournir l’adresse e-mail du contact à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`utk`	Chaîne	pour l’association de contacts, vous pouvez fournir le jeton utilisateur d’un contact existant à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`domain`	Chaîne	pour l’association d’entreprise, vous pouvez fournir le domaine de site web d’une entreprise existante. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`timestamp`	Chaîne	définit l’heure de l’occurrence de l’événement (format ISO 8601). Si ce champ n’est pas renseigné, HubSpot utilisera par défaut l’horodatage de l’envoi des données d’occurrence d’événement.
`properties`	Objet	paires clé-valeur des noms et valeurs des propriétés que vous avez définies pour le type d’événement.
`extraData`	Tableau	lorsqu’il est inclus, fournit des informations supplémentaires pour le rendu de la chronologie. Doit être un JSON valide. Découvrez-en davantage sur les données supplémentaires dans le rendu des modèles.
`timelineIFrame`	Objet	une fois incluse, la carte de chronologie comprendra un lien hypertexte qui permet aux utilisateurs d’ouvrir le contenu lié dans un iframe. Découvrez-en davantage sur l’utilisation des iframes.
`id`	Chaîne	un identifiant unique pour l’occurrence de l’événement. Doit être unique dans le type d’événement. Si ce champ n’est pas renseigné, HubSpot générera un GUID aléatoire. Lorsque plusieurs événements ont le même ID, le premier sera accepté et tous les autres seront rejetés.

Si certaines occurrences ne sont pas validées, les occurrences validées avec succès seront toujours acceptées et persistées. Le message d’erreur dans la réponse fournira des informations sur ce que vous devrez corriger. Capture d'écran d'un exemple de message d'erreur que vous pouvez recevoir lors de l'envoi de données d'occurrence d'événement

Capture d'écran d'un exemple de message d'erreur que vous pouvez recevoir lors de l'envoi de données d'occurrence d'événement

Association des fiches d’informations CRM

Chaque événement doit être associé à une fiche d’informations CRM, le type d’objet CRM étant défini par le schéma de type d’événement. L’API des événements de l’application comprend plusieurs champs pour associer les données d’occurrence d’événement aux fiches d’informations CRM. Pour tous les objets CRM pris en charge, il est recommandé d’utiliser le champ objectId. Cependant, dans certaines situations, vous souhaiterez peut-être utiliser les autres champs.

utk/email : si vous ne connaissez pas l’ID du contact, utilisez le champ utk et/ou email pour l’identification. Fournir ces deux identifiants vous permet également de créer et de mettre à jour des contacts. Par exemple :
- Si utk correspond à un contact existant mais que l’email ne correspond pas, HubSpot mettra à jour le contact avec la nouvelle adresse e-mail.
- Si aucun objectId n’est fourni, l’occurrence de l’événement sera associée à un contact existant correspondant à utk/email, ou HubSpot créera un nouveau contact si aucune correspondance n’est trouvée.
- Notez que le utk seul ne peut pas créer de nouveaux contacts. Vous devez toujours inclure l’email avec utk pour garantir une bonne association.
domain : pour l’association d’entreprises, vous devez fournir l’objectId, mais vous pouvez également l’inclure le domain pour mettre à jour la propriété de domain de cette entreprise.

Créer des applications

Ajouter des fonctionnalités

Publier dans la Marketplace HubSpot

Référence des événements d'application (BÊTA)

Structure du projet

Schéma de type d’événement

Propriétés d’événement

Horodatage de propriété

Modèles de rendu

Utilisation d’iframes

Occurrence de l’événement

Association des fiches d’informations CRM

​Structure du projet

​Schéma de type d’événement

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

​Horodatage de propriété

​Modèles de rendu

​Utilisation d’iframes

​Occurrence de l’événement

​Association des fiches d’informations CRM

Structure du projet

Schéma de type d’événement

Propriétés d’événement

Horodatage de propriété

Modèles de rendu

Utilisation d’iframes

Occurrence de l’événement

Association des fiches d’informations CRM