Referência de objetos de aplicativo (BETA)

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.

Veja abaixo informações de referência para recursos de aplicativo da plataforma de desenvolvedor com objetos de aplicativo, incluindo definições de arquivo de configuração, detalhes de escopos e muito mais.

Estrutura do projeto

Todos os componentes do projeto devem estar no diretório src especificado no arquivo de configuração hsproject.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).

O exemplo de estrutura de diretório abaixo descreve todos os recursos disponíveis.

my-folder/
├── hsproject.json
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

Ver exemplo no GitHub

Objetos de aplicativo

Para criar um objeto de aplicativo, inclua um diretório do componente app-objects no projeto, com um arquivo de configuração.

...
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
└──

Veja abaixo as opções de configuração disponíveis para *-object-hsmeta.json.

{
  "uid": "car-app-object",
  "type": "app-object",
  "config": {
    "name": "CAR",
    "appPrefix": "Vroom",
    "description": "An automobile in our warehouse.",
    "singularForm": "Car",
    "pluralForm": "Cars",
    "primaryDisplayLabelPropertyName": "model",
    "secondaryDisplayLabelPropertyNames": ["make"],
    "settings": {
      "hasRecordPage": true,
      "allowsUserCreatedRecords": true,
      "hasEngagements": true
    },
    "properties": [
      {
        "type": "string",
        "fieldType": "text",
        "name": "model",
        "label": "Model",
        "description": "The model of the car"
      },
      {
        "type": "enumeration",
        "fieldType": "select",
        "name": "make",
        "label": "Make",
        "description": "The manufacturer of the car.",
        "options": [
          {
            "label": "Ford",
            "value": "ford",
            "displayOrder": 0
          },
          {
            "label": "Toyota",
            "value": "toyota",
            "displayOrder": 1
          },
          {
            "label": "Chevrolet",
            "value": "chevrolet",
            "displayOrder": 2
          }
        ]
      }
    ]
  }
}

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ção app-hsmeta.json no diretório app.

...
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
└──

Veja abaixo as opções de configuração disponíveis para app-hsmeta.json.

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 e config adicionados.
Campo extensions removido.
Campo distribution adicionado.

{
  "uid": "app_object_poc_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with an app object on developer projects.",
    "name": "my first app object app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

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

"auth": {
      "type" : "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write",
        "crm.app.objects.a12345_MY_APP_OBJECT.view",
        "crm.app.objects.a12345_MY_APP_OBJECT.create",
        "crm.app.objects.a12345_MY_APP_OBJECT.edit",
        "crm.app.schemas.a12345_MY_APP_OBJECT.read",
        "crm.app.objects.a12345_MY_APP_OBJECT.merge",
        "crm.app.objects.a12345_MY_APP_OBJECT.delete",
        "crm.app.schemas.a12345_MY_APP_OBJECT.properties.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },

Para obter uma lista completa dos escopos disponíveis, consulte a referência de escopos.

Definição de componente webhooks

Para definir um conjunto de assinaturas de webhook para seu aplicativo, inclua um diretório webhooks no projeto, junto com um arquivo de configuração *-hsmeta.json.

├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
└──

Veja as opções de configuração disponíveis para o arquivo *-hsmeta.json.

{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "car_app_object",
          "propertyName": "carProperty",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "contact.deletion",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

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

Para cada objeto 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ório cards do componente no projeto, junto com um arquivo de configuração.

├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

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 à matriz objectTypes ("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

Observe as seguintes alterações para os arquivos de configuração de cartão de aplicativo:

Campos de nível superior uid, type e config adicionados.
O campo module foi renomeado para entrypoint.
O campo title foi renomeado para name.
O campo objectTypes foi simplificado para aceitar uma matriz de strings.

{
  "uid": "my-app-card",
  "type": "card",
  "config": {
    "name": "My app card",
    "description": "An example description of the card, which lives on contact records.",
    "previewImage": {
      "file": "./preview.png",
      "altText": "A short description of the preview image"
    },
    "entrypoint": "/app/cards/MyCard.jsx",
    "location": "crm.record.tab",
    "objectTypes": ["contacts", "app_object_uid"]
  }
}

Depois de salvar as alterações no seu arquivo example-card-hsmeta.json, execute hs project upload.

Os cartões são adicionados automaticamente à exibição padrão para objetos de aplicativo. Se o cartão não aparecer automaticamente, veja como adicionar cartões a registros de CRM.

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 componente app-object-associations no projeto, junto com um arquivo de configuração.

├── src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
└──

Veja abaixo as opções de configuração de objeto do aplicativo disponíveis (*-association-hsmeta.json).

{
  "uid": "car_to_contact_association",
  "type": "app-object-association",
  "config": {
    "firstObjectType": "car-app-object",
    "secondObjectType": "CONTACT"
  }
}

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.

Criar aplicativos

Adicionar recursos

Publicar no HubSpot Marketplace

Referência de objetos de aplicativo (BETA)

Estrutura do projeto

Ver exemplo no GitHub

Objetos de aplicativo

Ver exemplo no GitHub

Esquema de aplicativo

Ver exemplo no GitHub

Campos *-hsmeta.json do esquema do aplicativo

campos de autenticação

Escopos

Definição de componente webhooks

Campos webhook *-hsmeta.json

Esquema do cartão de aplicativo

Ver exemplo no GitHub

Campos *-hsmeta.json do cartão de aplicativo

Associações de objetos de aplicativo

Campos *-association-hsmeta.json de associação

​Estrutura do projeto

Ver exemplo no GitHub

​Objetos de aplicativo

Ver exemplo no GitHub

​Esquema de aplicativo

Ver exemplo no GitHub

​Campos *-hsmeta.json do esquema do aplicativo

​campos de autenticação

​Escopos

​Definição de componente webhooks

​Campos webhook *-hsmeta.json

​Esquema do cartão de aplicativo

Ver exemplo no GitHub

​Campos *-hsmeta.json do cartão de aplicativo

​Associações de objetos de aplicativo

​Campos *-association-hsmeta.json de associação

Estrutura do projeto

Objetos de aplicativo

Esquema de aplicativo

Campos *-hsmeta.json do esquema do aplicativo

campos de autenticação

Escopos

Definição de componente webhooks

Campos webhook *-hsmeta.json

Esquema do cartão de aplicativo

Campos *-hsmeta.json do cartão de aplicativo

Associações de objetos de aplicativo

Campos *-association-hsmeta.json de associação