Produtos suportados
Marketing Hub -Enterprise Sales Hub -Enterprise Content Hub -Enterprise Service Hub -Enterprise Operations Hub -Enterprise
Eventos personalizados são eventos definidos por conta que armazenam detalhes de eventos em propriedades de eventos. Há três tipos de eventos personalizados que você pode criar no HubSpot:
- Elemento clicado e URL visitado são eventos personalizados que o código de rastreamento preenche automaticamente com dados. Você pode personalizar ainda mais esses eventos atualizando seu código de rastreamento com a função trackCustomEvent.
- Eventos rastreados manualmente são eventos personalizados exclusivos do seu negócio que não são capturados automaticamente pelo HubSpot ou por uma integração. Você pode enviar dados manualmente para esses eventos por meio dessa API.
Abaixo, saiba como criar um evento personalizado rastreado manualmente, enviar dados de evento por meio da API e usar dados de evento depois de capturados.
Para enviar dados de conclusão de evento para o HubSpot, primeiro você precisa definir o evento, incluindo seus metadados, associações de objetos do CRM e propriedades. Você pode definir eventos usando a API de definição de evento personalizado ou, se você tiver uma assinatura do Marketing Hub Enterprise, poderá criar o evento no HubSpot. Ao criar o evento, o HubSpot incluirá um conjunto de propriedades de evento padrão que você pode usar para armazenar os dados do evento. Você também pode criar propriedades adicionais para o evento. Essas propriedades podem ser criadas ou editadas a qualquer momento.
Depois de configurar o evento, você pode enviar dados para ele através da API.
Para enviar dados de evento ao HubSpot, faça uma solicitação POST
para https://api.hubspot.com/events/v3/send
com os dados do evento no corpo da solicitação. Antes de enviar dados de evento, revise os limites abaixo, pois exceder esses limites resultará em erro.
// POST to https://api.hubspot.com/events/v3/send
{
"eventName": "pe1234567_login_event",
"objectId": "608051",
"occurredAt": "2024-06-28T12:09:31Z",
"properties": {
"hs_city": "Cambridge",
"hs_country": "United States",
"hs_page_id": "53005768010",
"hs_page_content_type": "LANDING_PAGE",
"hs_touchpoint_source": "DIRECT_TRAFFIC"
}
}
Parâmetro | Tipo | Descrição |
---|---|---|
eventName Obrigatório | String | O nome interno do evento. Você pode encontrar isso consultando suas definições de evento existentes ou no aplicativo HubSpot. |
objectId Obrigatório | String | O ID do registro do CRM com o qual o evento será associado. Para contatos, você pode alternativamente usar o campo email ou utk para identificar o contato pelo endereço de e-mail ou pelo Token de Usuário da HubSpot. Todos os outros tipos de objetos exigem objectId . |
occurredAt | String | Por padrão, o HubSpot definirá a data/hora de conclusão do evento para a hora em que a solicitação foi enviada. Para especificar a hora de conclusão do evento, inclua um carimbo de data/hora em um campo occurredAt no corpo da solicitação POST (Formato ISO 8601). Isso pode ser especialmente útil para datar retroativamente dados de eventos para refletir com mais precisão a conclusão de eventos reais. |
properties | Objeto | As propriedades de evento às quais enviar dados. Isso pode incluir propriedades de evento padrão do HubSpot ou qualquer propriedades personalizadas você definiu para o evento. A maioria das propriedades de evento padrão são propriedades de string, mas você pode revisar todas as propriedades de evento consultando a definição do evento ou navegando até o evento no HubSpot. Saiba mais sobre propriedades de evento abaixo. |
Exceder qualquer um dos limites a seguir resultará em falha na solicitação:
- O rótulo da propriedade e o nome interno são limitados a 50 caracteres.
- Propriedades de URL e de referência podem ter até 1024 caracteres, enquanto todas as outras propriedades podem ter até 256 caracteres.
- Cada conclusão de evento pode conter dados para até 50 propriedades.
- Os nomes internos da propriedade devem começar com uma letra e conter apenas letras minúsculas de a-z, números de 0-9 e sublinhados.
- As propriedades com o mesmo nome interno após minúsculas serão consideradas duplicatas e apenas uma delas será usada na conclusão. O HubSpot classificará em ordem lexicográfica ascendente e manterá as últimas propriedades vistas entre as primeiras 50 propriedades.
- Há um limite de 500 definições de eventos exclusivos por conta.
- Há um limite de 30 milhões de finalizações de eventos por mês.
Para recuperar os dados de evento de um contato, faça uma solicitação GET
para/events/v3/events/eventType={EVENT_NAME}&objectType=contact&objectId={CONTACT_ID}
.
A solicitação acima inclui:
- eventType: o nome interno do evento.
- objectType: o tipo de objeto do registro.
- objectId: o ID de contato
Os dados de eventos são armazenados em propriedades, seja no conjunto de propriedades de evento padrão ou propriedades definidas pelo cliente. Ao enviar dados de eventos, você poderá atualizar as propriedades incluindo-as em um objeto properties
.
xxxxxxxxxx
"properties": {
"property1": "string",
"property2": "string",
"property3": "string"
}
Os valores que você envia dependerão do tipo de propriedade de evento. A maioria das propriedades de evento padrão é texto de linha única (string). Entretanto, você pode criar propriedades personalizadas de qualquer tipo para cada evento. Revise a tabela abaixo ao formatar os valores de propriedade.
Propriedade Tipo | Descrição |
---|---|
enumeration | Uma string que representa um conjunto de opções. Ao enviar vários valores, separe-os com um ponto e vírgula. No HubSpot, esse tipo corresponde a propriedades de seleção suspensa, botão de opções e várias caixas de seleção. |
date | Data/hora na forma de milissegundos de época ou ISO8601. No HubSpot, este tipo corresponde a propriedades de seletor de data. |
string | Uma string de texto simples, com no máximo 65.536 caracteres. No HubSpot, esse tipo corresponde a propriedades de texto de linha única e de várias linhas. |
number | Um valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. No HubSpot, este tipo corresponde às propriedades de número e cálculo. |
Para exibir as propriedades disponíveis de um evento:
- Na sua conta da HubSpot, navegue até Relatórios > Gerenciamento de dados > Eventos personalizados.
- Clique no nome do evento.
- Clique na guia Propriedades.
- Na tabela de propriedades, veja o tipo sob o nome da propriedade.
Eventos JavaScript, como elemento clicado e URL visitada, são preenchidos automaticamente com o tipo de ativo e os dados de interação para os relatórios de atribuição. Para incluir os mesmos dados para eventos rastreados manualmente, você precisará incluir manualmente os dados no corpo da solicitação usando as propriedades do evento. Saiba mais sobre análises de eventos personalizados.
Abaixo, conheça os valores disponíveis para tipos de ativos e origens de interação, juntamente com solicitações de exemplo.
Para atribuir um tipo de ativo específico a uma solicitação de evento comportamental personalizado, inclua a propriedade hs_page_content_type
no corpo da solicitação. Por exemplo:
xxxxxxxxxx
// example request body
{
"eventName": "pe1234567_manually_tracked_event",
"properties": {
"hs_page_id": "53005768010",
"hs_page_content_type": "LANDING_PAGE"
},
"objectId": "6091051"
}
Você também pode usar a propriedade hs_asset_type. Se ambos hs_page_content_type e hs_asset_type estiverem incluídos em uma única solicitação, hs_page_content_type substituirá o valor hs_asset_type.
Os tipos de conteúdo padrão do HubSpot, como landing pages e posts de blog, podem ser representados com os seguintes valores:
Valor | Descrição |
---|---|
STANDARD_PAGE | Uma interação com uma página do site. |
LANDING_PAGE | Uma interação com uma landing page. |
BLOG_POST | Uma interação com um post de blog. |
KNOWLEDGE_ARTICLE | Uma interação com um artigo da central de conhecimento. |
Para todos os outros tipos de ativos, use os seguintes valores:
Valor | Descrição |
---|---|
AD | Uma interação com um anúncio, como um anúncio do Facebook ou do Google. |
CALL | Uma interação com uma chamada. |
CONTACT_IMPORT | Uma interação através de uma importação de contato. |
CONVERSATION | Uma interação relacionada a uma conversa HubSpot. |
CUSTOM_BEHAVIORAL_EVENT_NAME | O nome interno de um evento personalizado, comope123456_manually_tracked_event . |
EMAIL | Uma interação com um e-mail. |
EXTERNAL_PAGE | Uma interação com uma página externa. |
INTEGRATIONS | Uma interação via integração. |
MARKETING_EVENT | Uma interação com um evento de marketing . |
MEDIA_BRIDGE | Uma interação via media bridge. |
MEETING | Uma interação com uma reunião. |
SALES_EMAIL | Uma interação com um e-mail de vendas individual. |
SEQUENCE | Uma interação com uma sequência. |
SOCIAL_POST | Uma interação com um post de mídia social. |
OTHER | Uma interação com um ativo que não está em uma das categorias acima. |
Para atribuir um evento personalizado a um ativo, inclua a propriedade hs_page_title
ou hs_asset_title
em sua solicitação com o nome do ativo formatado como uma string. Por exemplo:
hs_page_title:
xxxxxxxxxx
// example request body
{
"eventName": "pe1234567_manually_tracked_event",
"properties": {
"hs_page_title": "Sweepstakes Sign Up",
"hs_page_content_type": "LANDING_PAGE"
},
"objectId": "6091051"
}
Para atribuir um evento comportamental personalizado a uma fonte específica, inclua a propriedade hs_touchpoint_source
em sua solicitação com um dos seguintes valores:
Valor | Descrição |
---|---|
CONVERSATION | A fonte da interação é uma conversa. |
DIRECT_TRAFFIC | A fonte da interação é tráfego direto. |
EMAIL_MARKETING | A fonte da interação é um e-mail de marketing. |
HUBSPOT_CRM | A fonte da interação é o CRM da HubSpot. |
INTEGRATION | A fonte da interação é uma integração. |
MARKETING_EVENT | A fonte da interação é um evento de marketing. |
OFFLINE | A fonte da interação é offline. |
ORGANIC_SEARCH | A fonte de interação é a busca orgânica. |
OTHER_CAMPAIGNS | A fonte da interação é uma campanha não categorizada. |
PAID_SEARCH | A fonte da interação é um anúncio de pesquisa pago. |
PAID_SOCIAL | A fonte da interação é um anúncio de redes sociais pago. |
REFERRALS | A fonte da interação é uma referência. |
SALES | A fonte da interação é vendas. |
SOCIAL_MEDIA | A fonte da interação é mídias sociais (não um anúncio de redes sociais pago). |