> ## 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. # Migrer une application privée existante vers le cadre de projet (BÊTA) > Découvrez comment migrer une application privée existante vers le cadre de projets (BÊTA). Si vous avez déjà créé une [application privée sur la version précédente](/docs/guides/crm/understanding-the-crm) du cadre de développement, vous pouvez migrer manuellement la configuration de votre application vers le nouveau cadre (`2025.2`). Ce guide vous explique les points suivants : * Vous commencerez par cloner votre projet existant afin que les fichiers d'origine puissent servir de sauvegarde, puis vous pourrez examiner chacun des fichiers de configuration associés pour vous assurer qu'ils sont conformes au nouveau schéma de projet. Cela nécessitera des mises à jour mineures des noms et de la structure de vos fichiers de configuration de composants, ainsi que de leurs propriétés respectives. * Vous mettrez ensuite à jour vos fichiers de configuration existants `hsproject.json` et `app.json` de premier niveau. * Vous pouvez ensuite suivre chacune des sections suivantes pour mettre à jour la configuration des composants de votre application afin qu'elle soit conforme à la version `2025.2` de la plateforme de développement, en fonction des fonctionnalités existantes que vous aviez configurées (par exemple, une carte d'application créée à l'aide d'extensions d'interface utilisateur). * Notez qu'à l'exception du fichier `hsproject.json`, tous les autres fichiers de configuration suivent un schéma de dénomination prévisible (`*-hsmeta.json` où `*` est basé sur le répertoire ou le composant spécifique) et partagent tous les mêmes propriétés de premier niveau : ```json theme={null} { "uid": "example-unique-identifier", "type": "example-component", "config": { ... } } ``` * Après avoir mis à jour tous les composants de votre projet existant cloné, vous chargerez votre nouveau projet sur votre [compte de développeur HubSpot](/docs/getting-started/account-types#developer-accounts) dans le cadre de la dernière étape de ce guide. Gardez les limitations suivantes à l'esprit avant de migrer votre application privée : * Les commandes de migration de l'ILC HubSpot ne sont pas prises en charge pour les applications privées existantes, car la migration automatique n'est pas prise en charge actuellement. * La prise en charge de [l'intégration GitHub](/docs/developer-tooling/third-party-tools/set-up-github-actions), qui déclenche des chargements et des builds automatiques à partir de GitHub, n'est pas encore disponible. Si votre projet existant est actuellement lié à GitHub, veillez à désactiver l'intégration avant de commencer la migration. Pour désactiver l'intégration GitHub et configurer les actions GitHub pour l'automatisation CI/CD, consultez les instructions de [cet article](/docs/developer-tooling/third-party-tools/set-up-github-actions). ## Cloner vos fichiers de configuration de projet existants Avant d'effectuer toute mise à jour, clonez votre projet existant afin de disposer d'une sauvegarde à laquelle vous pouvez vous référer ou revenir en cas de problème. Après avoir cloné votre projet, ouvrez-le dans l'IDE de votre choix, comme VSCode. Si vous recherchez un projet minimal conforme aux nouveaux schémas `2025.2` que vous pouvez consulter, vous pouvez télécharger un modèle de boilerplate : * Assurez-vous que vous avez installé la dernière version bêta de l'ILC HubSpot en exécutant la commande `npm i -g @hubspot/cli@next` et en la connectant à votre compte à l'aide des commandes `hs auth` et `hs accounts use`. * Exécutez la commande ci-dessous dans votre terminal pour créer un projet avec le modèle de boilerplate pour une application avec distribution `private` et authentification `static`. ```shell theme={null} hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta ``` * Suivez les requêtes pour fournir un nom et un répertoire local dans lequel télécharger le modèle de boilerplate. * Lorsque vous êtes invité à sélectionner un modèle, sélectionnez **Premiers pas avec une application privée utilisant un jeton d'accès**. * Ouvrez le projet que vous venez de créer dans votre éditeur préféré. Vous pouvez ensuite comparer la structure du répertoire du projet et les fichiers de schéma associés `*-hsmeta.json` à votre projet existant pour vous assurer que les spécifications correspondent, le cas échéant. Notez que le modèle doit être utilisé comme référence, mais pas modifié directement, car il est recommandé d'apporter des modifications à la version clonée de votre projet comme indiqué ci-dessus. Une référence complète de la nouvelle structure de projet pour la version `2025.2` de la plateforme de développement est détaillée dans le guide de [configuration de l'application](/docs/apps/developer-platform/build-apps/app-configuration#project-structure). ## Mettre à jour la configuration de votre hsproject.json Les modifications apportées au `hsproject.json` de premier niveau impliquent des modifications mineures des propriétés `name` et `platformVersion`, comme indiqué dans les blocs de code ci-dessous : **Avant :** ```json theme={null} { "name": "My old private app", "srcDir": "src", "platformVersion": "2025.1" } ``` **Après :** ```json theme={null} { "name": "My new migrated app (Developer platform v2025.2)", "srcDir": "src", "platformVersion": "2025.2" } ``` Le fichier `hsproject.json` de premier niveau de votre projet se trouve au même emplacement sur la nouvelle plateforme de développement, mais vous devrez mettre à jour le `platformVersion` vers la version `"2025.2"`. Vous pouvez également mettre à jour le champ `name` avec un nom unique afin qu'il ne remplace pas votre projet existant lorsque vous le chargez. Par exemple, si le nom de votre application privée existante a été nommé `My private app`, vous pouvez ajouter un élément `(Developer Platform v2025.2)` ou quelque chose de similaire pour le distinguer de l'ancienne application. ## Examiner le schéma de premier niveau de votre application Les blocs de code ci-dessous fournissent des exemples de configuration avant et après les modifications requises : **Avant (`src/app/app.json`) :** ```json theme={null} { "name": "My old private app", "description": "This is an example of private app on the old developer platform.", "scopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "uid": "my-old-private-app", "public": false, "extensions": { "crm": { "cards": [ { "file": "extensions/example-card.json" } ] } }, "webhooks": { "files": "./webhooks/webhooks.json" } } ``` **Après (`src/app/app-hsmeta.json`) :** ```json theme={null} { "uid": "new_developer_platform_app", "type": "app", "config": { "description": "Example of migrated app on the new developer platform.", "name": "My new migrated app (Developer platform v2025.2)", "distribution": "private", "auth": { "type": "static", "redirectUrls": ["http://localhost:3000/oauth-callback"], "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "optionalScopes": [], "conditionallyRequiredScopes": [] }, "permittedUrls": { "fetch": ["https://api.example.com"], "iframe": [], "img": [] }, "support": { "supportEmail": "support@example.com", "documentationUrl": "https://example.com/docs", "supportUrl": "https://example.com/support", "supportPhone": "+18005555555" } } } ``` Sur l'ancienne version de la plateforme de développement, la configuration de votre application privée a été spécifiée dans votre fichier `app.json`. Ces détails de configuration pour votre application sont désormais spécifiés avec le fichier de schéma de votre application dans le fichier `/src/app/app-hsmeta.json`. Les principales modifications entre votre ancienne configuration `app.json` et la nouvelle configuration `app-hsmeta.json` sont les suivantes : * La propriété de premier niveau `public` a été remplacée par `distribution` et doit être définie sur `private`. Notez que la sous-propriété `type` du champ `auth` doit être définie sur `static`, ce qui limitera l'installation de votre application à un seul compte. Pour en savoir plus sur la distribution et l'authentification des applications, consultez le guide de [configuration de l'application](/docs/apps/developer-platform/build-apps/app-configuration#distribution). * Les domaines de votre application sont désormais spécifiés en tant que sous-propriété du champ `auth` et sont réparties entre `requiredScopes`, `conditionallyRequiredScopes` et `optionalScopes`. Découvrez-en davantage sur la spécification de chacun de ces types de domaine dans le guide de [configuration de l'application](/docs/apps/developer-platform/build-apps/app-configuration#scopes). * Vous n'avez pas besoin de définir la propriété de premier niveau `extensions` de votre projet précédent, car la propriété n'est pas présente dans le nouveau fichier `app-hsmeta.json`. Toutes les extensions d'interface utilisateur précédemment configurées (par exemple, les cartes sur la page des fiches d'informations du CRM) sont gérées à l'aide du répertoire `cards/` de votre projet. Dans ce répertoire, les détails de configuration de la carte sont spécifiés dans un fichier `*-hsmeta.json`, ainsi que le code du composant de votre carte fourni dans un fichier `.jsx` référencé à l'aide de la propriété `entrypoint` du fichier `*-hsmeta.json`. * Vous n'avez pas non plus besoin de définir la propriété de premier niveau `webhooks` de votre projet précédent dans le nouveau fichier `app-hsmeta.json`, car les webhooks sont configurés et gérés à l'aide du répertoire `webhooks/` de votre projet. Découvrez-en davantage dans la [section Migrer les abonnements webhook](#migrate-webhook-subscriptions) ci-dessous. ## Mettre à jour la configuration des composants individuels Les sections ci-dessous expliquent comment porter les extensions d'interface utilisateur et les webhooks vers votre nouvelle application. Si votre ancienne application n'avait aucun de ces composants, vous pouvez accéder à la section [Charger votre projet](#upload-your-project). ### Migrer des cartes CRM créées avec des extensions d'interface utilisateur Les blocs de code ci-dessous fournissent des exemples de configuration avant et après les modifications requises : **Avant (`src/app/extensions/card.json`) :** ```json theme={null} { "type": "crm-card", "data": { "title": "example app card", "uid": "example_app_card_private_static", "location": "crm.record.tab", "module": { "file": "example-app-card.jsx" }, "objectTypes": [ { "name": "contacts" } ] } } ``` **Après (`src/app/cards/example-app-card-hsmeta.json`) :** ```json theme={null} { "uid": "example_app_card_private_static", "type": "card", "config": { "name": "example app card", "description": "Provides detailed information about a contact or company.", "previewImage": { "file": "./full-preview.png", "altText": "This describes the image" }, "entrypoint": "/app/cards/example-app-card.jsx", "location": "crm.record.tab", "objectTypes": ["CONTACT"] } } ``` Les cartes CRM sont désormais configurées dans le répertoire `cards/` de votre projet, remplaçant l'ancien répertoire `extensions/` de votre ancien projet. Dans le nouveau répertoire `cards/`, les détails de configuration de la carte sont spécifiés dans un fichier `*-hsmeta.json`, ainsi que le code du composant de votre carte fourni dans un fichier `.jsx` référencé à l'aide de la propriété `entrypoint` du fichier `*-hsmeta.json`. Pour transférer le code d'extension d'interface utilisateur de votre application héritée, copiez toutes les valeurs pertinentes de votre fichier `app.json` hérité dans les propriétés associées dans le fichier `*-hsmeta.json` du répertoire `cards/`, en gardant à l'esprit les modifications suivantes : * La valeur de la propriété `type` a été modifiée de `"crm-card"` à `"card"`. * La propriété `uid` a été déplacée d'une sous-propriété du champ `data` et est désormais spécifiée au premier niveau de votre configuration. * La propriété `data` a été remplacée par `config`, qui comprend les sous-propriétés suivantes : * La propriété `title` a été renommée `name`. * Une nouvelle propriété `description` vous permet de fournir plus de contexte sur la fonctionnalité de votre carte. La description apparaîtra dans les paramètres du projet de votre application. * La propriété `module` a été renommée `entrypoint` et la valeur doit maintenant être une chaîne qui représente le chemin d'accès à votre composant JSX, par rapport à la racine de votre projet (par exemple, `"/app/cards/example-app-card.jsx"`). * La propriété `objectTypes` a été simplifiée et se présente désormais sous la forme d'un tableau de chaînes représentant les types d'objets où votre carte doit apparaître (par exemple, `["CONTACT", "COMPANY"]`). * La propriété `location` reste inchangée et peut être définie sur `crm.record.tab`, `crm.record.sidebar`, ou `helpdesk.sidebar`. Si vous avez [téléchargé](#clone-your-existing-project-configuration-files) le modèle de projet de boilerplate, un exemple de fichier de configuration `example-app-card-hsmeta.json` et un composant JSX `example-app-card.jsx` sont fournis dans le répertoire `src/app/cards`. Pour un guide complet sur la création de cartes d'application sur la nouvelle plateforme de développement, consultez [cet article](/docs/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card). ### Migrer les abonnements au webhook Les blocs de code ci-dessous fournissent des exemples de configuration avant et après les modifications requises : **Avant (`src/app/webhooks/webhooks.json`) :** ```json theme={null} { "settings": { "targetUrl": "https://example.com/webhook", "maxConcurrentRequests": 10 }, "subscriptions": { "crmObjects": [ { "subscriptionType": "object.creation", "objectType": "contact", "active": true } ], "legacyCrmObjects": [ { "subscriptionType": "contact.propertyChange", "propertyName": "lastname", "active": true } ], "hubEvents": [ { "subscriptionType": "contact.privacyDeletion", "active": true } ] } ``` **Après (`src/app/webhooks/webhooks-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 } ], "legacyCrmObjects": [ { "subscriptionType": "contact.propertyChange", "propertyName": "lastname", "active": true } ], "hubEvents": [ { "subscriptionType": "contact.privacyDeletion", "active": true } ] } } } ``` Les abonnements webhook sont toujours gérés dans un répertoire `webhooks/` de votre projet. Dans le répertoire, les détails de l'abonnement sont spécifiés dans un fichier `*-hsmeta.json`. La structure du fichier est en grande partie similaire au schéma `webhooks.json` précédent dans votre application privée, avec les changements notables suivants : * Une propriété `uid` obligatoire doit être définie au niveau supérieur de votre fichier `*-hsmeta.json`, dans lequel un nom doit être défini pour le différencier des autres fonctionnalités de l'application (par exemple, `"migrated_private_app_webhooks"`). * Une propriété `type` requise doit également être définie au niveau supérieur de votre configuration `*-hsmeta.json` et doit être définie sur `"webhooks"`. * Les propriétés `subscriptions` et `settings` restent inchangées par rapport à `webhooks.json`, mais doivent être déplacées dans la propriété `config` définie au premier niveau de votre fichier `*-hsmeta.json`. Pour obtenir des références complètes sur la définition des abonnements webhook sur la nouvelle plateforme de développement, consultez [cet article](/docs/apps/developer-platform/add-features/configure-webhooks). ## Charger votre projet Après avoir migré la configuration de votre application privée existante vers les sous-répertoires respectifs de votre projet, vous pouvez charger votre nouvelle application sur votre compte HubSpot. À partir de là, vous pouvez trouver le jeton d'accès de votre application que vous pouvez utiliser pour authentifier les requêtes d'API et continuer à développer les fonctionnalités sur la nouvelle plateforme de développement. ### Remarque : Si des fonctions sans serveur sont définies pour votre application privée existante :
  1. Faites une sauvegarde de `src/app/app.functions` depuis votre ancien projet, avec toutes les références associées à vos fonctions sans serveur ailleurs dans votre projet.
  2. Les fonctions sans serveur ne doivent pas être incluses dans le répertoire du projet que vous chargez dans le cadre de votre nouvelle application. Une fois votre projet chargé, vous pouvez suivre les étapes de la [section ci-dessous](#migrate-serverless-function-handling) pour reproduire le même comportement de la nouvelle plateforme de développement.
Pour charger votre nouveau projet, exécutez la commande CLI suivante : ```shell theme={null} hs project upload ``` ## Gérer la migration des fonctions sans serveur Si votre application privée incluait des fonctions sans serveur, vous devrez créer votre propre service backend REST et utiliser l'API `hubspot.fetch()` pour récupérer les données. Cela vous obligera à migrer toute logique de service existante précédemment définie dans vos fonctions sans serveur hébergées par HubSpot, ainsi que votre jeton d'accès d'application privée vers une plateforme d'hébergement tierce, telle que Vercel, DigitalOcean, AWS, etc. Pour migrer votre logique de fonction sans serveur vers une plateforme d'hébergement tierce : * Recherchez vos fonctions sans serveur dans le projet de votre application privée existante dans le répertoire `src/app/app.functions`. * Copiez toute la logique pertinente de vos fonctions. Dans l'exemple de fonction sans serveur ci-dessous, seule la ligne 4 devrait être copiée. ```js theme={null} exports.main = async (context = {}) => { const { text } = context.parameters; const response = `This is coming from a serverless function! You entered: ${text}`; return response; }; ``` * Dans la plateforme d'hébergement tierce, collez la logique de votre précédente définition de fonction sans serveur et assurez-vous que les noms des paramètres correspondent. Vous devrez consulter la documentation pour définir la fonction sans serveur sur la plateforme que vous utilisez. * Copiez votre jeton d'accès depuis la [page des détails du projet](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication-for-your-app) de votre application et ajoutez-le en tant que variable d'environnement avec votre plateforme d'hébergement tierce afin qu'il puisse être référencé dans votre code. * Ensuite, vous devez mettre à jour la propriété `permittedUrls` de votre [fichier de schéma](#review-your-app-s-top-level-schema) `app-hsmeta.json` de premier niveau pour inclure le champ `fetch`. La valeur de ce champ doit être définie sur un tableau qui inclut l'URL de votre point de terminaison hébergé sur votre plateforme d'hébergement tierce. * Ensuite, mettez à jour toutes les références dans votre code React dans vos cartes d'application pour appeler la nouvelle URL de fonction sans serveur que vous avez configurée. Vous pouvez en apprendre davantage sur l'utilisation de `hubspot.fetch()` dans [ce guide](/docs/apps/developer-platform/add-features/ui-extensibility/fetching-data). Par exemple, si le code React de votre application privée a déjà appelé la fonction sans serveur comme ceci : ```js theme={null} const { response } = await runServerless({ name: "myFunc", parameters: { text: text }, }); ``` Ensuite, vous devrez mettre à jour le code dans votre nouveau projet comme suit : ```js theme={null} const response = await hubspot.fetch("https://my-new-serverless-function.example.app/api/example-function.js", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: "hello" }), }); ``` ## Nettoyer Une fois que vous avez chargé avec succès votre nouveau projet, migré toutes les manipulations de fonctions sans serveur (le cas échéant) et testé entièrement votre application pour confirmer la cohérence du comportement, vous pouvez supprimer votre ancien projet dans votre compte développeur HubSpot. N'oubliez pas que vous disposez toujours localement de la sauvegarde d'origine de votre projet, comme indiqué dans la [première étape](#clone-your-existing-project-configuration-files) de ce guide, au cas où vous en auriez besoin comme référence. Pour supprimer votre ancien projet de votre compte développeur : * Dans votre compte HubSpot, naviguez vers **Développent**. * Sur la page **Projets**, cliquez sur le **nom** de votre ancien projet. * Cliquez sur l'onglet **Settings**. * Sous *Supprimer ce projet*, cliquez sur **Supprimer \[nom du projet]**. * Passez en revue les informations affichées dans la boîte de dialogue pour confirmer que tout est prêt. Puis, saisissez le nom de votre projet et cliquez sur **Supprimer le projet**. Confirmer la suppression de l'ancien projet ## Étapes suivantes Maintenant que vous avez effectué manuellement la migration des composants et de la configuration de votre ancienne application privée, vous pouvez continuer à créer des fonctionnalités sur la nouvelle plateforme de développement en consultant ces guides de suivi : * [Créer un composant de paramètres](/docs/apps/developer-platform/add-features/ui-extensibility/create-a-settings-component) * [Définir une action de workflow personnalisée](/docs/apps/developer-platform/add-features/custom-workflow-actions) * [Gérer votre application dans HubSpot](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot)