Visão geral da API de código de rastreamento

Esta página foi atualizada para usar novos eventos comportamentais personalizados. Para eventos personalizados antigos, consulte a documentação antiga.

Além de rastrear as visualizações de página, o código de rastreamento do HubSpot permite identificar visitantes, rastrear eventos e rastrear manualmente visualizações de página sem recarregar a página. A API do código de rastreamento permite criar eventos e rastrear dados de eventos dinamicamente no HubSpot.

Se o seu site usa o banner de consentimento de privacidade, saiba como gerenciar os cookies adicionados ao navegador de um visitante com a API de banner de cookies.

As chamadas de função são enviadas para o array _hsq. Por exemplo:

var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', { path string }])

Neste artigo, saiba como adicionar funções ao código de rastreamento para identificar visitantes, rastrear visualizações de página, enviar dados de eventos e muito mais.

Identificação de contatos

A ferramenta de análise da HubSpot identifica os contatos usando dois segmentos de dados:

  • O usertoken, que é armazenado no cookie hubspotutk do navegador do visitante.
  • O endereço de e-mail do contato.

Quando o código de rastreamento do HubSpot rastrear a ação de um visitante, como uma exibição de página, ele associará automaticamente essa ação ao usertoken do visitante. Quando você usar a API de código de rastreamento para identificar um visitante por endereço de e-mail, o sistema de análise de dados vinculará esse e-mail ao usertoken, permitindo que a HubSpot atualize um registro de contato existente ou crie um novo. Os dados de análise associados ao usertoken, como exibições de página e fonte original, serão exibidos no registro do contato.

Quando você sabe a identidade de um visitante (por exemplo, endereço de e-mail), pode usar a função de identificação para definir identidades no rastreador. Você pode enviar a identidade para o HubSpot fazendo uma chamada separada de trackPageView ou trackCustomBehavioralEvent.

Lembre-se do seguinte ao usar essa função:

  • Evite usar um e-mail de espaço reservado para visitantes desconhecidos, pois o HubSpot criará um registro de contato com esse e-mail, e o cookie usertoken do visitante será associado a esse registro. Assim, todos os visitantes desconhecidos serão associados ao seu contato de espaço reservado.
  • Se você definir uma identidade para um registro de contato e tiver propriedades exclusivas, removeremos todas as propriedades da identidade que violem a exclusividade.

Identificar um visitante

Observação: se sua conta foi criada antes de 8 de setembro de 2021 e está configurada para permitir que propriedades de contato sejam atualizadas por meio do código de rastreamento, você também poderá incluir outras propriedades de contato a serem atualizadas com essa função. Essa funcionalidade está desativada para contas criadas após 8 de setembro de 2021.

_hsq.push(["identify", { {identity details} }]);

Use esse endpoint para identificar os visitantes e os contatos do site.

  • Visitor: refere-se a qualquer visitante do site, independentemente de ser ou não um contato no HubSpot. O HubSpot não cria registros para os visitantes como o faz para os contatos.
  • Contact: refere-se a um visitante ou contato offline que tem um registro no HubSpot. Um contato pode ser identificado pelo seu endereço de e-mail exclusivo.

Para identificar manualmente um visitante ou contato, você pode usar um endereço de e-mail ou um ID externo exclusivo:

  • email: identifique um visitante pelo endereço de e-mail quando você quiser atualizar um contato existente ou criar um novo. Se existir um contato com esse e-mail no HubSpot, o registro de contato será atualizado com os dados de análise. Se não existir nenhum contato com esse endereço de e-mail, um novo registro será criado.
  • id: um ID externo personalizado que identifica o visitante. A identificação de um visitante com este ID associará os dados de análise a esse visitante. No entanto, somente usar o ID não criará um contato no HubSpot. Os dados de análise somente podem ser associados a um contato existente por meio deste método quando:
    • o visitante foi previamente identificado pelo ID e pelo e-mail.
    • o visitante foi previamente identificado pelo ID e também possui um envio de formulário associado ao seu registro.

Observação: esse ID externo somente poderá ser usado com o código de rastreamento do HubSpot. Esse ID não pode ser usado para obter ou atualizar registros usando qualquer outra ferramenta ou API do HubSpot. Se você souber o endereço de e-mail do visitante, é recomendado usá-lo como identificador exclusivo. Da mesma forma, você somente deve identificar um visitante por ID quando não souber o endereço de e-mail dele.

Se você já enviou dados de análise para o HubSpot usando apenas o ID do visitante, poderá incluir posteriormente o ID e um endereço de e-mail para associar os dados desse ID a um contato. O contato existente será atualizado ou criado se não houver nenhum contato no momento.

/* The below example gets the value of a query string parameter '?email=' and uses that to identify the visitor */ function getParameterByName(name) { var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search); return match && decodeURIComponent(match[1].replace(/\+/g, ' ')); } var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email") }]); /* The below example sets the email, as well as a custom property favorite_color */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email"), favorite_color: 'orange' }]); /* The below example sets the email and a custom external ID for the visitor. This assumes that your site includes a variable named 'user' that includes that user's ID in an 'id' property, and their email in an 'email' property. */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: user.email, id: user.id }]);
Lembre-se das seguintes condições ao usar essa função:
  • Essa função armazena os dados no rastreador, mas os dados não são transmitidos de fato para o HubSpot com essa chamada. Os dados só serão transmitidos durante o rastreamento de uma exibição de página ou de um evento (com as funções trackPageView ou trackEvent).
  • Um contato somente pode ter um ID e/ou endereço de e-mail associado a ele. Se você tentar atribuir dois IDs a um e-mail, apenas o primeiro será associado ao endereço de e-mail.
  • Para vincular os dados a um contato, inclua um endereço de e-mail.
  • Se a sua conta foi criada antes de 8 de setembro de 2021 e está configurada para permitir que as propriedades de contato sejam atualizadas por meio do código de rastreamento, você também pode incluir outras propriedades de contato a serem atualizadas com esta função.
  • Esta função não restaurará contatos excluídos anteriormente. Esses contatos devem ser restaurados no HubSpot.

Rastreamento em aplicativos de página única

O código de rastreamento do HubSpot registrará automaticamente uma visualização de página quando o código for carregado pela primeira vez, mas você também pode rastrear manualmente visualizações de página em um aplicativo de página única sem recarregar o código de rastreamento. Você pode usar as funções setPath e trackPageView para atualizar e rastrear a página atual. Por exemplo:

<!-- Set up the path for the initial page view --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/home']); </script> <!-- Load the HubSpot tracking code --> <!-- Start of HubSpot Embed Code --> <script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/{hubId}.js"> </script> <!-- End of HubSpot Embed Code --> <!-- Tracking subsequent page views --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/about-us']); _hsq.push(['trackPageView']); </script>

Definir o caminho da página

hsq.push(['setPath', { path string }])

Atualizar o caminho da página atual armazenado no rastreador. Esta função deve ser usada pelos aplicativos de página única para atualizar a página atual sempre que uma página for carregada. Após usar essa função para atualizar o caminho, você precisará chamar a função trackPageView para rastrear a exibição da página atual.

Os aplicativos de página única devem enviar uma chamadasetPath para _hsq antes que o código de rastreamento seja carregado para definir a URL que será rastreada para a primeira exibição de página. Consulte a seção de exibição da página de rastreamento abaixo para ver um exemplo.

Ao chamar setPath, você incluirá o caminho da página atual. O caminho definido será tratado como relativo ao domínio atual que está sendo visualizado. O caminho sempre deve ser precedido de uma barra. Se o URL também contiver parâmetros, eles também deverão ser incluídos no caminho. Confira o código acima para ver exemplos.

Lembre-se das seguintes condições ao usar essa função:
  • Qualquer caminho definido usando a função setPath substituirá os dados no cabeçalho do referenciador. Se você chamar setPath uma vez, precisará usar setPath para atualizar o caminho de cada visualização que deseja rastrear.
  • Chamar setPath repetidamente substituirá o referenciador, o que pode afetar a fonte original do contato, dependendo de quando uma solicitação de rastreamento é feita. 
  • Esta função só pode atualizar o caminho da URL. O domínio é definido automaticamente com base na URL da página que está sendo carregada. O caminho definido usando essa função sempre é tratado como relativo a esse domínio detectado.
Example usage: // These examples assume that the domain of the site is // www.mydomain.com // Set the path to '/' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/ // Set the path to '/contact-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/contact-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/contact-us // Set the path to '/blog/post?utm_campaign=my-campaign' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/blog/post?utm_campaign=my-campaign']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/blog/post?utm_campaign=my-campaign // Set the path to '/#/about-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/about-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/#/about-us

Rastrear a visualização da página

_hsq.push(['trackPageView']);

Rastreie a exibição de página para a página atual. Esta função é chamada automaticamente quando o código de rastreamento é carregado em uma página, mas você pode chamar esta função manualmente para rastrear visualizações subsequentes em um aplicativo de página única.

Observação: chamar essa função manualmente antes ou durante o carregamento da página inicial pode fazer com que visualizações duplicadas sejam rastreadas.

Esta função não é compatível com argumentos. O título rastreado será o valor atual de document.title.

A URL rastreada baseia-se em um dos seguintes:

  • O caminho definido usando a função setPath. Se o site tiver sido criado como um aplicativo de página única, esta função será o método preferido para definir o caminho rastreado. Confira a seção setPath acima para ver as isenções de responsabilidade sobre a função.
  • Se a função setPath nunca tiver sido chamada, a URL rastreada será o cabeçalho do HTTP do referenciador na solicitação feita pelo navegador do visitante para os servidores de rastreamento da HubSpot. (A modificação do estado do histórico do navegador atualizará o valor usado para esse cabeçalho). O uso de cabeçalhos de referenciador não permitirá fragmentos de URL (qualquer elemento após # na URL), pois os fragmentos não são incluídos nesses cabeçalhos.
Example usage: // Track a new page using setPath: // Update the path stored in the tracker: var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/new-page']); // Track the page view for the new page _hsq.push(['trackPageView']); // Track a new page by updating the browser state: // Update the browser state, showing "updated.html" in the browser address bar var stateObj = { foo: 'updated' }; history.pushState(stateObj, "updated page", "updated.html"); //Track the page view for the new page, '/updated.html' var _hsq = window._hsq = window._hsq || []; _hsq.push(['trackPageView']);

Lembre-se das seguintes condições ao usar essa função:

  • Embora não seja possível impedir que essa função seja chamada automaticamente quando o código de rastreamento for carregado, você pode controlar a URL registrada para a página enviando uma chamada setPath para _hsq antes de o código de rastreamento ser carregado.
  • Se o site for um aplicativo de página única, evite incluir a tag <link rel="canonical"> em sua página. Se sua página usar tags <link rel="canonical">, você precisará usar a função setPath para atualizar o caminho das novas páginas, pois a URL canônica definida com base no link substituirá qualquer URL detectada se você estiver atualizando apenas o estado do histórico do navegador.

Política de privacidade no rastreamento

Se o seu site tiver um banner de consentimento de privacidade, você poderá usar funções para verificar e gerenciar os cookies adicionados ao navegador do visitante. Saiba mais sobre como gerenciar os cookies de banner de consentimento de privacidade.

Obter parâmetros de vinculação entre domínios

_hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) {}]) 

O código de rastreamento do HubSpot pode ser usado em vários sites com domínios separados. Como essa função, você pode obter os parâmetros de consulta obrigatórios para criar links que permitirão rastrear os visitantes nesses domínios separados. Esses parâmetros de consulta são usados pelo código de rastreamento do HubSpot para identificar um visitante entre os domínios, garantindo que os cookies separados para os domínios separados sejam mesclados para um único visitante rastreado. Você também pode usar parâmetros de consulta entre domínios em links que são adicionados dinamicamente à página depois que o código de rastreamento é carregado.

Os links entre domínios são necessários somente durante a vinculação a um domínio distinto (por exemplo, domain-one.com e domain-two.com) que também está sendo rastreado para uma única conta da HubSpot. Você não precisa de parâmetros de link entre domínios ao rastrear visitas entre subdomínios (por exemplo, www.domain-one.com e blog.domain-one.com). 

// Get the cross-domain query parameters and store them in a string, //so that they can be appended to links as needed. _hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) { // Add these query parameters to any links that point to a separate tracked domain crossDomainTrackingParams = '&__hstc=' + hstc + '&__hssc=' + hssc + '&__hsfp=' + hsfp; }]);

Reaplicar handlers de eventos de análise

_hsq.push(['refreshPageHandlers'])

Esta função reaplica quaisquer handlers de eventos de análise que estejam definidos nas configurações de análise da conta da HubSpot.

Isso incluirá a reaplicação de qualquer evento de elemento clicado que tenha sido configurado.

 Você pode usar esta função para reaplicar automaticamente handlers de clique quando o conteúdo na página for atualizado, como atualizar uma seção de conteúdo ou exibir uma janela modal na página.

Observação: essa funcionalidade é disparada automaticamente como parte da função setPath. Portanto, você só precisará usar essa função quando atualizar o conteúdo sem atualizar a URL da página rastreada.

// Reapply event handlers after updating the page content _hsq.push(['refreshPageHandlers']);

Rastreamento de eventos comportamentais personalizados (somente Marketing Hub Enterprise)

Usando eventos comportamentais personalizados, você pode vincular conclusões de eventos a registros de contato e preencher propriedades de evento com metadados sobre o evento. Para recuperar eventos comportamentais personalizados, use a API de análises da web.

Por meio da API, os eventos podem ser disparados usando seus nomes internos, que são atribuídos automaticamente quando você cria os eventos. Você pode encontrar o nome interno de um evento no HubSpot ou usando a API de eventos. Saiba como encontrar o nome interno de um evento. 

custom-event-internal-name

Há três tipos de eventos que você pode criar no HubSpot:

  • Eventos de elementos clicados: eventos vinculados a elementos clicáveis em uma página do site. Preencherá automaticamente um conjunto de propriedades de evento padrão da HubSpot por meio do código de rastreamento. Você pode personalizar ainda mais esses eventos com a função trackCustomBehavioralEvent.
  • Eventos de URL visitada: eventos vinculados a carregamentos de página em URLs específicas. Preencherá automaticamente um conjunto de propriedades de evento padrão da HubSpot por meio do código de rastreamento. Você pode personalizar ainda mais esses eventos com a função trackCustomBehavioralEvent.
  • Eventos comportamentais rastreados manualmente: eventos personalizados que são exclusivos da sua empresa, bem como eventos que podem não ser capturados automaticamente pelo HubSpot ou por uma integração. Envie dados manualmente para eventos do HubSpot por meio da API HTTP.

Para cada tipo de evento, o HubSpot inclui um conjunto de propriedades padrão que podem capturar certos metadados no momento da conclusão, incluindo parâmetros UTM ou metadados do dispositivo e do sistema operacional.

 Como essa função trabalha juntamente com o rastreamento de análises de dados do HubSpot, qualquer evento disparado por meio da API JavaScript será automaticamente associado ao cookie hubspotutk do visitante. Nesse caso, o evento será vinculado automaticamente ao contato associado a esse token do usuário.

trackCustomBehavioralEvent

_hsq.push(["trackCustomBehavioralEvent", { {event details} }]);

Use essa função para rastrear um evento usando o JavaScript e o código de rastreamento do HubSpot. Você pode usar eventos para rastrear atividades específicas realizadas pelos visitantes em seu site. Eventos rastreados podem aparecer nas linhas do tempo dos contatos.

/* Example code to fire a custom behavioral event using the name "clicked Buy Now button" when a visitor clicks an element with the 'buyNow' id. */ document.getElementById("buyNow").onclick = function() {_hsq.push(["trackCustomBehavioralEvent", { name: "pe123456_course_registration", properties: { course_id: "Math101" } }]);
Use this table to describe parameters / fields
ArgumentosComo usarDescrição
Name
name:"internal_name"

O event_id ou o nome interno do evento que você criou no HubSpot.

Properties
property_name: "property_value"

Uma lista de pares de chaves e valores, com um par de chave e valor por propriedade.

property_name é o nome interno da propriedade de evento que você criou para o evento e property_value é o valor a ser adicionado à propriedade. 

Você também pode rastrear propriedades não definidas e retornar para criá-las após o rastreamento de eventos.

Personalize o código de rastreamento para enviar dados de eventos comportamentais personalizados

Por padrão, o HubSpot cria um conjunto de propriedades para cada evento que você criar. Para eventos de elemento clicado ou URL visitada, o HubSpot preencherá automaticamente algumas dessas propriedades com dados. Porém, você também poderá personalizar o código de rastreamento para enviar dados para as propriedades do evento.

  • Na sua conta da HubSpot, acesse Relatórios > Ferramentas de análise.
  • Clique em Personalizar eventos comportamentais.
  • Clique no Nome do evento que você deseja rastrear.
  • Em Propriedades, copie o nome interno do evento.custom-clicked-element-event-internal-name0
  • Em seguida, na tabela de propriedades, clique no nome da propriedade de evento para qual você deseja enviar os dados.
  • No painel direito, clique no ícone de origem </> para visualizar o nome interno da propriedade. Você usará esse nome ao personalizar o código de rastreamento.
    custom-behavioral-event-property-internal-name0
  • Agora que você tem os dados do evento e da propriedade de evento, clique no ícone Configurações para acessar as configurações da conta. Em seguida, no menu da barra lateral esquerda, acesse Rastreamento e análises > Código de rastreamento.
  • Clique em Personalizar javascript.
    tracking-code-customize-javascript0
  • No canto superior direito, clique em Adicionar Javascript personalizado.
  • Na barra lateral direita, insira um nome para o JavaScript personalizado e insira o JavaScript, incluindo a função trackCustomBehavioralEvent. O JavaScript será executado após o código de rastreamento ser carregado em uma página.
// example usage _hsq.push(['trackCustomBehavioralEvent',{ name: '((behavioral_event_internal_name))”, properties: { internal_property_name: property_value} } ]);

Por exemplo, se seu evento rastreia o registro em um curso quando um botão com o ID HTML register_for_econ101 é clicado, seu JavaScript pode ter a seguinte aparência: customize-tracking-code0-1

  • Clique em Salvar para salvar o JavaScript. O código de rastreamento será carregado com o JavaScript personalizado.
Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..