Migrar una aplicación pública existente al marco de proyectos (BETA)

• Empezarás clonando el proyecto existente para que los archivos originales sirvan de copia de seguridad, y luego podrás revisar cada uno de los archivos de configuración asociados para asegurarte de que se ajustan al nuevo esquema del proyecto. Esto requerirá pequeñas actualizaciones de los nombres y la estructura de los archivos de configuración de tus componentes, así como de sus respectivas propiedades.
• A continuación, actualizarás tus archivos de configuración de nivel superior hsproject.json y app.json.
  • Luego, puedes seguir cada una de las secciones siguientes para actualizar la configuración de los componentes de tu aplicación para que se ajusten a la versión 2025.2 de la plataforma para desarrolladores, basándote en las características existentes que habías configurado (por ejemplo, una tarjeta de aplicación creada mediante extensiones de interfaz de usuario).
  • Ten en cuenta que a excepción del archivo hsproject.json, todos los demás archivos de configuración siguen un esquema de nombres predecible (*-hsmeta.json donde * se basa en el directorio o componente específico) y todos comparten las mismas propiedades de nivel superior:

{
  "uid": "example-unique-identifier",
  "type": "example-component",
  "config": {
    ...
  }
}

• Una vez que hayas actualizado todos los componentes de tu proyecto existente clonado, subirás tu nuevo proyecto a tu cuenta de desarrollador de HubSpot como parte del último paso de esta guía.

​

Clonar los archivos de configuración existentes de tu proyecto

• Asegúrate de que has instalado la última versión beta de la CLI de HubSpot ejecutando el comando npm i -g @hubspot/cli@next y conéctalo a tu cuenta mediante los comandos hs auth y hs accounts use.
• Ejecuta el siguiente comando en tu terminal para crear un proyecto con la plantilla de una aplicación con distribución private y autenticación static.

hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta

• Sigue las instrucciones para proporcionar un nombre y un directorio local en el que descargar la plantilla estándar.
• Cuando se te pida que selecciones una plantilla, selecciona Proyecto de inicio con aplicación privada utilizando un token de acceso.
• Abre el proyecto recién creado en tu editor preferido. A continuación, puedes comparar la estructura de directorios del proyecto y los archivos de esquema *-hsmeta.json asociados con tu proyecto existente para asegurarte de que las especificaciones coinciden cuando proceda. Ten en cuenta que la plantilla debe utilizarse como referencia, pero no editarse directamente, ya que se recomienda que realices cualquier edición en la versión clonada de tu proyecto, como se ha indicado anteriormente.

​

Actualizar la configuración de tu 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"
}

​

Revisar el esquema de nivel superior de tu aplicación

{
  "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 propiedad de nivel superior public se ha sustituido por distribution y debe establecerse en private. Ten en cuenta que la subpropiedad type del campo auth debe establecerse en static, lo que restringirá la instalación de tu aplicación a una sola cuenta. Más información sobre la distribución y autenticación de aplicaciones en la guía de configuración de aplicaciones.
• Los permisos de tu aplicación se especifican ahora como una subpropiedad del campo auth, y se dividen entre requiredScopes, conditionallyRequiredScopes y optionalScopes. Más información sobre cómo especificar cada uno de estos tipos de permiso en la guía de configuración de la aplicación.
• No necesitas definir la propiedad de nivel superior extensions de tu proyecto anterior, ya que la propiedad no está presente en el nuevo archivo app-hsmeta.json. Todas las extensiones de interfaz de usuario configuradas previamente (por ejemplo, las tarjetas de la página de registro de CRM) se gestionan utilizando el directorio cards/ de tu proyecto. Dentro de ese directorio, los detalles de configuración de la tarjeta se especifican en un archivo *-hsmeta.json, junto con el código del componente de tu tarjeta proporcionado en un archivo .jsx al que se hace referencia mediante la propiedad entrypoint del archivo *-hsmeta.json.
• Tampoco necesitas definir sobre la propiedad webhooks de nivel superior de tu proyecto anterior en el nuevo archivo app-hsmeta.json, ya que los webhooks se configuran y gestionan utilizando el directorio webhooks/ de tu proyecto. Más información en la sección migrar suscripciones webhook más abajo.

​

Actualizar la configuración individual de los componentes

​

Migrar tarjetas del CRM creadas con extensiones de IU

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

• El valor de la propiedad type se ha cambiado de "crm-card" a "card".
• La propiedad uid ha dejado de ser una subpropiedad del campo data y ahora se especifica en el nivel superior de tu configuración.
• La propiedad data se ha cambiado a config, que incluye las siguientes subpropiedades:
  • La propiedad title ha pasado a llamarse name.
  • Una nueva propiedad description te permite proporcionar más contexto en torno a la funcionalidad de tu tarjeta. La descripción aparecerá en la configuración del proyecto de tu aplicación.
  • La propiedad module ha sido renombrada a entrypoint y el valor debe ser ahora una cadena que represente la ruta a tu componente JSX, relativa a la raíz de tu proyecto (por ejemplo, "/app/cards/example-app-card.jsx").
  • La propiedad objectTypes se ha simplificado y ahora es una matriz de cadenas que representan los tipos de objetos en los que debe aparecer tu tarjeta (por ejemplo, ["CONTACT", "COMPANY"]).
  • La propiedad location no se modifica y puede establecerse como crm.record.tab, crm.record.sidebar o helpdesk.sidebar.

​

Migrar suscripciones de 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
        }
      ]
    }
  }
}

• En el nivel superior de tu archivo *-hsmeta.json debe definirse una propiedad obligatoria uid, a la que debe darse un nombre para diferenciarla de otras características de la aplicación (por ejemplo, "migrated_private_app_webhooks").
• También debe definirse una propiedad obligatoria type en el nivel superior de tu configuración *-hsmeta.json y debe establecerse como "webhooks".
• Las propiedades subscriptions y settings no se modifican respecto a webhooks.json, pero deben trasladarse a la propiedad config, definida en el nivel superior de tu archivo *-hsmeta.json.

​

Subir tu proyecto

hs project upload

​

Migrar el manejo de funciones sin servidor

• Localiza tus funciones sin servidor en el proyecto de tu aplicación privada existente en el directorio src/app/app.functions.
• Copia toda la lógica relevante de tus funciones. En el ejemplo de función sin servidor que aparece abajo, solo habría que copiar la línea 4.

exports.main = async (context = {}) => {
  const { text } = context.parameters;

  const response = `This is coming from a serverless function!  You entered: ${text}`;

  return response;
};

• En la plataforma de alojamiento de terceros, pega la lógica de tu definición de función sin servidor anterior, y asegúrate de que los nombres de los parámetros coinciden. Tendrás que consultar la documentación para definir la función sin servidor en la plataforma que estés utilizando.
• Copia tu token de acceso de la página de detalles del proyecto de tu aplicación y agrégalo como variable de entorno con tu plataforma de alojamiento de terceros para que pueda ser referenciado en tu código.
• A continuación, tendrás que actualizar la propiedad permittedUrls de tu archivo de esquema de nivel superior app-hsmeta.json para incluir el campo fetch. El valor de este campo debe establecerse en una matriz que incluya la URL de tu endpoint alojado en tu plataforma de alojamiento de terceros.
• A continuación, actualiza cualquier referencia en tu código React en tus tarjetas de aplicación para llamar a la nueva URL de la función sin servidor que has configurado. Puedes obtener más información sobre el uso hubspot.fetch() en esta guía.

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' }),
  }
);

​

Limpieza

• En tu cuenta de HubSpot, dirígete a Desarrollo.
• En la página Proyectos, haz clic en el nombre de tu antiguo proyecto.
• Haz clic en la pestaña Configuración.
• En Eliminar este proyecto, haz clic en Eliminar [nombre del proyecto].
• Revisa la información del cuadro de diálogo para confirmar que estás preparado para continuar. A continuación, introduce el nombre de tu proyecto y haz clic en Eliminar proyecto.

​

Próximos pasos

• Crear un componente de configuración
• Definir una acción de workflow personalizada
• Gestiona tu aplicación en HubSpot