Definir eventos personalizados

Requisitos de escopo

Os eventos personalizados permitem que você defina e rastreie eventos exclusivos da sua empresa, como eventos no seu site ou em um aplicativo. Você pode configurar eventos para armazenar informações nas propriedades, que podem ser usadas nas ferramentas do HubSpot. Para enviar dados de um evento personalizado para o HubSpot, primeiro você precisa definir o evento. Esse processo é semelhante aos objetos personalizados do CRM, onde você primeiro define o objeto personalizado e depois cria registros individuais para esse objeto. Uma definição de evento inclui detalhes como metadados, associações de objetos do CRM e propriedades. Abaixo, saiba mais sobre como criar e gerenciar definições de eventos usando a API. Para saber como criar definições de eventos sem usar a API, confira a Central de conhecimento da HubSpot.

Criar uma definição de evento

Para criar o esquema de evento personalizado, envie uma solicitação POST para events/v3/event-definitions. No corpo da solicitação, inclua as definições do seu esquema de evento, incluindo rótulo, nome, associações de objetos do CRM e propriedades personalizadas. O corpo da solicitação abaixo fornece um exemplo básico de uma definição de evento:

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}

Se quiser vincular automaticamente conclusões de eventos a registros de um tipo de Objeto do CRM especificado, você pode incluir um customMatchingId em seu pedido POST. Neste campo, defina um objeto primaryObjectRule com dois campos: a propriedade de objeto exclusiva que você configurou anteriormente como a targetObjectPropertyName e uma das propriedades definidas na propertyDefinitions da sua definição de evento. Por exemplo, o seguinte corpo de solicitação especifica um customMatchingId que corresponde a um nome de propriedade de Objeto do CRM de "unique_object_property" e o nome da propriedade de evento de "string_property":

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}

Uma lista completa dos parâmetros disponíveis para o corpo da solicitação é detalhada na tabela abaixo:

Parâmetro	Tipo	Descrição
`label`	String	O rótulo legível do evento que será exibido no HubSpot (até 100 caracteres). Rótulos longos podem ser cortados em certas partes da interface do HubSpot.
`name`	String	O nome interno exclusivo do evento que você usará para fazer referência ao evento por meio da API. Se nenhum valor for fornecido, a HubSpot gerará automaticamente um com base no rótulo. Esta propriedade não pode ser alterada após a criação da definição de evento. Esta propriedade pode conter apenas letras minúsculas, números, sublinhados e hifens (até 50 caracteres). O primeiro caractere deve ser uma letra.
`description`	String	A descrição do evento que será exibida no HubSpot.
`primaryObject`	String	O tipo de objeto do CRM ao qual os dados de evento serão associados. Conclusões de evento aparecerão nos registros de CRM daquele tipo de objeto. Pode ser um de: `"CONTACT"` (padrão), `"COMPANY"`, `"DEAL"`, `"TICKET"`, `"<CUSTOM_OBJECT_NAME>"`. Isso não poderá ser alterado depois que a definição do evento for criada.
`propertyDefinitions`	Matriz	Além das Propriedades do evento padrão HubSpot, você pode incluir essa matriz para definir as propriedades do evento personalizado (até 50). Para cada objeto de propriedade, inclua os seguintes campos: `name`: o nome interno da propriedade, que você usará ao enviar dados de evento por meio da API. `label`: o rótulo no aplicativo da propriedade. `type`: o tipo de propriedade. O padrão é `string`. `options`: para propriedades de tipo `enumeration`, esta matriz define os valores disponíveis. Deve incluir um `label` e `value` para cada opção. `description`: texto que descreve a propriedade.
`customMatchingId`	Objeto	Como uma alternativa para incluir as informações do objeto de destino `objectId` nos dados de conclusão do evento, esse campo opcional define uma regra para vincular automaticamente conclusões de evento a registros do tipo de objeto do CRM especificado. Isso é feito através da correspondência do valor de uma propriedade nos dados do evento com o valor de uma propriedade exclusiva no objeto alvo. Este objeto deve incluir um objeto `primaryObjectRule`, que por sua vez deve incluir dois campos: `targetObjectPropertyName`: uma cadeia de caracteres que especifica o nome da propriedade exclusiva no objeto do CRM de destino a ser usada para correspondência. `eventPropertyName`: uma cadeia de caracteres que especifica o nome da propriedade nos dados de evento personalizado a serem usados para correspondência.
`includeDefaultProperties`	Booleano	Um campo opcional que especifica se o evento deve incluir o conjunto de propriedades de evento padrão. Se nenhum valor for fornecido, este campo será automaticamente definido como `true`.

Propriedades do evento

As propriedades de evento personalizado são usadas para armazenar informações sobre conclusões de eventos personalizados individuais. Elas devem ser usadas quando apropriado para enviar conclusões de eventos, mas não são obrigatórias para que uma conclusão de evento seja válida. Para cada definição de evento, o HubSpot fornece um conjunto padrão de 32 propriedades. Além disso, você pode criar até 50 propriedades personalizadas por definição de evento. As propriedades podem ter os seguintes tipos:

bool: uma propriedade que recebe um valor booleano. Os valores devem ser representados como true ou false.
date: uma propriedade que recebe uma data que representa um dia, mês e ano específicos. Os valores devem ser representados na hora UTC e podem ser formatados como Strings ISO 8601 ou carimbos de data/hora EPOCH em milissegundos (ou seja, meia-noite UTC).
datetime: Uma propriedade que recebe valores de milissegundos de era ou ISO8601 que representam uma data/hora.
enumeration: Uma propriedade com opções predefinidas. Ao criar esse tipo de propriedade, inclua uma matriz options para definir os valores disponíveis.
number: propriedade que recebe valores numéricos com até uma casa decimal.
string: uma propriedade que recebe strings de texto simples. Se o nome da propriedade contiver as palavras url, referrer ou link, o valor da propriedade poderá ter até 1.024 caracteres. Caso contrário, poderá ter até 256 caracteres.

Abaixo, saiba mais sobre as propriedades de evento padrão do HubSpot, como definir novas propriedades para eventos existentes e como atualizar propriedades de eventos personalizados existentes.

Propriedades de evento padrão do HubSpot

hs_asset_description
hs_asset_type
hs_browser
hs_campaign_id
hs_city
hs_country
hs_device_name
hs_device_type
hs_element_class
hs_element_id
hs_element_text
hs_language
hs_link_href
hs_operating_system
hs_operating_version
hs_page_content_type
hs_page_id
hs_page_title
hs_page_url
hs_parent_module_id
hs_referrer
hs_region
hs_screen_height
hs_screen_width
hs_touchpoint_source
hs_tracking_name
hs_user_agent
hs_utm_campaign
hs_utm_content
hs_utm_medium
hs_utm_source
hs_utm_term

Definir novas propriedades

Para definir uma nova propriedade em um evento personalizado existente, envie uma solicitação POST para events/v3/event-definitions/{eventName}/property. No corpo da solicitação, inclua a definição da sua propriedade.

{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}

Ao nomear sua propriedade, tenha em mente o seguinte:

Depois de criar uma propriedade, o nome da propriedade não poderá ser alterado.
O nome somente pode conter letras minúsculas, números, sublinhados e hifens.
O primeiro caractere do nome da propriedade deve ser uma letra.
O nome e o rótulo da propriedade podem ter até 50 caracteres cada.
Se um nome de propriedade não for fornecido, um será gerado automaticamente com base no rótulo da propriedade.
Rótulos longos podem ser cortados em certas partes da interface do HubSpot.

Atualizar propriedades personalizadas existentes

Para atualizar uma propriedade existente em um evento personalizado, envie uma solicitação PATCH para events/v3/event-definitions/{eventName}/property. Os únicos campos que podem ser atualizados em uma propriedade são label, description e options para propriedades de enumeração.

Observação:

Para alterar o tipo de propriedade, utilize o ponto de extremidade DELETE para excluir a propriedade e recriá-la com o tipo correto.

Excluir uma propriedade

Para excluir uma propriedade existente em um evento personalizado, envie uma solicitação DELETE para events/v3/event-definitions/{eventName}/property/{propertyName}. Quando uma propriedade é excluída, ela não pode ser usada em conclusões de eventos futuros. Conclusões anteriores ainda terão os valores das propriedades.

Atualizar um evento

Para atualizar um esquema de evento personalizado existente, envie uma solicitação PATCH para events/v3/event-definitions/{eventName}. Os únicos campos de definição de evento que podem ser atualizados são label e description.

{
  "label": "Event label",
  "description": "A description of the event"
}

Excluir um evento

Para excluir um evento personalizado, envie uma solicitação DELETE para events/v3/event-definitions/{eventName}. A exclusão de um evento personalizado o removerá de qualquer outra ferramenta HubSpot que o faça referência, como fluxos de trabalho e relatórios.

Observe que ao excluir um evento:

Todos os eventos dessa definição de evento serão excluídos e não poderão ser recuperados.
eventNameS excluídos anteriormente não podem ser usados novamente, portanto tenha cuidado ao excluir um evento.

Obter definições de eventos existentes

Para buscar uma definição de evento único, envie uma solicitação GET para events/v3/event-definitions/{eventName}. Para pesquisar definições de eventos por critérios específicos, envie uma solicitação GET para events/v3/event-definitions. Você pode fornecer os seguintes parâmetros de consulta para refinar sua pesquisa:

searchString: pesquisa eventos que contenham os caracteres especificados no campo name. A pesquisa não é flexível, mas sim uma pesquisa simples de contém.
after: uma string com hash fornecida nas respostas paginadas para visualização da próxima página de resultados de pesquisa.
limit: o número máximo de resultados a serem retornados.
includeProperties: um valor booleano que especifica se as propriedades do evento devem ser incluídas nos resultados retornados.

​Criar uma definição de evento

​Propriedades do evento

​Propriedades de evento padrão do HubSpot

​Definir novas propriedades

​Atualizar propriedades personalizadas existentes

​Observação:

​Excluir uma propriedade

​Atualizar um evento

​Excluir um evento

​Observe que ao excluir um evento:

​Obter definições de eventos existentes

Criar uma definição de evento

Propriedades do evento

Propriedades de evento padrão do HubSpot

Definir novas propriedades

Atualizar propriedades personalizadas existentes

Observação:

Excluir uma propriedade

Atualizar um evento

Excluir um evento

Observe que ao excluir um evento:

Obter definições de eventos existentes