Dernière modification : 11 septembre 2025
L’utilisation de cette fonctionnalité nécessite une autorisation de HubSpot. Si vous souhaitez demander l’accès aux objets d’application ou si vous souhaitez en savoir plus sur les fonctionnalités, veuillez soumettre ce formulaire.
Découvrez ci-dessous des informations de référence pour les fonctionnalités d’application de la plateforme de développement avec des objets d’application, y compris des définitions de fichier de configuration, des détails de domaines, etc.

​
Structure du projet

  • Tous les composants du projet doivent se trouver dans le répertoire indiqué src dans le fichier de configuration hsproject.json.
  • Toutes les fonctionnalités et tous les composants de l’application doivent se trouver dans le répertoire app/.
  • Les associations d’objets d’application sont définies dans le répertoire app-object-associations/.
  • Les abonnements Webhook sont définis dans le répertoire webhooks/.
  • Les actions de workflow personnalisées sont définies dans le répertoire workflow-actions/.
  • Toutes les caractéristiques des cartes doivent se trouver dans le répertoire cards/.
  • Toutes les instances de composants et de fonctionnalités sont déclarées à l’aide de fichiers *-hsmeta.json. Vous devez faire précéder le nom du fichier d’un élément significatif (par exemple, my-app-hsmeta.json). Ces fichiers doivent se trouver à la racine de leur dossier respectif (par exemple, app/my-app-hsmeta.json, cards/my-card-hsmeta.json).
L’exemple de structure de répertoire ci-dessous décrit toutes les fonctionnalités disponibles. 
my-folder/
├── hsproject.json
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

Afficher un exemple sur GitHub

​
Objets de l’application

Pour créer un objet d’application, incluez un répertoire de composants app-objects dans le projet, ainsi qu’un fichier de configuration. 
...
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
└──
Voici les options de configuration disponibles pour *-object-hsmeta.json. 
{
  "uid": "car-app-object",
  "type": "app-object",
  "config": {
    "name": "CAR",
    "appPrefix": "Vroom",
    "description": "An automobile in our warehouse.",
    "singularForm": "Car",
    "pluralForm": "Cars",
    "primaryDisplayLabelPropertyName": "model",
    "secondaryDisplayLabelPropertyNames": ["make"],
    "settings": {
      "hasRecordPage": true,
      "allowsUserCreatedRecords": true,
      "hasEngagements": true
    },
    "properties": [
      {
        "type": "string",
        "fieldType": "text",
        "name": "model",
        "label": "Model",
        "description": "The model of the car"
      },
      {
        "type": "enumeration",
        "fieldType": "select",
        "name": "make",
        "label": "Make",
        "description": "The manufacturer of the car.",
        "options": [
          {
            "label": "Ford",
            "value": "ford",
            "displayOrder": 0
          },
          {
            "label": "Toyota",
            "value": "toyota",
            "displayOrder": 1
          },
          {
            "label": "Chevrolet",
            "value": "chevrolet",
            "displayOrder": 2
          }
        ]
      }
    ]
  }
}

Afficher un exemple sur GitHub

Les champs marqués par * sont requis.

ChampTypeDescription
uid*Chaîneun identifiant unique pour l’objet application. Doit être globalement unique au sein du projet.
type*Chaînele type de composant. Doit correspondre au nom du dossier parent (app-object).
name*Chaînele nom de l’objet de votre application. Utilisez le nom approuvé que vous avez reçu dans la confirmation de votre application approuvée. Doit être en majuscule snake case (MY_OBJECT_NAME).
appPrefixChaîneune chaîne qui précède le nom singulier ou pluriel de l’objet dans l’interface utilisateur de HubSpot pour aider à le différencier des autres objets. Dans cet exemple, les éléments appPrefix de Vroom et singularForm de Car entraînent l’affichage de « Voiture Vroom » dans l’interface utilisateur.
description*Chaînela description de l’objet, qui s’affichera dans HubSpot.
singularForm*Chaînela forme singulière du nom d’objet.
pluralForm*Chaînela forme plurielle du nom d’objet.
properties*Tableauune liste des propriétés CRM définies pour l’objet. Les propriétés sont définies en utilisant les mêmes champs que l’API des propriétés. Les propriétés résultantes auront automatiquement a<appId>_ ajouté à elles (par exemple, a12345_make) lors de la création. Vous ne devez pas inclure le préfixe dans le fichier de configuration.
primaryDisplayLabelPropertyName*Chaînele nom de la propriété qui doit être utilisée comme propriété d’affichage principale. La valeur doit correspondre au nom fourni dans la liste properties (autrement dit, elle ne doit pas inclure le préfixe généré a<appId>_).
secondaryDisplayLabelPropertyNames*Tableaula liste des propriétés qui doivent être utilisées comme propriétés d’affichage secondaires. La valeur doit correspondre au nom fourni dans la liste properties (autrement dit, elle ne doit pas inclure le préfixe généré a<appId>_).
settings*Objetun objet contenant des paramètres d’objet.
hasRecordPage*Booléenindique si des pages de fiches d’informations existent pour les instances de cet objet d’application. Si défini sur false, la page d’index existera toujours, mais elle ne comprendra pas de liens vers des pages de fiches d’informations individuelles.
allowsUserCreatedRecords*Booléensi les utilisateurs finaux pourront créer des fiches d’informations à l’aide de l’objet. Lorsque la valeur est définie sur false, les utilisateurs ne pourront pas créer de fiches d’informations dans HubSpot
hasEngagements*Booléensi les fiches d’informations d’objet d’application prennent en charge des activités/engagements. Lorsque définie sur false, les pages de fiches d’informations d’objet d’application n’incluront aucune fonctionnalité d’engagement, comme l’onglet d’activité ou les filtres de chronologie liés à l’activité.
Le nom entièrement qualifié (FQN) pour votre objet d’application sera a<appId>_<objectName>. Par exemple : si votre appId est 16858319 et que le nom d’objet de l’application est CARS, alors le FQN serait a16858319_CARS. Vous utiliserez le FQN lors de la définition des valeurs de domaine pour les vos objets d’application.

​
Schéma de l’application

Pour créer un objet d’application, incluez un fichier de configuration app-hsmeta.json dans le répertoire app. 
...
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
└──
Voici les options de configuration disponibles pour app-hsmeta.json. 
{
  "uid": "app_object_poc_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with an app object on developer projects.",
    "name": "my first app object app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Afficher un exemple sur GitHub

​
Schéma d’application *champs -hsmeta.json

Les champs marqués par * sont requis

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour l’application. Doit être globalement unique au sein du projet. Peut être n’importe quelle chaîne jusqu’à 64 caractères. Les caractères peuvent être en majuscules ou en minuscules, et peuvent inclure des chiffres, des tirets bas (_), des tirets (-) et des points (.).
type*Chaînele type de composant. Doit correspondre au nom du dossier parent (app).
description*Chaîneune description de ce que l’application fait pour l’utilisateur qui l’installe. Peut être n’importe quelle chaîne jusqu’à 8 192 caractères.
name*Chaînele nom de l’application, qui s’affichera dans HubSpot. Peut être n’importe quelle chaîne jusqu’à 200 caractères. Ne doit pas commencer ou se terminer par un espace.
distribution*Chaînela méthode de distribution de l’application. Doit être défini sur marketplace pour que l’application soit éligible au listing du marketplace des applications.
auth*Objetun objet contenant les détails de la méthode d’authentification de l’application. Voir le tableau des authentifications pour plus de détails.
permittedUrlsObjetun tableau contenant les URL que l’application est autorisée à appeler. Les URL doivent utiliser le schéma HTTPS et contenir une autorité, suivie d’un préfixe de chemin facultatif si nécessaire.
supportEmailChaîneune adresse e-mail valide que les utilisateurs peuvent contacter pour obtenir de l’aide.
documentationUrlChaînel’URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir de la documentation utile. Doit utiliser HTTPS.
supportUrlChaînel’URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir une assistance supplémentaire. Doit utiliser HTTPS.
supportPhoneChaînele numéro de téléphone que les utilisateurs peuvent contacter pour obtenir de l’aide. Doit commencer par un signe plus (+).

​
champs d’authentification

Les champs marqués par * sont requis.

ChampTypeDescription
type*Chaînele type d’authentification. Doit être défini sur oauth pour que l’application utilise l’authentification OAuth.
redirectUrls*Tableauune liste des URL vers lesquelles le processus OAuth est autorisé à rediriger. Chaque application doit avoir au moins une URL de redirection d’authentification et doit utiliser HTTPS. La seule exception est http://localhost, qui est autorisée pour les tests.
requiredScopes*Tableauune liste des domaines requis de votre application. Chaque application doit inclure au moins un domaine et l’utilisateur qui a procédé à l’installation doit accorder ces domaines pour installer l’application avec succès. Découvrez-en davantage sur les domaines ci-dessous.
optionalScopesTableauune liste des domaines facultatifs de votre application. Ces domaines peuvent être exclus de l’autorisation lors de l’installation si le compte ou l’utilisateur qui installe l’application ne dispose pas des autorisations appropriées. Dans ce cas, le domaine ne sera pas inclus dans le jeton d’actualisation ou le jeton d’accès qui en résulte. Découvrez-en davantage sur les domaines ci-dessous.
conditionallyRequiredScopesTableauune liste des domaines requis uniquement lorsqu’ils sont inclus dans le paramètre de requête scope de l’URL d’installation. Découvrez-en davantage sur les domaines ci-dessous.

​
Domaines

Dans le champ auth d’un fichier de configuration d’application, vous pouvez indiquer trois types de domaines : les domaines requis, les domaines conditionnellement requis et les domaines facultatifs. À ce stade de la version bêta, vous devez inclure uniquement les domaines d’objet de votre application en tant que conditionallyRequiredScopes. Cela vous permettra de réserver vos nouvelles fonctionnalités à des clients spécifiques en incluant les domaines d’objet d’application dans l’URL d’installation. Les domaines d’objet d’application utilisent le format suivant : crm.app.schemas.<appObjectFullyQualifiedName>.read Par exemple, pour un objet application avec le FQN a16858319_cars, le domaine d’application read serait : crm.app.schemas.a16858319_cars.read. Au minimum, votre application doit inclure le domaine ci-dessus read pour permettre aux clients d’accéder à l’objet. Il est recommandé d’inclure tous les domaines d’application dans votre application, comme indiqué ci-dessous. 
"auth": {
      "type" : "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write",
        "crm.app.objects.a12345_MY_APP_OBJECT.view",
        "crm.app.objects.a12345_MY_APP_OBJECT.create",
        "crm.app.objects.a12345_MY_APP_OBJECT.edit",
        "crm.app.schemas.a12345_MY_APP_OBJECT.read",
        "crm.app.objects.a12345_MY_APP_OBJECT.merge",
        "crm.app.objects.a12345_MY_APP_OBJECT.delete",
        "crm.app.schemas.a12345_MY_APP_OBJECT.properties.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
Pour obtenir une liste complète des domaines disponibles, consultez la référence des domaines.

​
Définition du composant Webhook

Pour définir un ensemble d’abonnements au webhook pour votre application, incluez un répertoire webhooks dans le projet ainsi qu’un fichier de configuration *-hsmeta.json. 
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
└──
Vous trouverez ci-dessous les options de configuration disponibles pour le fichier *-hsmeta.json. 
{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "car_app_object",
          "propertyName": "carProperty",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "contact.deletion",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

​
Webhook *champs -hsmeta.json

Les champs marqués par * sont requis.

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour le composant du webhook.
type*Chaînele type de composant, qui devrait être webhooks dans ce cas.
settings*Objetun objet qui spécifie deux champs : targetUrl, qui est l’URL publique que HubSpot peut appeler l’endroit où les charges utiles de l’événement seront livrées, et maxConcurrentRequests, qui est le seuil supérieur des demandes HTTP que HubSpot effectuera dans une période donnée.
subscriptions*Objetun objet qui spécifie les types d’abonnements auxquels votre application s’abonnera.
crmObjectsTableauun tableau contenant des définitions d’abonnement aux événements. Il s’agit du tableau standard à inclure, qui doit être utilisé pour tous les événements dans le nouveau format (object.*). Les types d’abonnement de webhook classiques doivent plutôt être inclus dans les tableaux legacyCrmObjects et hubEvents, en fonction de l’événement.
legacyCrmObjectsTableauun tableau contenant les types d’abonnements classiques, tels que contact.creation et deal.deletion.
hubEventsTableauun tableau contenant les types contact.privacyDeletion d’abonnements classiques et conversation.*
Pour chaque objet subscription, les champs suivants peuvent être indiqués, en fonction du type de définition d’abonnement auquel vous êtes abonné (c’est-à-dire crmObjects, legacyCrmObjects ou hubEvents) ou selon que vous êtes abonné à une modification de propriété spécifique (par exemple, contact.propertyChange).
ChampTypeDescription
subscriptionTypeChaînele type d’événement auquel l’abonné est abonné.
objectTypeChaînepour les abonnements indiqués dans le tableau crmObjects, cela indique l’objet CRM auquel votre application est abonnée. Pour vous abonner aux modifications apportées à un objet d’application, incluez le nom de votre objet d’application pour ce champ (par exemple, car_app_object).
propertyNameChaînepour les abonnements de modification de propriété, cela indique la propriété qui déclenchera l’événement webhook.
activeBooléensi des événements webhook seront déclenchés pour cet abonnement.

​
Schéma de carte d’application

Pour créer une carte d’application qui apparaît sur une page de fiches d’informations d’un objet d’application, incluez un répertoire de composant cards dans le projet, ainsi qu’un fichier de configuration. 
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──
  • Vérifiez que vous avez exécuté hs project upload après avoir créé votre composant d’objet d’application et les fichiers de configuration associés.
  • Dans votre fichier my-app-card-hsmeta.json, ajoutez l’UID de votre objet d’application au tableau objectTypes (par exemple, "app_object_uid" dans cet exemple). Chacun des champs disponibles dans le fichier .json est détaillé dans le tableau ci-dessous.
{
  "uid": "my-app-card",
  "type": "card",
  "config": {
    "name": "My app card",
    "description": "An example description of the card, which lives on contact records.",
    "previewImage": {
      "file": "./preview.png",
      "altText": "A short description of the preview image"
    },
    "entrypoint": "/app/cards/MyCard.jsx",
    "location": "crm.record.tab",
    "objectTypes": ["contacts", "app_object_uid"]
  }
}
  • Après avoir enregistré les modifications apportées à votre fichier example-card-hsmeta.json, exécutez hs project upload.
Les cartes sont ajoutées automatiquement à la vue par défaut pour les objets d’application. Si la carte ne s’affiche pas automatiquement, découvrez comment ajouter des cartes aux fiches d’informations CRM.

Afficher un exemple sur GitHub

​
App card *champs -hsmeta.json

Les champs marqués par * sont requis.

ChampTypeDescription
uid*Chaînel’identifiant unique de la carte. Il peut s’agir de n’importe quelle chaîne, mais doit identifier la carte de manière significative. HubSpot identifiera la carte par cet ID afin que vous puissiez modifier le titre de la carte sans supprimer les données historiques ou d’état, telles que la position sur la fiche d’informations CRM.
typeChaînele type de composant, qui devrait être card dans ce cas.
configObjetun objet contenant des détails de configuration.
name*Chaînele titre de la carte, tel qu’il apparaît dans l’interface utilisateur de HubSpot.
descriptionChaîneune description de la carte.
previewImageObjetun objet contenant les champs file et altText. Le champ file est le chemin relatif vers l’image d’aperçu. Les extensions de fichier valides sont png, jpeg, jpg ou gif. La taille maximale du fichier est de 5.0 Mo. Le champ altText est une courte description de l’image.
entrypoint*Chaînele chemin du fichier du code React front-end de la carte.
location*crm.record.tab | crm.record.sidebar | helpdesk.sidebarEmplacement de la carte dans l’interface utilisateur de HubSpot En savoir plus sur l’emplacement de l’extension.
objectTypes*Tableaules types de fiches d’informations CRM sur lesquels la carte apparaîtra.

​
Associations d’objets d’application

Pour activer les associations entre votre objet application et d’autres objets CRM, incluez un répertoire de composants app-object-associations dans le projet, ainsi qu’un fichier de configuration. 
├── src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
└──
Voici les options de configuration d’objet d’application disponibles (*-association-hsmeta.json). 
{
  "uid": "car_to_contact_association",
  "type": "app-object-association",
  "config": {
    "firstObjectType": "car-app-object",
    "secondObjectType": "CONTACT"
  }
}

​
Association *champs -association-hsmeta.json

Les champs marqués par * sont requis.

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour l’application. Doit être globalement unique au sein du projet.
type*Chaînele type de composant. Doit correspondre au nom du dossier parent (app-object-association).
config*Objetun objet contenant la configuration de l’association d’objets.
firstObjectType*Chaînele premier objet de l’association. Il peut s’agir d’un objet d’application ou d’un objet CRM HubSpot. Les objets d’application sont désignés par leur uid indiqué dans leur fichier source. Les objets standards sont désignés par leur fullyQualifiedName. L’association résultante sera bidirectionnelle, de sorte que l’ordre de ces valeurs de champ est arbitraire.
secondObjectType*Chaînele deuxième objet de l’association. Voir firstObjectType pour plus de détails.