> ## 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. # Référence des objets d'application (BÊTA) > Informations de référence pour la création d'objets d'application, y compris les options de configuration pour les applications, les objets d'application, etc. 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](/docs/apps/developer-platform/add-features/app-objects/overview). 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. ```shell theme={null} 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 └── ``` ## 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. ```shell theme={null} ... ├──src │ ├── app/ │ │ └── app-hsmeta.json │ │ └── ... │ │ └── app-objects/ │ │ └── my-app-object-hsmeta.json └── ``` Voici les options de configuration disponibles pour `*-object-hsmeta.json`. ```json theme={null} { "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 } ] } ] } } ```

Les champs marqués par \* sont requis.

| Champ | Type | Description | | ------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | Chaîne | un identifiant unique pour l'objet application. Doit être globalement unique au sein du projet. | | `type`\* | Chaîne | le type de composant. Doit correspondre au nom du dossier parent (`app-object`). | | `name`\* | Chaîne | le 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`). | | `appPrefix` | Chaîne | une 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îne | la description de l'objet, qui s'affichera dans HubSpot. | | `singularForm`\* | Chaîne | la forme singulière du nom d'objet. | | `pluralForm`\* | Chaîne | la forme plurielle du nom d'objet. | | `properties`\* | Tableau | une 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](/docs/api-reference/crm-properties-v3/guide). Les propriétés résultantes auront automatiquement `a_` 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îne | le nom de la propriété qui doit être utilisée comme [propriété d'affichage principale](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=object%27s%20singular%20name.-,Primary%20display%20property,-%3A%20the%20property%20used). 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_`). | | `secondaryDisplayLabelPropertyNames`\* | Tableau | la liste des propriétés qui doivent être utilisées comme [propriétés d'affichage secondaires](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=Secondary%20properties%3A). 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_`). | | `settings`\* | Objet | un objet contenant des paramètres d'objet. | | `hasRecordPage`\* | Booléen | indique 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éen | si 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éen | si 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_`. 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`. ```shell theme={null} ... ├──src │ ├── app/ │ │ └── app-hsmeta.json/ └── ``` Voici les options de configuration disponibles pour `app-hsmeta.json`. Prenez note des modifications suivantes pour les fichiers de configuration des cartes d'application : * Ajout des champs de premier niveau `uid`, `type` et `config`. * Champ `extensions` supprimé. * Champ `distribution` ajouté. ```json theme={null} { "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" } } } ``` ### Schéma d'application \*champs -hsmeta.json

Les champs marqués par \* sont requis

| Champ | Type | Description | | --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | Chaîne | un 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îne | le type de composant. Doit correspondre au nom du dossier parent (`app`). | | `description`\* | Chaîne | une 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îne | le 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îne | la 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`\* | Objet | un objet contenant les détails de la méthode d'authentification de l'application. Voir le [tableau des authentifications](#auth-fields) pour plus de détails. | | `permittedUrls` | Objet | un tableau contenant les URL que l'application est autorisée à appeler. Les URL doivent utiliser le schéma HTTPS et contenir une [autorité](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#authority), suivie d'un préfixe de chemin facultatif si nécessaire. | | `supportEmail` | Chaîne | une adresse e-mail valide que les utilisateurs peuvent contacter pour obtenir de l'aide. | | `documentationUrl` | Chaîne | l'URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir de la documentation utile. Doit utiliser HTTPS. | | `supportUrl` | Chaîne | l'URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir une assistance supplémentaire. Doit utiliser HTTPS. | | `supportPhone` | Chaîne | le 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.

| Champ | Type | Description | | ----------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type`\* | Chaîne | le type d'authentification. Doit être défini sur `oauth` pour que l'application utilise l'authentification OAuth. | | `redirectUrls`\* | Tableau | une 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`\* | Tableau | une 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](#scopes). | | `optionalScopes` | Tableau | une 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](#scopes). | | `conditionallyRequiredScopes` | Tableau | une 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](#scopes). | ### Domaines Dans le champ `auth` d'un fichier de configuration d'application, vous pouvez indiquer trois [types de domaines](/docs/apps/legacy-apps/public-apps/overview#scope-types) : 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..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. ```json theme={null} "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](/docs/apps/legacy-apps/authentication/scopes). ## 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`. ```shell theme={null} ├──src │ ├── app/ │ │ └── app-hsmeta.json │ │ └── ... │ │ └── webhooks/ │ │ └── webhooks-hsmeta.json └── ``` Vous trouverez ci-dessous les options de configuration disponibles pour le fichier `*-hsmeta.json`. ```json theme={null} { "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.

| Champ | Type | Description | | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | Chaîne | un identifiant unique interne pour le composant du webhook. | | `type`\* | Chaîne | le type de composant, qui devrait être `webhooks` dans ce cas. | | `settings`\* | Objet | un 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`\* | Objet | un objet qui spécifie les types d'abonnements auxquels votre application s'abonnera. | | `crmObjects` | Tableau | un 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. | | `legacyCrmObjects` | Tableau | un tableau contenant les types d'abonnements classiques, tels que `contact.creation` et `deal.deletion`. | | `hubEvents` | Tableau | un 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`). | Champ | Type | Description | | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subscriptionType` | Chaîne | le type d'événement auquel l'abonné est abonné. | | `objectType` | Chaîne | pour 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`). | | `propertyName` | Chaîne | pour les abonnements de modification de propriété, cela indique la propriété qui déclenchera l'événement webhook. | | `active` | Booléen | si 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. ```shell theme={null} ├──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](#app-card-*-hsmeta.json-fields) ci-dessous. Prenez note des modifications suivantes pour les fichiers de configuration des cartes d'application : * Ajout des champs de premier niveau `uid`, `type` et `config`. * Le champ `module` a été renommé `entrypoint`. * Le champ `title` a été renommé `name`. * Le champ `objectTypes` a été simplifié pour accepter un tableau de chaînes. ```json theme={null} { "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](/docs/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card#view-the-card-in-hubspot). ### App card \*champs -hsmeta.json

Les champs marqués par \* sont requis.

| Champ | Type | Description | | -------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | Chaîne | l'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. | | `type` | Chaîne | le type de composant, qui devrait être `card` dans ce cas. | | `config` | Objet | un objet contenant des détails de configuration. | | `name`\* | Chaîne | le titre de la carte, tel qu'il apparaît dans l'interface utilisateur de HubSpot. | | `description` | Chaîne | une description de la carte. | | `previewImage` | Objet | un 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îne | le chemin du fichier du code React front-end de la carte. | | `location`\* | `crm.record.tab` \| `crm.record.sidebar` \| `helpdesk.sidebar` | Emplacement de la carte dans l'interface utilisateur de HubSpot En savoir plus sur [l'emplacement de l'extension](/docs/apps/developer-platform/add-features/ui-extensibility/app-cards/reference#extension-location). | | `objectTypes`\* | Tableau | les 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. ```shell theme={null} ├── 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`). ```json theme={null} { "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.

| Champ | Type | Description | | ------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | Chaîne | un identifiant unique interne pour l'application. Doit être globalement unique au sein du projet. | | `type`\* | Chaîne | le type de composant. Doit correspondre au nom du dossier parent (`app-object-association`). | | `config`\* | Objet | un objet contenant la configuration de l'association d'objets. | | `firstObjectType`\* | Chaîne | le 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îne | le deuxième objet de l'association. Voir `firstObjectType` pour plus de détails. |