Aplicativos públicos

Na HubSpot, um aplicativo público é um tipo de integração que pode ser instalada nas contas de clientes ou listadas no Marketplace de aplicativos. Isso requer autenticação por OAuth. Assim que um usuário instalar o app em sua conta da HubSpot, você poderá fazer chamadas de API para essa conta usando um token de acesso OAuth. O app também aparecerá nas configurações Apps conectados da conta. Os aplicativos conectados também podem fazer a assinatura de alterações usando webhooks e criar eventos de linha do tempo personalizados. Abaixo, aprenda como:

• Criar um aplicativo público
• Instalar um aplicativo público em uma conta
• Gerenciar o aplicativo, inclusive o monitoramento do uso
• Adicionar um domínio verificado ao aplicativo

​

Criar um aplicativo público

Ao criar um app na HubSpot, você basicamente associa o app criado com uma conta de desenvolvedor. Para começar a criar seu app da HubSpot:

• Na sua conta de desenvolvedor de apps, navegue até Apps na barra de navegação principal.
• No canto superior direito, clique em Criar app.
• Em seguida, preencha algumas informações básicas e configurações do app. Quando os usuários autenticarem o aplicativo na conta da HubSpot, eles verão o nome, a descrição, o logotipo e qualquer informação de contato de suporte que você fornecer nesta página.

• Clique na guia Autenticação para visualizar o ID e o segredo do cliente, bem como os escopos atribuídos ao aplicativo. Você precisará dessas informações aoiniciar uma conexão OAuth entre o aplicativo e o HubSpot.

​

Configurar escopos

Os escopos determinam as permissões do seu aplicativo para acessar as fontes de dados ou ferramentas em uma conta que tenha instalado o aplicativo. Os escopos configurados aparecerão como os parâmetros de consulta scope e optional_scope em um URL de instalação que você pode fornecer aos usuários.

​

Tipos de escopo

Na guia Autenticação, estão disponíveis três tipos de escopos diferentes para você configurar. Você deve especificar os escopos do aplicativo necessários para a instalação, mas também pode especificar dois outros tipos de escopos: condicionalmente obrigatórios e opcionais.

• Escopos obrigatórios: escopos que devem ser autorizados pelo usuário e devem estar presentes no parâmetro de consulta scope no URL de instalação do aplicativo para uma instalação bem-sucedida.
• Escopos condicionalmente obrigatórios: escopos que devem ser autorizados pelo usuário somente se estiverem presentes no parâmetro de consulta scope no URL de instalação do aplicativo para uma instalação bem-sucedida.
  • Este tipo de escopo permite ser flexível e fornecer um URL de instalação separado para funcionalidades ou escopos escalonados que só são obrigatórios quando os usuários ativam determinadas funcionalidades no seu aplicativo. Por exemplo, você pode oferecer dois URLs de instalação aos seus usuários: um URL de instalação pode incluir o escopo condicionalmente obrigatório no parâmetro de consulta scope para usuários com acesso a uma funcionalidade, enquanto outro URL de instalação omite esse escopo no parâmetro de consulta scope para usuários sem acesso.
  • Se um escopo condicionalmente obrigatório estiver presente no URL de instalação do seu aplicativo e um usuário sem acesso à funcionalidade associada tentar instalar o aplicativo utilizando esse URL, a instalação falhará.
• Escopos opcionais: escopos que não são obrigatórios para instalar o aplicativo com êxito. Estes escopos são especificados no parâmetro de consulta optional_scope no URL de instalação do seu aplicativo. Por exemplo, se quiser que seu aplicativo possa obter dados de objetos personalizados (que só estão disponíveis para contas Enterprise da HubSpot), poderá adicionar o escopo crm.objects.custom.read como um escopo opcional. Depois, se uma conta tiver acesso aos objetos personalizados, o escopo será autorizado. Caso contrário, ainda será possível instalar o aplicativo sem o escopo dos objetos personalizados.

​

Configurar os escopos de aplicativos públicos

Para personalizar as configurações do seu escopo e adicionar novos escopos:

• Para configurar os escopos condicionalmente obrigatórios ou opcionais, clique para ativar a opção Ativar configurações avançadas de escopo.

• Na seção Escopos, clique em Adicionar novo escopo.
• No painel direito, utilize a barra de pesquisa para procurar um escopo e, em seguida, marque a caixa de seleção ao lado de qualquer escopo que pretenda que o usuário autorize. Se você ativou as configurações avançadas de escopo, clique no menu suspenso ao lado do escopo e selecione um tipo de escopo.
• Clique em Atualizar.

• Revise os escopos configurados. Se você ativou as configurações avançadas de escopo, poderá mudar o tipo de escopo de qualquer escopo clicando no menu suspenso ao lado do escopo. Você também pode clicar em Excluir para remover um dos escopos do seu aplicativo.

• Quando tiver terminado de definir as configurações do aplicativo, clique em Criar aplicativo no canto inferior esquerdo.

Com o seu app criado, agora é possível realizar o processo de instalação.

​

Instalar um app

A instalação de um app pode ser dividida em duas etapas: autorização e geração de token.

​

Autorize o aplicativo com uma conta de cliente.

• Para autorizar o aplicativo com uma conta da HubSpot, você precisará criar um URL de autorização. Para fazer isso, obtenha o ID de cliente do aplicativo e inicie o processo do OAuth.
• Depois que o URL estiver pronto, abra-o no navegador para ver uma lista de todas as suas contas da HubSpot. É exatamente isso que os usuários verão quando você direcioná-los para esse URL.
• Selecione a conta em que deseja instalar o app.

• Depois de escolher uma conta, você verá uma lista de escopos com base nos parâmetros &scope= e &optional_scope= definidos para o URL de autorização.

• Clique em Conceder acesso para autorizar a conexão.

• Depois que o acesso for concedido, você será redirecionado de acordo com o parâmetro &redirect_uri= no URL de autorização original, e um parâmetro ?code= será anexado ao URL. Use esse código na próxima etapa para gerar um token de acesso.

​

Gerar tokens iniciais do OAuth

Para gerar seus tokens de acesso iniciais e de atualização, você precisará do código do parâmetro ?code= do URL de autorização, do redirect_url e do ID e do segredo do cliente. Você encontrará instruções detalhadas aqui. Depois de autorizar o aplicativo e gerar os tokens iniciais, a instalação estará concluída. Ele será listado em sua página Apps conectados e você começará a receber solicitação de busca de webhook e cartões CRM.

​

Gerenciar aplicativos públicos no HubSpot

​

Find an app’s ID

Você pode encontrar o ID de um aplicativo público na sua conta de desenvolvedor de aplicativos, usando um dos métodos a seguir:

• Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal e visualize o ID do aplicativo listado abaixo do nome do seu aplicativo.

• Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal e clique no nome do aplicativo. Na página Informações básicas, clique na guia Autenticação e visualize o ID do aplicativo.

​

Monitorar o comportamento do aplicativo

O HubSpot registra todas as solicitações feitas para um app conectado, incluindo solicitações recebidas usando um token de acesso OAuth ou solicitações enviadas para webhooks ou cartões de CRM. Para visualizar este registro de solicitação:

• Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal.
• Clique no nome do aplicativo.
• No menu da barra lateral esquerda, acesse Monitoramento.
• Use as guias para visualizar diferentes tipos de solicitações feitas para ou por meio do app. Ao visualizar esses registros, você pode clicar em uma solicitação individual para visualizar mais informações sobre ela, incluindo:
  • para solicitações bem-sucedidas, o método, o caminho e o horário da solicitação.
  • para solicitações malsucedidas, informações de erro adicionais, como cabeçalhos de resposta e corpo.

Abaixo, saiba mais sobre cada guia da página Monitoramento.

• Chamadas de API: a guia Chamadas de API mostrará todas as solicitações feitas no aplicativo usando um token de acesso de OAuth. Ele pode ser filtrado por método HTTP, código de resposta, período ou URL de solicitação.
• Webhooks: a guia Webhooks mostra as solicitações do HubSpot para todas as suas assinaturas de webhook do aplicativo. Filtre por resposta (inclusive tempo limite e falhas de conexão), status (sucesso, nova tentativa ou falha), tipo de assinatura, período de tempo, tentativa, lote, evento ou ID da conta.

• Extensões do CRM: a guia Extensões do CRM mostra as solicitações para os Cartões de CRM do aplicativo. Filtre por tipo de objeto de extensão, tipo de objeto de CRM (contato, empresa, ticket ou negócio), erro ou tipo de aviso, período de tempo, ID da solicitação ou ID de registro de CRM (ou seja, um ID de contato específico).
• Configurações do aplicativo: a guia Configurações do aplicativo permite configurar a página de configurações do aplicativo.

Em cada guia, se algum evento associado ocorreu nos últimos 30 dias (por exemplo, um gatilho de webhook ou uma chamada de API), você pode clicar em Exportar registros para exportar os dados de evento associados para um CSV:

• Na caixa de diálogo, configure quantos dias de dados devem ser exportados (até 30 dias).
• Clique em Exportar. Será enviada uma notificação por e-mail para o endereço de e-mail associado ao seu usuário nas suas configurações da HubSpot.

​

Adicionar um domínio verificado

Quando os usuários do HubSpot instalam um aplicativo, eles consentem o acesso aos dados de suas contas ao desenvolvedor do aplicativo. A identidade e a reputação do desenvolvedor desempenham um papel importante na decisão de um usuário de continuar com a instalação. Para garantir o consentimento total do usuário ao instalar um aplicativo, a HubSpot exibirá uma mensagem na tela de instalação do aplicativo para indicar seu nível de verificação e a listagem no Marketplace de aplicativos:

• Se um aplicativo não tiver um domínio verificado, a HubSpot exibirá um banner na tela de instalação, informando que o aplicativo não foi verificado.

• Se o aplicativo tiver um domínio verificado, mas não estiver listado no Marketplace de aplicativos, o HubSpot exibirá o domínio verificado junto com um banner na tela de instalação, informando que o aplicativo não foi revisado ou aprovado pela HubSpot.

• Quando um aplicativo for listado no marketplace e aprovado pelo processo de revisão do aplicativo da HubSpot, o HubSpot não exibirá nenhum dos banners acima. Não é necessário verificar o domínio se o aplicativo tiver sido listado no Marketplace de aplicativos.

​

Adicionar um domínio verificado

Para adicionar um domínio verificado ao aplicativo, você precisará primeiro adicionar o domínio às configurações do aplicativo e, em seguida, um registro TXT às configurações de DNS do domínio:

• Na sua conta de desenvolvedor de aplicativos, acesse Aplicativos.
• Clique no nome do aplicativo.
• Na barra lateral esquerda, acesse Contato e suporte.
• No campo Domínio da empresa, insira seu domínio e clique em Salvar. Uma mensagem será exibida abaixo do Domínio da empresa, informando que o domínio ainda não foi verificado.
• Clique em Verificar agora para iniciar o processo de verificação.

• No painel direito, confirme se o domínio foi inserido corretamente e clique em Próximo.
• Copie o valor do registro de TXT exigido, clicando em Copiar na coluna Valor.

• No seu provedor de DNS, crie um registro de TXT com o valor copiado. Veja a seguir as instruções para alguns provedores de DNS comuns:
  • GoDaddy
  • BlueHost
  • Namecheap
  • Cloudflare
  • Hover
  • Nome
  • Domínios unidos
• Depois de atualizar as configurações de DNS, volte ao HubSpot e clique em Próximo no painel direito. Os registros de DNS podem levar até 48 horas para serem atualizados, portanto, o HubSpot pode não reconhecer a alteração imediatamente. Você pode voltar a essa tela a qualquer momento, selecionando novamente a opção Verificar agora na página de configurações Informações da empresa.
• Depois da verificação, será exibido um indicador de status de sucesso no campo Domínio da empresa.

​

Observações adicionais

• Para garantir a propriedade contínua do domínio, o HubSpot continuará a verificar se o registro TXT está presente regularmente. O aviso de instalação retornará se o registro TXT for removido ou modificado.
• Atualmente, você pode ter apenas um domínio verificado por conta de desenvolvedor. Todos os aplicativos em uma conta compartilham o domínio verificado. O domínio na página de instalação será vinculado ao seu domínio raiz.
• Se você excluir seu domínio verificado, todos os aplicativos da sua conta de desenvolvedor receberão o aviso de instalação novamente. Você pode verificar outro domínio, mas o processo levará algumas horas.