Última modificação: 11 de setembro de 2025
Esse recurso requer aprovação da HubSpot para ser usado. Se você tiver interesse em se inscrever para receber o acesso a objetos de aplicativo ou se quiser saber mais sobre a funcionalidade, envie este formulário de interesse.
Estrutura do projeto
- Todos os componentes do projeto devem estar no diretório
src
especificado no arquivo de configuraçãohsproject.json
. - Todos os recursos e componentes do aplicativo devem estar no diretório
app/
. - As associações de objeto do aplicativo são definidas no diretório
app-object-associations/
. - As assinaturas de webhook são definidas no diretório
webhooks/
. - As ações de fluxo de trabalho personalizadas são definidas no diretório
workflow-actions/
. - Todos os recursos do cartão devem estar no diretório
cards/
. - Todas as declarações de instâncias de componente e recurso são feitas com arquivos
*-hsmeta.json
. Você deve usar algo significativo no nome do arquivo (por exemplo,my-app-hsmeta.json
). Esses arquivos devem estar no nível raiz da respectiva pasta (por exemplo,app/my-app-hsmeta.json
,cards/my-card-hsmeta.json
).
Ver exemplo no GitHub
Objetos de aplicativo
Para criar um objeto de aplicativo, inclua um diretório do componenteapp-objects
no projeto, com um arquivo de configuração.
*-object-hsmeta.json
.
Ver exemplo no GitHub
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | Um identificador exclusivo para o objeto do aplicativo. Deve ser globalmente exclusivo dentro do projeto. |
type * | String | O tipo de componente. Deve corresponder ao nome da pasta principal (app-object ). |
name * | String | O nome do seu objeto de aplicativo. Use o nome aprovado recebido na confirmação do aplicativo aprovado. Deve usar letras maiúsculas separadas por sublinhado (snake case) (MY_OBJECT_NAME ). |
appPrefix | String | Uma sequência de caracteres que precede o nome singular ou plural do objeto na interface do usuário do HubSpot para ajudar a diferenciá-lo de outros. Neste exemplo, o appPrefix de Vroom e singularForm de Car resultaria na exibição de “Vroom Car” na interface. |
description * | String | A descrição do objeto, que será mostrada no HubSpot. |
singularForm * | String | A forma singular do nome do objeto. |
pluralForm * | String | A forma plural do nome do objeto. |
properties * | Matriz | Uma lista de propriedades de CRM definidas para o objeto. As propriedades são definidas usando os mesmos campos da API de propriedades. As propriedades resultantes terão o prefixo a<appId>_ (por exemplo, a12345_make ) na criação. Você não deve incluir o prefixo no arquivo de configuração. |
primaryDisplayLabelPropertyName * | String | O nome da propriedade que deve ser usada como propriedade de exibição principal. O valor deve corresponder ao nome fornecido na lista properties (ou seja, não deve incluir o prefixo a<appId>_ gerado.) |
secondaryDisplayLabelPropertyNames * | Matriz | A lista das propriedades que devem ser usadas como propriedades de exibição secundária. O valor deve corresponder ao nome fornecido na lista properties (ou seja, não deve incluir o prefixo a<appId>_ gerado.) |
settings * | Objeto | Um objeto que contém as configurações de objeto. |
hasRecordPage * | Booleano | Se existem páginas de registro para instâncias deste objeto de aplicativo. Quando definido como false , a página de índice existirá, mas não incluirá links para páginas de registro individuais. |
allowsUserCreatedRecords * | Booleano | Se os usuários finais poderão criar registros usando o objeto. Quando definido como false , os usuários não poderão criar registros no HubSpot |
hasEngagements * | Booleano | Se os registros de objeto do aplicativo permitem atividades/engajamentos. Quando definido como false , as páginas de registro de objeto do aplicativo não incluirão nenhuma funcionalidade de engajamento, como a guia de atividade ou filtros de linha do tempo relacionados à atividade. |
O nome totalmente qualificado (FQN) do objeto do aplicativo será
a<appId>_<objectName>
. Por exemplo: se o seu appId
é 16858319
e o nome do objeto do aplicativo é CARS
, o FQN será a16858319_CARS
. Você usará o FQN ao definir valores de escopo para seus objetos de aplicativo.Esquema de aplicativo
Para criar um objeto de aplicativo, inclua um arquivo de configuraçãoapp-hsmeta.json
no diretório app
.
app-hsmeta.json
.
Resumo da alteração
Resumo da alteração
Observe as seguintes alterações para os arquivos de configuração de cartão de aplicativo:
- Campos de nível superior
uid
,type
econfig
adicionados. - Campo
extensions
removido. - Campo
distribution
adicionado.
Ver exemplo no GitHub
Campos *-hsmeta.json do esquema do aplicativo
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | Um identificador exclusivo interno do aplicativo. Deve ser globalmente exclusivo dentro do projeto. Pode ser qualquer string de até 64 caracteres. Os caracteres podem ser maiúsculos ou minúsculos e podem incluir números e sublinhados (_ ), traços (- ) e pontos (. ). |
type * | String | O tipo de componente. Deve corresponder ao nome da pasta principal (app ). |
description * | String | Uma descrição do que o aplicativo faz para o usuário que está instalando. Pode ser qualquer string de até 8192 caracteres. |
name * | String | O nome do aplicativo, que será exibido na interface do HubSpot. Pode ser qualquer string de até 200 caracteres. Não deve iniciar ou terminar com um caractere de espaço. |
distribution * | String | O método de distribuição do aplicativo. Precisa ser definido como marketplace para que o aplicativo possa ser listado no Marketplace de aplicativos. |
auth * | Objeto | Um objeto que contém os detalhes do método de autenticação do aplicativo. Consulte a tabela de autenticação para obter detalhes. |
permittedUrls | Objeto | Uma matriz que contém os URLs que o aplicativo tem permissão para chamar. Os URLs devem usar o esquema HTTPS e devem conter uma autoridades, seguido por um prefixo de caminho opcional, se necessário. |
supportEmail | String | Um endereço de e-mail válido com o qual os usuários podem entrar em contato para obter suporte. |
documentationUrl | String | O URL externa na qual os usuários podem navegar para documentação de suporte. Devem usar HTTPS. |
supportUrl | String | O URL externo para o qual os usuários podem navegar para obter suporte adicional. Devem usar HTTPS. |
supportPhone | String | O número de telefone com o qual os usuários podem entrar em contato para obter suporte. Deve começar com um sinal de mais (+ ). |
campos de autenticação
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
type * | String | O tipo de autenticação. Deve ser definido como oauth para que o aplicativo use a autenticação OAuth. |
redirectUrls * | Matriz | Uma lista de URLs que o OAuth tem permissão para usar em redirecionamentos. Cada aplicativo deve ter pelo menos um URL de redirecionamento de autenticação e deve usar HTTPS. A única exceção é que http://localhost é permitida para testes. |
requiredScopes * | Matriz | Uma lista dos escopos obrigatórios do seu aplicativo. Cada aplicativo deve incluir pelo menos um escopo, e o usuário instalador deve conceder esses escopos para instalar o aplicativo. Saiba mais sobre escopos abaixo. |
optionalScopes | Matriz | Uma lista dos escopos opcionais do seu aplicativo. Esses escopos podem ser excluídos da autorização durante a instalação se a conta ou o usuário que está instalando o aplicativo não tiver as permissões adequadas. Nesse caso, o escopo não será incluído no token de atualização ou de acesso resultante. Saiba mais sobre escopos abaixo. |
conditionallyRequiredScopes | Matriz | Uma lista de escopos que são necessários somente quando incluídos no parâmetro de consulta scope do URL de instalação. Saiba mais sobre escopos abaixo. |
Escopos
Na janelaauth
de um arquivo de configuração de aplicativo, você pode especificar três tipos de escopos: necessários, condicionalmente necessários e opcionais. Para este estágio da versão beta, você deve apenas incluir seus escopos de objeto de aplicativo como conditionallyRequiredScopes
. Isso permitirá armazenar seus novos recursos isoladamente para clientes específicos, incluindo os escopos de objeto de aplicativo no URL de instalação.
Os escopos de objeto de aplicativo usam o seguinte formato:
crm.app.schemas.<appObjectFullyQualifiedName>.read
Por exemplo, para um objeto de aplicativo com o FQN a16858319_cars
, o escopo read
seria:
crm.app.schemas.a16858319_cars.read
.
No mínimo, seu aplicativo deve incluir o escopo read
acima para permitir que os clientes acessem o objeto. Recomendamos incluir todos os escopos de objeto de aplicativo em seu aplicativo, conforme mostrado abaixo.
Definição de componente webhooks
Para definir um conjunto de assinaturas de webhook para seu aplicativo, inclua um diretóriowebhooks
no projeto, junto com um arquivo de configuração *-hsmeta.json
.
*-hsmeta.json
.
Campos webhook *-hsmeta.json
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | Um identificador exclusivo interno do componente de webhook. |
type * | String | O tipo de componente, que deve ser webhooks neste caso. |
settings * | Objeto | Um objeto que especifica dois campos: targetUrl , que é o URL disponível publicamente para que o HubSpot chame onde as cargas do evento serão entregues, e maxConcurrentRequests , que é o limite superior das solicitações HTTP que o HubSpot fará em um determinado intervalo de tempo. |
subscriptions * | Objeto | Um objeto que especifica os tipos de assinatura em que seu aplicativo se inscreverá. |
crmObjects | Matriz | Uma matriz que contém definições de assinatura de evento. Essa é a matriz padrão a ser incluída e deve ser usada para todos os eventos no novo formato (object.* ). Os tipos de assinatura de webhook clássico devem ser incluídos nas matrizes legacyCrmObjects e hubEvents , dependendo do evento. |
legacyCrmObjects | Matriz | Uma matriz que contém tipos de assinatura clássicos, como contact.creation e deal.deletion . |
hubEvents | Matriz | Uma matriz que contém os tipos de assinatura clássica contact.privacyDeletion e conversation.* |
subscription
, os seguintes campos podem ser especificados, com base no tipo de definição de assinatura em que você está inscrito (ou seja, crmObjects
, legacyCrmObjects
, ou hubEvents
) ou se você está se inscrevendo em uma mudança de propriedade específica (por exemplo, contact.propertyChange
).
Campo | Tipo | Descrição |
---|---|---|
subscriptionType | String | O tipo de evento que está sendo assinado. |
objectType | String | Para assinaturas especificadas dentro da matriz crmObjects , especifica o objeto do CRM que seu aplicativo está assinando. Para se inscrever em alterações em um objeto de aplicativo, inclua o nome do objeto de aplicativo para este campo (por exemplo, car_app_object ). |
propertyName | String | Para assinaturas de alteração de propriedade, especifica quais propriedades acionarão o evento de webhook. |
active | Booleano | Se os eventos de webhook serão disparados para esta assinatura. |
Esquema do cartão de aplicativo
Para criar um cartão de aplicativo que aparece em uma página de registro de objeto de aplicativo, inclua um diretóriocards
do componente no projeto, junto com um arquivo de configuração.
- Lembre-se de executar
hs project upload
depois de criar o componente de objeto de aplicativo e os arquivos de configuração associados. - No seu arquivo
my-app-card-hsmeta.json
, adicione o UID do objeto do aplicativo à matrizobjectTypes
("app_object_uid"
, neste exemplo). Cada um dos campos disponíveis no arquivo.json
são detalhados na seção tabela a seguir.
Resumo da alteração
Resumo da alteração
Observe as seguintes alterações para os arquivos de configuração de cartão de aplicativo:
- Campos de nível superior
uid
,type
econfig
adicionados. - O campo
module
foi renomeado paraentrypoint
. - O campo
title
foi renomeado paraname
. - O campo
objectTypes
foi simplificado para aceitar uma matriz de strings.
- Depois de salvar as alterações no seu arquivo
example-card-hsmeta.json
, executehs project upload
.
Ver exemplo no GitHub
Campos *-hsmeta.json do cartão de aplicativo
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | O identificador exclusivo do cartão. Ele pode ser qualquer string, mas deve identificar o aplicativo de uma maneira significativa. O HubSpot identificará o cartão por esse ID para que você possa alterar o título do cartão sem remover dados do histórico ou de estado, como a posição no registro de CRM. |
type | String | O tipo de componente, que deve ser card neste caso. |
config | Objeto | Um objeto que contém detalhes de configuração. |
name * | String | O título do cartão, exibido na interface do usuário do HubSpot. |
description | String | Uma descrição do cartão. |
previewImage | Objeto | Um objeto que contenha os campos file e altText . O campo file é o caminho relativo para a imagem de visualização. As extensões de arquivo válidas são png, jpeg, jpg ou gif. O tamanho máximo do arquivo é 5,0 MB. O campo altText é uma breve descrição da imagem. |
entrypoint * | String | O caminho de arquivo do código do React de frontend do cartão. |
location * | crm.record.tab | crm.record.sidebar | helpdesk.sidebar | Onde o cartão aparece na interface do usuário do HubSpot. Saiba mais sobre localização da extensão. |
objectTypes * | Matriz | Os tipos de registros de CRM em que o cartão aparecerá. |
Associações de objetos de aplicativo
Para ativar as associações entre o objeto do aplicativo e outros objetos de CRM, inclua um diretório do componenteapp-object-associations
no projeto, junto com um arquivo de configuração.
*-association-hsmeta.json
).
Campos *-association-hsmeta.json de associação
Campos marcados com * são obrigatórios.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | Um identificador exclusivo interno do aplicativo. Deve ser globalmente exclusivo dentro do projeto. |
type * | String | O tipo de componente. Deve corresponder ao nome da pasta principal (app-object-association ). |
config * | Objeto | Um objeto que contém a configuração de associação de objeto. |
firstObjectType * | String | O primeiro objeto da associação. Pode ser um objeto ou um objeto de CRM da HubSpot. Objetos de aplicativo são referenciados por seu uid especificado no arquivo de origem. Objetos padrão são referenciados por seu fullyQualifiedName . A associação resultante será bidirecional, de modo que a ordem desses valores de campo é arbitrária. |
secondObjectType * | String | O segundo objeto na associação. Veja firstObjectType para mais informações. |