> ## Documentation Index
> Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência de eventos de aplicativo (BETA)
> Informações de referência para eventos de aplicativo na versão mais recente da plataforma de desenvolvedor.
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`).
```shell theme={null}
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](/apps/developer-platform/build-apps/app-configuration).
* 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.
```json theme={null}
{
"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](#rendering-templates) 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](#rendering-templates) 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.
```json theme={null}
"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.
```json theme={null}
"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](https://www.markdownguide.org/basic-syntax/) com modelos de [Handlebars](https://handlebarsjs.com/guide/). 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](#event-occurrences).
```json theme={null}
"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](https://handlebarsjs.com/guide/builtin-helpers.html#if) 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.`.
```json theme={null}
"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.
```json theme={null}
"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.
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname).
```json theme={null}
{
"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](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) 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](#crm-record-association). |
| `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](#crm-record-association). |
| `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](#crm-record-association). |
| `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](#crm-record-association). |
| `timestamp` | String | Define a hora da ocorrência do evento (formato [ISO 8601](https://en.wikipedia.org/wiki/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](/apps/developer-platform/add-features/app-events/reference#event-properties) 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](#rendering-templates). |
| `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](#using-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.
### 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.