Resumen de la API de código de seguimiento

Esta página se ha actualizado para trabajar con nuevos eventos de comportamiento personalizados. Para eventos personalizados preexistentes, consulta la documentación preexistente.

Además de hacer seguimiento a las vistas de página, el código de seguimiento de HubSpot te permite identificar visitantes, hacer seguimiento a eventos y hacer seguimiento manualmente a las vistas de página sin volver a cargar la página. La API de código de seguimiento te permite crear eventos dinámicamente y hacer seguimiento a los datos de eventos en HubSpot.

Si tu sitio usa el banner de consentimiento de privacidad, obtén información sobre cómo administrar las cookies que se agregan al navegador de un visitante con la API del banner de cookies.

Las llamadas de función se introducen en la matriz _hsq: Por ejemplo:

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

En este artículo, obtén información sobre cómo puedes agregar funciones al código de seguimiento para identificar a los visitantes, realizar un seguimiento de las vistas de página, enviar datos de eventos y más.

Identificación de contactos

La herramienta de analíticas de HubSpot identifica los contactos usando dos datos:

  • El usertoken, que se almacena en la cookie del navegador hubspotutk del visitante.
  • La dirección de email registro del contacto.

Cuando el código de seguimiento de HubSpot hace seguimiento a una acción de un visitante, se asocia automáticamente esa acción con el usertoken del visitante. Cuando usas la API de código de seguimiento para identificar a un visitante por la dirección de correo electrónico, el sistema de analíticas vinculará ese correo electrónico con el valor  usertoken, lo que permite a HubSpot actualizar un registro de contacto existente o crear uno nuevo. Los datos de analíticas asociados con el usertoken, como las vistas de página y la fuente original, aparecerán en el registro de contacto.

Cuando conoces la identidad de un visitante (por ejemplo, la dirección de correo electrónico), puedes usar la función de identificación para establecer identidades en el rastreador. Luego puedes enviar la identidad a HubSpot haciendo una llamada separada a trackPageView o trackCustomBehavioralEvent.

Cuando uses esta función, recuerda:

  • Evita usar un correo marcador de posición de correo para visitantes desconocidos, ya que HubSpot creará un registro de contacto con ese correo marcador de posición y la cookie usertoken del visitante se asociará con ese registro. Esto lleva a que todos los visitantes desconocidos se asocien con tu contacto de marcador de posición.
  • Si estableces una identidad en un registro de contacto y tiene alguna propiedad que sea única, eliminaremos cualquier propiedad de la identidad que viole la unicidad.

Identificar a un visitante

Nota: si tu cuenta se creó antes del 8 de septiembre de 2021 y está configurada para permitir que las propiedades de contacto se actualicen a través del código de seguimiento, también puedes incluir otras propiedades de contacto que se actualizarán con esta función. Para las cuentas creadas después del 8 de septiembre de 2021, esta funcionalidad no está en uso.

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

Usa este punto de terminación para identificar a los visitantes y contactos del sitio web.

  • Visitante: se refiere a cualquier visitante del sitio web, independientemente de si es un contacto de HubSpot. HubSpot no crea registros para los visitantes como lo hace para los contactos.
  • Contacto: se refiere a un visitante o contacto fuera de línea que tiene un registro en HubSpot. Un contacto puede identificarse por su dirección de correo electrónico única.

Para identificar manualmente a un visitante o contacto, puedes usar una dirección de correo electrónico o un ID externo único:

  • correo electrónico: identifica a un visitante por dirección de correo electrónico cuando desees actualizar un contacto existente o crear uno nuevo. Si existe un contacto con ese correo electrónico en HubSpot, su registro de contacto se actualizará con los datos de analíticas. Si no existe ningún contacto en esa dirección de correo electrónico, se creará un nuevo registro.
  • id: un ID externo personalizado que identifica al visitante. Identificar a un visitante con este ID asociará los datos de analíticas a ese visitante. Sin embargo, usar el ID solo no creará un contacto en HubSpot. Los datos de analíticas solo se pueden asociar con un contacto existente a través de este método cuando:
    • el visitante fue identificado previamente tanto por ID como por correo electrónico.
    • el visitante fue identificado previamente por ID y también tiene un envío de formulario asociado con su registro.

Nota: este ID externo solo se puede usar con el código de seguimiento de HubSpot. Este ID no se puede usar para recuperar o actualizar cualquier registro a través de cualquier otra herramienta o API de HubSpot. Si conoces la dirección de correo electrónico del visitante, se recomienda usarla como identificador único. Del mismo modo, solo debes identificar a un visitante por ID cuando no conozcas su dirección de correo electrónico.

Si has enviado previamente datos de analíticas a HubSpot utilizando solo el ID del visitante, puedes incluir más tarde tanto el ID como una dirección de correo electrónico para asociar los datos de ese ID con un contacto. El contacto existente se actualizará o creará si no existe ningún contacto actualmente.

/* 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 }]);
Al usar esta función, ten en cuenta lo siguiente:
  • Esta función almacena los datos en el rastreador, pero en realidad, los datos no se pasan a HubSpot con esta llamada. Los datos solo se pasarán cuando se realice un seguimiento de una visita de página o un evento (con las funciones trackPageView o trackEvent).
  • Un contacto solo puede tener una identificación y/o dirección de correo electrónico asociada con ellos. Si intentas asignar dos ID a un correo electrónico, solo se asociará el primer ID con la dirección de correo electrónico.
  • Debes incluir una dirección de correo electrónico para vincular los datos a un contacto.
  • Si tu cuenta se creó antes del 8 de septiembre de 2021 y está configurada para permitir que las propiedades de contacto se actualicen a través del código de seguimiento, también puedes incluir otras propiedades de contacto que se actualizarán con esta función.
  • Esta función no restaurará contactos eliminados previamente. Estos contactos deben restaurarse en HubSpot.

Seguimiento en aplicaciones single-page

El código de seguimiento de HubSpot registrará automáticamente una vista de página cuando el código se carga por primera vez, pero también puedes hacer seguimiento manualmente de las vistas de página en una aplicación single-page sin volver a cargar el código de seguimiento. Puedes usar las funciones setPath y trackPageView para actualizar y hacer seguimiento a la página actual: Por ejemplo:

<!-- 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>

Establecer ruta de página

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

Actualizar la ruta de la página actual almacenada en el rastreador. Esta función debe usarse en aplicaciones single-page para actualizar la página actual cuando se carga una página. Después de usar esta función para actualizar la ruta, deberás llamar a la  función trackPageView para hacer seguimiento a la vista de la página actual.

Las aplicaciones single-page deben mover una llamada setPath a _hsq antes de que se cargue el código de seguimiento para establecer la URL a la que se hace seguimiento durante la primera vista de página. Consulta la sección de vista de página de seguimiento a continuación para obtener un ejemplo.

Cuando llames a setPath, incluirás la ruta de la página actual. La ruta establecida será tratada como relativa al dominio que se está viendo actualmente. La ruta siempre debe comenzar con una barra diagonal. Si tu URL también contiene parámetros, estos deben incluirse en la ruta. Ve el código anterior para ejemplos.

Al usar esta función, ten en cuenta lo siguiente:
  • Cualquier ruta establecida usando la función setPath anulará los datos en el encabezado del referente. Si llamas a setPath una vez, tendrás que usar setPath para actualizar la ruta para cada vista que deseas hacer seguimiento.
  • Las llamadas repetidas a setPath anularán al remitente, lo que puede afectar a la fuente original de un contacto, dependiendo de cuándo se realice una solicitud de seguimiento. 
  • Esta función solo puede actualizar la ruta de la URL. El dominio se establece automáticamente según la URL de la página de carga y la ruta que se establece usando esta función siempre se trata como relativa a ese dominio 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

Seguimiento de vista de página

_hsq.push(['trackPageView']);

Haz un seguimiento de la vista de página para la página actual. Esta función se llama cuando el código de seguimiento se carga en una página, pero puedes llamar manualmente a esta función para hacer seguimiento de las vistas subsiguientes en una aplicación de una página.

Nota: llamar a esta función manualmente antes de o durante la carga de la página inicial podría conducir a hacer seguimiento de vistas duplicadas.

Esta función no admite ningún argumento. El título de la página al que se hace seguimiento será el valor actual de document.title

La URL que se rastrea se basa en uno de los siguientes elementos:

  • La ruta establecida usando la función setPath. Si el sitio es creado como una aplicación single-page, esta función es el método preferido para configurar la ruta a la que se hace seguimiento. Consulta la sección setPath arriba para descargos de responsabilidad sobre la función.
  • Si setPath no se ha llamado nunca, la URL con seguimiento será el encabezado HTTP del referente en la solicitud que el navegador del visitante debe hacer en los servidores de seguimiento de HubSpot (modificar el estado del historial del navegador actualizaría el valor utilizado para ese encabezado). El encabezado del referente no se admitirán los fragmentos de URL (cualquier cosa después del #en la URL), ya que los fragmentos no están incluidos en el encabezado del referente.
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']);

Ten en cuenta lo siguiente cuando uses esta configuración:

  • Si bien no puedes evitar que esta función se llame automáticamente cuando se cargue el código de seguimiento, puedes controlar la URL grabada para la página moviendo una llamada a setPath a _hsq antes de que se cargue el código de seguimiento.
  • Si tu sitio es una aplicación single-page, debes evitar incluir una etiqueta <link rel="canonical"> en tu página. Si tu página usa etiquetas <link rel="canonical">, deberás usar la función setPath para actualizar la ruta de tus nuevas páginas, ya que la URL canónica establecida en la etiqueta de enlace anulará cualquier URL detectada si solo estás actualizando el estado del historial del navegador.

Política de privacidad en el seguimiento

Si tu sitio tiene un banner de consentimiento de privacidad, puedes usar funciones para verificar y administrar las cookies colocadas en el navegador del visitante. Más información sobre cómo administrar cookies de banner de consentimiento de privacidad.

Obtener parámetros de enlace entre dominios

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

El código de seguimiento de HubSpot se puede usar en varios sitios con dominios separados. Esta función te permitirá obtener los parámetros de consulta necesarios para crear enlaces que te permitirán hacer seguimiento a tus visitantes en esos dominios separados. Estos parámetros de consulta utilizan el código de seguimiento de HubSpot para identificar a un visitante en varios dominios, garantizando que las cookies separadas para los dominios separados se combinen para un solo visitante con seguimiento. También puedes usar parámetros de consulta entre dominios en enlaces que se agregan dinámicamente a la página después de que se cargue el código de seguimiento.

Los enlaces entre dominios solo son necesarios para enlazar a un dominio distinto (por ejemplo, dominio-uno.com y dominio-dos.com) al que también se le está siendo haciendo seguimiento en una única cuenta de HubSpot. No necesitas parámetros de enlace entre dominios al realizar un seguimiento de las visitas entre subdominios (por ejemplo, www.dominio-uno.com y blog.dominio-uno.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; }]);

Aplicar otra vez los manejadores de eventos de analíticas

_hsq.push(['refreshPageHandlers'])

Esta función aplica nuevamente los manejadores de eventos de analíticas que se configuraron en la configuración de analíticas para la cuenta de HubSpot.

Esto incluiría la aplicación de cualquier evento de elemento seleccionado que se haya configurado.

 Puedes usar esta función para volver a aplicar automáticamente los manejadores de clics cuando se actualiza el contenido de la página, como actualizar una sección de contenido o mostrar una ventana modal en la página.

Nota: esta funcionalidad se activa automáticamente como parte de la función setPath , por lo que solo tendrás que usar esta función al actualizar el contenido sin actualizar la URL de la página a la que se hace seguimiento.

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

Seguimiento de eventos de comportamiento personalizados (Marketing Hub Enterprise únicamente)

Usando eventos personalizados de comportamiento, puedes vincular las terminaciones de eventos a los registros de contactos y rellenar las propiedades del evento con metadatos sobre el evento. Para recuperar eventos de comportamiento personalizados, usa la API de analíticas web.

A través de la API, los eventos se pueden activar utilizando el nombre interno del evento, que se asigna automáticamente cuando se crea el evento. Puedes encontrar el nombre interno de un evento en HubSpot o usando la API de eventos. Descubre cómo encontrar el nombre interno de un evento. 

custom-event-internal-name

Puedes crear tres tipos de eventos en HubSpot.

  • Eventos de elementos con clics: eventos vinculados a elementos en los que se puede hacer clic en una página de sitio web. Se rellenará automáticamente un conjunto de propiedades de evento de HubSpot predeterminadas a través del código de seguimiento. Puedes personalizar más estos eventos con la función trackCustomBehavioralEvent.
  • Eventos de URL visitada: eventos vinculados a cargas de página en URL específicas. Se rellenará automáticamente un conjunto de propiedades de evento de HubSpot predeterminadas a través del código de seguimiento. Puedes personalizar más estos eventos con la función trackCustomBehavioralEvent.
  • Eventos de comportamiento con seguimiento manual: eventos personalizados que son exclusivos de tu empresa, además de eventos que HubSpot o una integración pueden no capturar automáticamente. Envía datos manualmente a eventos de HubSpot a través de la API HTTP.

Para cada tipo de evento, HubSpot incluye un conjunto de propiedades estándar que pueden capturar ciertos metadatos en el momento de la finalización, incluidos los parámetros UTM o los metadatos del dispositivo y del sistema operativo.

 Dado que esta función trabaja en conjunto con el seguimiento de analíticas de HubSpot, cualquier evento que se desencadene a través de la API de JavaScript se asociará automáticamente con la cookie de hubspotutk del visitante, por lo que el evento se vincularía automáticamente al contacto asociado con esa ficha de usuario.

trackCustomBehavioralEvent

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

Usa esta función para hacer seguimiento a un evento usando el código de seguimiento de JavaScript y HubSpot. Puedes usar eventos para hacer seguimiento a actividades específicas completadas por visitantes en tu sitio. Los eventos con seguimiento pueden aparecer en las cronologías de los contactos.

/* 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
ArgumentosCómo utilizarloDescripción
Name
name:"internal_name"

El event_id o el nombre interno del evento que creaste en HubSpot.

Properties
property_name: "property_value"

Una lista de pares clave-valor, con un par clave-valor por propiedad.

property_name es el nombre interno de la propiedad del evento que has creado para el evento, y property_value es el valor que se agregará a la propiedad. 

También puedes hacer seguimiento a las propiedades no definidas y volver a crearlas después del seguimiento de eventos.

Personaliza tu código de seguimiento para enviar datos de eventos de comportamiento personalizados

Por opción predeterminada, HubSpot crea un conjunto de propiedades para cada evento que crees. Para los eventos de elementos con clics o URL visitada, HubSpot rellenará automáticamente algunas de esas propiedades con datos. Pero también puedes personalizar tu código de seguimiento para enviar datos a las propiedades del evento.

  • En tu cuenta de HubSpot, navega a Informes > Herramientas de Analíticas.
  • Haz clic en Eventos de comportamiento personalizados.
  • Haz clic en el nombre del evento al que que deseas hacerle seguimiento.
  • En Propiedades, copia el nombre interno del evento.custom-clicked-element-event-internal-name0
  • Luego, en la tabla de propiedades, haz clic en el nombre de la propiedad del evento a la que deseas enviar datos.
  • En el panel derecho, haz clic en el ícono de origen </> para ver el nombre interno de la propiedad. Usarás este nombre al personalizar el código de seguimiento.
    custom-behavioral-event-property-internal-name0
  • Ahora que tienes los datos de tu evento y de la propiedad del evento, haz clic en el icono Configuración para navegar a la configuración de tu cuenta. En el menú de la barra lateral izquierda, navega a Seguimiento y analíticas > Código de seguimiento.
  • Haz clic en Personalizar javascript.
    tracking-code-customize-javascript0
  • En la parte superior derecha, haz clic en Agregar JavaScript personalizado.
  • En la barra lateral derecha, escribe un nombre para tu Javascript personalizado y luego escribe el Javascript, incluyendo la función trackCustomBehavioralEvent. Este JavaScript se ejecutará después de que se cargue el código de seguimiento de una página.
// example usage _hsq.push(['trackCustomBehavioralEvent',{ name: '((behavioral_event_internal_name))”, properties: { internal_property_name: property_value} } ]);

Por ejemplo, si tu evento hace seguimiento de un registro de curso cuando se hace clic en un botón con el ID de HTML register_for_econ101, tu JavaScript podría tener el siguiente aspecto: customize-tracking-code0-1

  • Haz clic en Guardar para guardar tu JavaScript. Tu código de seguimiento ahora se cargará con tu JavaScript personalizado.
¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.