Migrer une application privée existante vers le cadre de projet (BÊTA)

• 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 :

{
  "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 dans le cadre de la dernière étape de ce guide.

​

Cloner vos fichiers de configuration de projet existants

• 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.

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.

​

Mettre à jour la configuration de votre hsproject.json

{
  "name": "My old private app",
  "srcDir": "src",
  "platformVersion": "2025.1"
}

{
  "name": "My new migrated app (Developer platform v2025.2)",
  "srcDir": "src",
  "platformVersion": "2025.2"
}

​

Examiner le schéma de premier niveau de votre application

{
  "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"
  }
}

{
  "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"
    }
  }
}

• 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.
• 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.
• 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 ci-dessous.

​

Mettre à jour la configuration des composants individuels

​

Migrer des cartes CRM créées avec des extensions d’interface utilisateur

{
  "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"
      }
    ]
  }
}

{
  "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"
    ]
  }
}

• 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.

​

Migrer les abonnements au webhook

{
"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
        }
      ]
}

{
  "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
        }
      ]
    }
  }
}

• 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.

​

Charger votre projet

hs project upload

​

Gérer la migration des fonctions sans serveur

• 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.

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

const { response } = await runServerless({
  name: 'myFunc',
  parameters: { text: text },
});

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

• 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.

​

Étapes suivantes

• Créer un composant de paramètres
• Définir une action de workflow personnalisée
• Gérer votre application dans HubSpot