Zum Hauptinhalt springen
Dernière modification : 8 octobre 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 comment créer une application de preuve de concept dans laquelle vous configurerez un objet d’application que vous pourrez tester et utiliser dans un compte de test de développeur.
1

Installer la dernière version de l'ILC HubSpot

Vous aurez besoin de la dernière version bêta de l’ILC HubSpot pour créer une application unifiée. Dans une fenêtre de terminal, exécutez la commande suivante :
npm install -g @hubspot/cli@next
L’ILC doit être une version 7.4.4-beta.0 ou ultérieure. Vous pouvez vérifier la version de l’ILC dont vous disposez en exécutant hs --version.
2

Authentifier votre compte de développeur

Vous devrez ensuite authentifier votre compte de développeur en exécutant la commande suivante :
hs auth
  • Suivez les instructions pour générer une clé d’accès personnelle dans votre compte, puis copiez-la et collez-la dans le terminal pour enregistrer votre configuration.
  • Pendant cette période bêta, il est recommandé de faire de ce compte votre compte par défaut dans l’ILC. Cela permettra d’éviter d’éventuelles erreurs d’accès pour le compte pour lequel vous avez participé à la bêta.
3

Créer un nouveau projet de boilerplate

Exécutez la commande ci-dessous dans votre terminal pour créer un nouveau projet et une nouvelle application du marketplace avec les fonctionnalités actuellement compatibles ou un schéma de référence d’objet d’application.
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

Configurez le projet nouvellement créé et chargez-le sur votre compte de développeur

L’infrastructure de projets déplace les fonctionnalités d’application qui étaient précédemment configurées dans l’interface utilisateur ou via l’API vers des fichiers de code source, généralement définis comme des fichiers de configuration <file-name>-hsmeta.json.Les fonctionnalités de l’application sont ensuite créées à l’aide d’une combinaison de sous-dossiers du répertoire /src/app principal et d’autres fichiers de configuration si nécessaire. Pour configurer votre projet :
  • Ajoutez une ou plusieurs URL de redirection valides au fichier app-hsmeta.json en fonction de la configuration de votre serveur OAuth local (ou hors production).

​
Remarque :

Pour commencer, vous pouvez utiliser l’exemple d’Node.js OAuth et l’exécuter localement. Elle est déjà configurée pour fonctionner avec https://localhost:3000/oauth-callback comme l’URL de redirection configurée dans le code d’exemple du boilerplate à partir de la commande hs project create que vous avez exécutée à l’étape précédente.
  • Modifiez la propriété uid de l’application dans le fichier app-hsmeta.json et les autres fichiers de configuration *-hsmeta.json de votre projet.
Les UID sont utilisés comme identifiant unique pour tous les composants et fonctionnalités de votre projet. Une fois qu’une fonctionnalité et un UID sont créés, la modification ou la modification de l’UID dans les déploiements ultérieurs obligera la plateforme à le reconnaître comme différent des fonctionnalités précédentes, ce qui n’est peut-être pas prévu.
  • Lorsque vous utilisez des objets d’application pour votre application unifiée, seules les définitions de propriété « Nom » autorisées seront autorisées en fonction de votre demande d’objet. Dans le cadre de cette version bêta privée, vous devriez avoir reçu séparément confirmation du « nom » approuvé de votre application, qui doit être utilisé dans la configuration *-object-hsmeta.json. À titre de référence, le nom entièrement qualifié (FQN) de votre objet d’application sera a<appId>_<name>. Par exemple, si votre appId est 16858319 et votre propriété name était CARS, alors votre FQN serait a16858319_cars.
  • Après avoir enregistré vos modifications, exécutez la commande CLI hs project upload pour charger votre projet sur la plateforme de développement HubSpot et déclencher automatiquement une nouvelle build.
  • Dans une fenêtre de navigateur, accédez à https://app.hubspot.com/developer_projects/<accountId> pour accéder à l’interface utilisateur des projets et vérifiez que l’application et le projet ont été correctement créés, créés et déployés.
5

Ajoutez l'ID client et le secret client de votre application à votre application

  • Après avoir téléchargé votre projet, vous devrez obtenir les détails d’authentification pour que votre application soit copiée dans votre configuration OAuth :
    • Cliquez sur Projets dans le menu de navigation Développement.
    • Cliquez sur le nom de votre nouveau projet.
    • Cliquez sur le UID de votre application, puis sur l’onglet Authentification.
    • Copiez l’ID du client et le Secret client de votre nouvelle application et collez-les aux emplacements correspondants dans la configuration de votre serveur OAuth local, puis redémarrez votre serveur OAuth.
6

Configurer la configuration du schéma d'objet d'application

Ensuite, vous allez configurer le schéma d’objet de votre application :
  • Ajoutez un nouvel objet d’application en créant un répertoire dans le répertoire /src/app et nommez-le app-objects. Le chemin résultant vers le nouveau répertoire devrait être /src/app/app-objects.
  • Créez un nouveau fichier de configuration pour représenter le schéma de votre objet, Vous devez utiliser le nom d’objet attribué à votre application pendant le processus d’aperçu comme préfixe pour le nom de fichier, suivi de -object-hsmeta.json. Par exemple, dans le modèle de projet de référence, le nom d’objet de l’application est « CAR », de sorte que le fichier de configuration résultant est nommé car-object-hsmeta.json.
  • Consultez le fichier de référence de définition du composant d’objet d’application et personnalisez les champs en fonction des valeurs correspondantes pour votre objet d’application.
    • Dans l’objet config de votre définition, le champ name doit correspondre au nom qui a été accordé à votre application lors du processus d’évaluation, formaté dans le format UPPER_SNAKE_CASE.
    • Notez qu’une fois que les propriétés et les champs ont été ajoutés au schéma d’objet d’application et chargés dans votre projet à l’étape suivante, ils ne peuvent pas être supprimés.

​
Remarque :

Pour plus de commodité pendant les tests, le même nom d’objet d’application peut être utilisé sur plusieurs applications pour prendre en charge votre cycle de vie de développement. Commencez par cette application de preuve de concept, puis, à mesure que des migrations deviennent disponibles, vous pourrez utiliser les mêmes noms et définitions de schéma dans vos applications de développement, de préparation et de production. Les UID de chacune de ces instances devront être uniques.
  • Lorsque vous avez terminé de modifier la définition du schéma d’objet de votre application et que vous êtes prêt à valider ces modifications, exécutez les commandes suivantes pour enregistrer vos modifications :
hs project upload
hs project deploy
  • Dans une fenêtre de navigateur, accédez à https://app.hubspot.com/developer_projects/<hubId> pour accéder à l’interface utilisateur des projets et vérifiez que l’application et le projet ont été correctement créés, créés et déployés.
7

Mettre à jour votre application

Maintenant que le schéma d’objet de votre application a été chargé, vous devez mettre à jour les domaines définis dans votre fichier app-hsmeta.json pour refléter les domaines créés à partir de l’étape précédente. Ces domaines devraient être visibles dans les journaux de l’ILC après l’exécution de hs project upload.
  • Modifiez le fichier app-hsmeta.json et ajoutez les nouveaux domaines au tableau de requiredScopes dans la définition auth. Par exemple, si votre appId était a12345, vous modifieriez la définition auth comme suit :
"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": []
},

​
Remarque :

  • Les clients ne pourront voir votre objet d’application que si schemas.read le domaine est inclus dans les paramètres de votre application et est demandé pendant la flux OAuth d’installation/réautorisation. Il est fortement recommandé d’inclure tous les domaines d’objet d’application dans vos paramètres, mais schemas.read est obligatoire pour clients pour y accéder. Par exemple, pour un appId de 12345, que vous incluriez crm.app.schemas.a12345_MY_APP_OBJECT.read comme domaine obligatoire.
  • En fonction de l’application testée (prototype, développement, préparation, production), vous devrez faire attention à l’endroit où vous ajoutez votre champ d’application définitions. Bien que le déploiement d’une application de production ne soit pas encore pris en charge pendant cette phase de la version bêta privée, il est généralement plus sûr d’inclure domaines lorsque conditionallyRequiredScopes vous êtes prêt pour la production. Découvrez-en davantage sur ces types de domaines dans l’application publique documentation
  • Lorsque vous avez terminé d’ajouter ces domaines et que vous avez enregistré vos modifications, exécutez les commandes suivantes pour valider vos modifications dans la plateforme :
hs project upload
hs project deploy
Une fois le déploiement terminé, votre application et l’objet application correspondant sont maintenant prêts à être testés avec un compte installé.
8

Créez un compte de test de développeur (facultatif) et installez votre application

Si vous n’avez pas encore de compte test, vous pouvez en créer un dans HubSpot :
  • Accédez à Comptes de test dans le menu de navigation Développement, puis cliquez sur Créer un compte de test de développeur. Suivez les instructions pour créer votre nouveau compte de test.
  • Dans le menu latéral de gauche, accédez à Projets, cliquez sur le nom de votre nouveau projet, puis sur UID de votre application dans la liste des composants.
  • Dans l’onglet Authentification, copiez le lien d’installation de votre application.
  • Utilisez ce lien pour installer l’application dans votre compte de test de développeur.
  • Ouvrez le compte test et accédez à la page Applications connectées, où vous devriez voir la liste de votre application installée.
  • Dans votre compte de test, accédez à CRM > Contacts, puis cliquez sur le menu déroulant Objet CRM et confirmez que votre objet d’application est disponible.
  • Vous pouvez ensuite confirmer que votre définition de schéma est conforme à votre fichier de configuration en créant une nouvelle fiche d’informations de votre objet d’application.
app-object-available-in-crm
9

Accès aux données par programmation à l'aide de l'API d'objets HubSpot

Maintenant que vous avez créé votre objet d’application et que vous l’avez testé dans un compte de test de développeur, vous pouvez utiliser le jeton d’accès OAuth associé au compte de test installé pour effectuer des demandes de mise à jour des données du compte directement via l’API d’objets.Lisez l’API des objets pour plus d’informations sur l’API, mais toutes les demandes spécifiques à votre objet d’application suivront les mêmes conventions que les autres objets standard dans HubSpot. Vous devrez utiliser objectTypeId ou fullyQualifiedName de l’objet de votre application comme paramètre de chemin d’accès objectType dans votre demande.Par exemple, le bloc de code suivant montre comment effectuer une demande cURL pour créer une nouvelle fiche d’informations de votre objet d’application :
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/<fullyQualifiedName> \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'
Vous pouvez trouver le objectTypeId pour votre objet d’application en accédant à la page index des fiches d’informations :
  • Accédez à CRM > Contacts dans le compte de test de développeur sur lequel vous avez installé votre application.
  • Cliquez sur le menu déroulant en haut de la page et sélectionnez l’objet de votre application.
  • objectTypeId apparaîtra dans l’URL située entre les parties /objects/<objectTypeId>/views.

​
Étapes suivantes

Consultez la documentation de référence pour connaître les prochaines étapes à suivre afin d’utiliser les objets d’application avec différentes fonctionnalités de plateforme de développement :
⌘I