Migrar um aplicativo privado existente para o framework de projetos (BETA)

• Você começará clonando o projeto existente para que os arquivos originais possam servir como backup e, em seguida, poderá revisar cada um dos arquivos de configuração associados para garantir que estejam em conformidade com o novo esquema do projeto. Isso exigirá pequenas atualizações nos nomes e na estrutura dos arquivos de configuração do componente, bem como em suas respectivas propriedades.
• Em seguida, você atualizará os arquivos de configuração existentes hsproject.json e app.json de nível superior.
  • Em seguida, você pode seguir cada uma das seções subsequentes para atualizar a configuração de seus componentes de aplicativo para que estejam em conformidade com a versão 2025.2 da plataforma para desenvolvedores, com base nos recursos existentes que você configurou (por exemplo, um cartão de aplicativo criado com extensões de interface).
  • Observe que, com exceção do hsproject.json, todos os outros arquivos de configuração seguem um esquema de nomenclatura previsível (*-hsmeta.json, em que * é baseado no diretório ou componente específico) e todos compartilham as mesmas propriedades de nível superior:

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

• Depois de atualizar todos os componentes do seu projeto existente clonado, você carregará o novo projeto na sua Conta de desenvolvedor da HubSpot como parte da última etapa deste guia.

​

Clonar os arquivos de configuração de projeto existentes

• Verifique se você instalou a versão beta mais recente da CLI do HubSpot executando o comando npm i -g @hubspot/cli@next e se o conectou à sua conta usando os comandos hs auth e hs accounts use.
• Execute o comando abaixo no terminal para criar um projeto com o modelo básico para um aplicativo com distribuição private e autenticação static.

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

• Siga as instruções para fornecer um nome e um diretório local para baixar o modelo básico.
• Quando solicitado a selecionar um modelo, selecione Iniciar projeto com aplicativo privado usando um token de acesso.
• Abra o projeto recém-criado no editor de sua preferência. Você pode, então, comparar a estrutura de diretórios do projeto e os arquivos de esquema *-hsmeta.json associados ao projeto existente para garantir que as especificações correspondam quando aplicável. Observe que o modelo deve ser usado como referência, mas não editado diretamente, pois é recomendado fazer edições na versão clonada do seu projeto, conforme descrito acima.

​

Atualizar sua configuração 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"
}

​

Analisar o esquema de nível superior do seu aplicativo

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

• A propriedade public de nível superior foi substituída por distribution e deve ser definida como private. Observe que a subpropriedade type do campo auth deve ser definida como static, o que restringirá a instalação do seu aplicativo a uma única conta. Saiba mais sobre distribuição e autenticação de aplicativos no guia de configuração do aplicativo.
• Os escopos do seu aplicativo agora estão especificados como uma subpropriedade do campo auth e são divididos entre requiredScopes, conditionallyRequiredScopes e optionalScopes. Saiba mais sobre como especificar cada um desses tipos de escopo no guia de configuração do aplicativo.
• Você não precisa definir a propriedade extensions de nível superior do seu projeto anterior, já que a propriedade não está presente no novo arquivo app-hsmeta.json. Todas as extensões de interface configuradas anteriormente (por exemplo, cartões na página do registro o CRM) são gerenciadas usando o diretório cards/ do seu projeto. Nesse diretório, os detalhes da configuração do cartão são especificados em um arquivo *-hsmeta.json, juntamente com o código de componente do cartão fornecido em um arquivo .jsx que é referenciado usando a propriedade entrypoint do arquivo *-hsmeta.json.
• Você também não precisa definir acima da propriedade webhooks de nível superior do seu projeto anterior no novo arquivo app-hsmeta.json, à medida que os webhooks são configurados e gerenciados usando o diretório webhooks/ do seu projeto. Saiba mais na seção Migrar assinaturas de webhook abaixo.

​

Atualizar a configuração de componentes individuais

​

Migrar cartões do CRM criados com extensões de interface

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

• O valor da propriedade type foi alterado de "crm-card" para "card".
• A propriedade uid foi transferida de uma subpropriedade de data e agora é especificado no nível superior da sua configuração.
• A propriedade data foi alterada para config, que inclui as seguintes subpropriedades:
  • A propriedade title foi renomeada para name.
  • Uma nova propriedade description permite que você forneça mais contexto sobre a funcionalidade do cartão. A descrição aparecerá nas configurações de projeto do seu aplicativo.
  • A propriedade module foi renomeada para entrypoint e o valor deve agora ser uma string que representa o caminho para o componente JSX, relativo à raiz do seu projeto (por exemplo, "/app/cards/example-app-card.jsx").
  • A propriedade objectTypes foi simplificada e agora é uma matriz de strings que representa os tipos de objetos em que seu cartão deve aparecer (por exemplo, ["CONTACT", "COMPANY"]).
  • A propriedade location permanece inalterada e pode ser definida como crm.record.tab, crm.record.sidebar ou helpdesk.sidebar.

​

Migrar assinatura 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
        }
      ]
    }
  }
}

• Uma propriedade uid obrigatória deve ser definida no nível superior do seu arquivo *-hsmeta.json, que deve receber um nome para diferenciá-lo de outros recursos de aplicativo (por exemplo, "migrated_private_app_webhooks").
• Uma propriedade type obrigatória também devem ser definida no nível superior da sua configuração *-hsmeta.json e deve ser definida como "webhooks".
• As propriedades subscriptions e settings permanecem inalteradas de webhooks.json mas devem ser movidas para a propriedade config definida no nível superior do seu arquivo *-hsmeta.json.

​

Carregar projeto

hs project upload

​

Migrar manipulação de funções sem servidor

• Localize suas funções sem servidor no projeto do seu aplicativo privado existente no diretório src/app/app.functions.
• Copie toda a lógica relevante de suas funções. No exemplo de função sem servidor abaixo, somente a linha 4 precisa ser copiada.

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

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

  return response;
};

• Na plataforma de hospedagem de terceiros, cole a lógica da sua definição de função sem servidor anterior e verifique se os nomes dos parâmetros estão alinhados. Você precisará consultar a documentação para definir a função sem servidor na plataforma que está usando.
• Copie seu token de acesso da página de detalhes do projeto do seu aplicativo e adicione-o como uma variável de ambiente em sua plataforma de hospedagem de terceiros para que possa ser referenciado em seu código.
• Em seguida, você precisará atualizar a propriedade permittedUrls do seu arquivo de esquema app-hsmeta.json de nível superior para incluir o campo fetch. O valor deste campo deve ser definido para uma matriz que inclua o URL do seu ponto de extremidade hospedado na plataforma de hospedagem de terceiros.
• Em seguida, atualize quaisquer referências em seu código React em seus cartões de aplicativo para chamar o novo URL da função sem servidor que você configurou. Saiba mais sobre como usar hubspot.fetch() neste guia.

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

​

Limpar

• Na sua conta da HubSpot, acesse Desenvolvimento.
• Na página Projetos, clique no nome do seu projeto antigo.
• Clique na guia Configurações.
• Em Excluir este projeto, clique em Excluir [nome do projeto].
• Revise as informações na caixa de diálogo para confirmar se você está pronto para continuar. Em seguida, insira o nome do projeto e clique em Excluir projeto.

​

Próximas etapas

• Criar um componente de configurações
• Definir ações de fluxo de trabalho personalizado
• Gerenciar aplicativos no HubSpot