Referência de eventos de aplicativo (BETA)

Veja abaixo as informações de referência para usar eventos de aplicativo, incluindo esquemas de tipo de evento, modelos de renderização de linha do tempo de eventos, campos de ocorrência de eventos e muito mais.

Estrutura do projeto

No contexto de um projeto, as definições de tipo de evento serão colocadas em um diretório app-events em app/. O diretório app-events deve conter um arquivo de definição de esquema JSON para cada tipo de evento (*-hsmeta.json).

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json

Para incluir definições de tipo de evento em um projeto, é necessário o seguinte:

Seu aplicativo deve usar a autenticação OAuth e ser configurado para distribuição no Marketplace de aplicativos. Além disso, o aplicativo deve incluir timeline no seu requiredScopes. Saiba mais sobre a configuração de aplicativos.
Seu projeto deve ser implantado com êxito para que um componente de evento de aplicativo possa ser incluído.

Esquema de tipo de evento

Veja abaixo as opções de configuração disponíveis para esquemas de tipo de evento (*-hsmeta.json). Observe que alguns atributos abaixo não podem ser alterados depois da criação do tipo de evento.

Cada aplicativo tem um limite de 750 tipos de eventos.

{
  "uid": "customer_login_event",
  "type": "app-event",
  "config": {
    "name": "Customer login",
    "headerTemplate": "{{customerName}} logged in.",
    "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
    "objectType": "CONTACT",
    "properties": [
      {
        "name": "customerName",
        "label": "Customer Name",
        "type": "string"
      },
      {
        "name": "loginLocation",
        "label": "Login location",
        "type": "enumeration",
        "options": [
          {
            "value": "mobileApp",
            "label": "Mobile app"
          },
          {
            "value": "website",
            "label": "Website"
          }
        ]
      }
    ]
  }
}

Campos marcados com * são obrigatórios.

Campo	Tipo	Descrição
`uid`*	String	Um identificador exclusivo interno para o tipo de evento.
`type`*	String	O tipo de componente. Deve ser `app-event`.
`name`*	String	O rótulo exibido no HubSpot (até 50 caracteres). Este valor não pode ser atualizado após a criação.
`objectType`*	String	O nome totalmente qualificado do objeto do CRM ao qual as ocorrências de evento podem ser associadas. Este valor não pode ser alterado após a criação. Pode ser um dos seguintes: `COMPANY`, `CONTACT`, `CUSTOM_OBJECT`, `DEAL`, `TICKET`, `APP_OBJECT`.
`headerTemplate`	String	O modelo de renderização para o cabeçalho do cartão de atividades de linha do tempo do CRM. Pode ter até 1.000 caracteres de comprimento.
`detailTemplate`	String	O modelo de renderização para o corpo do cartão de atividades de linha do tempo do CRM. Pode ter até 10.000 caracteres de comprimento.
`properties`	Matriz	Propriedades definidas para o tipo de evento no qual você armazenará dados de ocorrência de evento. Cada tipo de evento pode ter até 500 propriedades. Saiba mais sobre propriedades de evento abaixo.

Propriedades do evento

Ao definir o esquema de evento, use a matriz properties para definir os campos para os quais os dados de ocorrência de evento serão enviados. Cada tipo de evento pode ter até 500 propriedades.

 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]

Campos marcados com * são obrigatórios.

Campo	Tipo	Descrição
`name`*	String	O nome interno da propriedade. Deve ter entre 1 e 500 caracteres minúsculos. Os nomes das propriedades devem ser exclusivos por tipo de evento. Este valor não pode corresponder ao regex `"[A-Za-z0-9_\\-.]+"` ou começar com `hs_`.
`label`*	String	O rótulo exibido em HubSpot. Deve ter entre 1 e 500 caracteres minúsculos.
`type`*	String	O tipo de dados capturados na propriedade. Pode ser: `STRING`, `NUMBER`, `DATE`, `ENUMERATION`.
`options`	Matriz	Para tipos de propriedade `ENUMERATION`, este campo fornece as opções disponíveis. Deve conter pelo menos uma opção. Cada opção é um objeto que contém: `name`: o rótulo para a opção exibida em HubSpot. `value`: o valor interno fornecido pela ocorrência do evento. `name` e `label` devem ser exclusivos ao tipo de evento.
`objectPropertyName`	String	Se incluído, o nome do objeto do CRM que deve ser atualizado quando dados de evento são enviados ao HubSpot. O valor desta propriedade substituirá os valores existentes nessa propriedade. Saiba mais sobre como usar o carimbo de propriedades de registro de CRM abaixo.

Carimbos de propriedade

Em alguns casos, talvez você queira modificar os valores da propriedade do registro do CRM com base nos dados de ocorrência do evento do aplicativo. Por exemplo, você pode querer atualizar o nome e o sobrenome de um contato com novos valores definidos pela ocorrência (por exemplo, envio de formulário). Para atualizar as propriedades de registro por meio de ocorrências de evento, você pode vincular uma propriedade de evento a uma propriedade de CRM no esquema de tipo de evento. Nos campos de definição de uma determinada propriedade de evento, inclua o campo objectPropertyName e especifique a propriedade de CRM a vincular. Quando uma propriedade é vinculada, o HubSpot sempre atualiza o valor da propriedade no registro de CRM usando o valor da ocorrência mais recente com base no campo timestamp. Por exemplo, o esquema de tipo de evento abaixo vincula a propriedade de evento customerName a uma propriedade do contato personalizada denominada custom_property_name. Quando os dados de ocorrência de evento incluir um valor para customerName, custom_property_name será atualizado para o registro de CRM associado.

 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

Renderização de modelos

Os esquemas de tipo de evento podem incluir o headerTemplate e detailTemplate para configurar como as ocorrências do evento são renderizadas nas linhas do tempo de registro de CRM.

headerTemplate: uma descrição em uma linha do evento na parte superior do cartão de atividade (até 1.000 caracteres).
detailTemplate: os detalhes do evento no corpo do cartão de atividade (até 10.000 caracteres).

Os modelos de renderização são gravados usando Marcações com modelos de Handlebars. Esses modelos podem processar dados de ocorrência do evento da seguinte maneira:

Em ambos os modelos, você pode acessar qualquer dados de property passados pela ocorrência do evento usando a sintaxe {{propertyName}}.
Na janela detailTemplate, você pode acessar também valores de extraData transmitidos pela ocorrência do evento usando a sintaxe {{extraData.fieldName}}. Você pode acessar qualquer categoria de atributo em extraData por meio da notação de ponto, como {{extraData.person1.preferredName}}.

O objeto extraData só pode conter JSON válido. Se o JSON estiver malformado, a ocorrência será rejeitada e você receberá uma resposta de erro.

Por exemplo, os modelos abaixo usam os dados de propriedade customerName e loginLocation com o campo surveyData de extraData enviado através da ocorrência do evento. Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato.

Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato.

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

Como os modelos são criados com marcações e handlebars, você pode aproveitar os auxiliares de handlebars para tornar o conteúdo mais dinâmico. Por exemplo, o seguinte detailTemplate inclui o #if auxiliar para processar conteúdo condicionalmente com base no fato de os dados de ocorrência do evento incluírem o campo surveyData em extraData.

Se extraData contém surveyData, as respostas da pesquisa pós-login são mostradas.
Se não havia surveyData presente na ocorrência do evento, renderizar No additional information..

Captura de tela que mostra o que o código de exemplo abaixo renderizaria como na linha do tempo de contato.

"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

Uso de iframes

Quando os dados de ocorrência do evento contiverem o campo timelineIFrame, o cartão de atividade da linha do tempo incluirá um hiperlink em que os usuários podem clicar para abrir o conteúdo vinculado em um iframe. Captura de tela de um link incluído em um cartão de atividade de linha do tempo devido ao campo timelineIFrame

Captura de tela de um link incluído em um cartão de atividade de linha do tempo devido ao campo timelineIFrame

"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }

Campo	Tipo	Descrição
`linkLabel`	String	O texto do hiperlink que iniciará o iframe ao ser clicado.
`headerLabel`	String	O rótulo da janela do modal que mostra o conteúdo do iframe.
`url`	String	O URL do conteúdo do iframe.
`width`	Inteiro	A largura do modal iframe.
`height`	Inteiro	A altura do modal iframe.

Ocorrências de eventos

Para enviar ocorrências de um determinado tipo de evento, faça uma solicitação de POST aos pontos de extremidade abaixo. A API de eventos do aplicativo inclui pontos de extremidade para enviar ocorrências de eventos únicos e lotes de várias ocorrências de eventos. Para ambos os pontos de extremidade, os dados de ocorrência do evento precisarão ser validados em relação a um esquema de tipo de evento existente, que você especificará com eventTypeName no corpo do pedido.

Enviar uma única ocorrência
Enviar um lote de ocorrências

Para enviar uma única ocorrência de evento, faça uma solicitação de POST para /integrators/timeline/v4/events.No corpo da solicitação, inclua os dados de ocorrência do evento, cumprindo o esquema definido do tipo de evento.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Para enviar um lote de ocorrências de evento, faça uma solicitação de POST para /integrators/timeline/v4/events/batch.No corpo da solicitação, inclua até 500 objetos de ocorrência de evento separados por vírgula em uma matriz inputs. Mesmo que alguma ocorrência não seja validada, as ocorrências validadas serão aceitas e mantidas.

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

No corpo da solicitação, inclua dados com base no esquema de tipo de evento definido. O corpo da solicitação deve incluir eventTypeName, que você pode recuperar via API.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

Campos marcados com * são obrigatórios.

Campo	Tipo	Descrição
`eventTypeName`*	String	O nome totalmente qualificado do tipo de evento, usado para identificar o evento via API. Esse valor é automaticamente definido pelo HubSpot e pode ser obtido através da API depois da criação do tipo de evento. Este valor não pode ser alterado após a criação.
`objectId`*	String	O ID do registro de CRM para associar à ocorrência do evento. Este campo pode ser usado para todos os tipos de registros de CRM e é o identificador recomendado. Saiba mais sobre associação de registro de CRM.
`email`	String	Para associações de contato, você pode fornecer o endereço de e-mail do contato a ser associado. Saiba mais sobre associação de registro de CRM.
`utk`	String	Para associações de contato, você pode fornecer o token de usuário de um contato existente para associar. Saiba mais sobre associação de registro de CRM.
`domain`	String	Para associações de empresa, você pode fornecer o domínio do site de uma empresa existente. Saiba mais sobre associação de registro de CRM.
`timestamp`	String	Define a hora da ocorrência do evento (formato ISO 8601). Se não for fornecida, o HubSpot usará como padrão o carimbo de data/hora do envio de dados de ocorrência de evento.
`properties`	Objeto	Pares chave-valor de nomes de propriedades e valores de propriedades que você definiu para o tipo de evento.
`extraData`	Matriz	Quando incluída, fornece informações adicionais para renderização de linhas do tempo. Deve ser um JSON válido. Saiba mais sobre dados extras em modelos de renderização.
`timelineIFrame`	Objeto	Quando incluído, o cartão de linha do tempo conterá um hiperlink que permite que os usuários abram o conteúdo vinculado em um iframe. Saiba mais sobre como usar iframes.
`id`	String	Um identificador exclusivo para a ocorrência do evento. Deve ser exclusivo dentro do tipo de evento. Se não for fornecido, o HubSpot gerará um UUID aleatório. Quando houver vários eventos com o mesmo ID, o primeiro será aceito e todos os outros serão rejeitados.

Mesmo que alguma ocorrência não seja validada, as ocorrências validadas serão aceitas e mantidas. A mensagem de erro na resposta fornecerá informações sobre o que precisa ser corrigido. Captura de tela de um exemplo de mensagem de erro que você pode receber ao enviar dados de ocorrência de evento

Captura de tela de um exemplo de mensagem de erro que você pode receber ao enviar dados de ocorrência de evento

Associação de registro de CRM

Cada ocorrência de evento deve ser associada a um registro de CRM, com o tipo de objeto de CRM definido pelo esquema de tipo de evento. A API de eventos de aplicativo inclui vários campos para associar dados de ocorrência de evento com registros de CRM. Para todos os objetos de CRM compatíveis, recomendamos usar o campo objectId. No entanto, há algumas situações em que outros campos devem ser usados.

utk/email: se você não souber o ID do contato, use o campo utk e/ou email para identificação. Fornecer esses dois identificadores também permite criar e atualizar contatos. Por exemplo:
- Se utk corresponde a um contato existente, mas email não corresponde, o HubSpot atualizará o contato com o novo endereço de e-mail.
- Se nenhum objectId for fornecido, a ocorrência do evento será associada a um contato existente que corresponda ao utk/email, ou HubSpot criará um contato se nenhuma correspondência for encontrada.
- Observe que o utk sozinho não pode criar novos contatos. Você deve sempre incluir email com utk para que associação seja adequada.
domain: para associações de empresa, você deve fornecer o objectId, mas você também pode incluir domain para atualizar a propriedade de domain daquela empresa.

Criar aplicativos

Adicionar recursos

Publicar no HubSpot Marketplace

Referência de eventos de aplicativo (BETA)

Estrutura do projeto

Esquema de tipo de evento

Propriedades do evento

Carimbos de propriedade

Renderização de modelos

Uso de iframes

Ocorrências de eventos

Associação de registro de CRM

​Estrutura do projeto

​Esquema de tipo de evento

​Propriedades do evento

​Carimbos de propriedade

​Renderização de modelos

​Uso de iframes

​Ocorrências de eventos

​Associação de registro de CRM

Estrutura do projeto

Esquema de tipo de evento

Propriedades do evento

Carimbos de propriedade

Renderização de modelos

Uso de iframes

Ocorrências de eventos

Associação de registro de CRM