Skip to main content

In addition to tracking page views, the HubSpot tracking code allows you to identify visitors, track events, and manually track page views without reloading the page. The tracking code API allows you to dynamically create events and track event data in HubSpot.

If your site uses the cookie consent banner, learn how to manage the cookies that are added to a visitor's browser with the cookie banner API.

Function calls are pushed into the _hsq array. For example:

In this article, learn about how you can add functions to the tracking code to identify visitors, track page views, send event data, and more.

The HubSpot analytics tool identifies contacts using two pieces of data:

  • The usertoken, which is stored in the visitor's hubspotutk browser cookie.
  • The contact's email address.

When the HubSpot tracking code tracks a visitor's action, such as a page view, it automatically associates that action with the visitor's usertoken. When you use the tracking code API to identify a visitor by email address, the analytics system will tie that email to the usertoken, allowing HubSpot to update an existing contact record or create a new one. Analytics data associated with the usertoken, such as page views and original source, will then appear on the contact record.

When you know a visitor's identity (e.g., email address), you can use the identify function to set identities in the tracker. You can then send the identity to HubSpot by making a separate trackPageView or trackCustomBehavioralEvent call.

When using this function keep in mind:

  • Avoid using a placeholder email for unknown visitors, as HubSpot will create a contact record with that placeholder email, and the visitor's usertoken cookie will be associated with that record. This leads to all unknown visitors being associated with your placeholder contact.
  • If you set an identity to a contact record and have any properties that are unique, we will drop any properties from the identity that violate uniqueness.

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

Use this endpoint to identify website visitors and contacts.

  • Visitor: refers to any website visitor, regardless of whether they’re a HubSpot contact. HubSpot does not create records for visitors like it does for contacts.
  • Contact: refers to a visitor or offline contact that has a record in HubSpot. A contact can be identified by its unique email address.

To manually identify a visitor or contact, you can use either an email address or unique external ID:

  • email: identify a visitor by email address when you want to update an existing contact or create a new one. If a contact with that email exists in HubSpot, their contact record will update with the analytics data. If no contact exists at that email address, a new record will be created.
  • id: a custom external ID that identifies the visitor. Identifying a visitor with this ID will associate analytics data to that visitor. However, using the ID alone will not create a contact in HubSpot. Analytics data can only be associated with an existing contact through this method when:
    • the visitor was previously identified by both ID and email.
    • the visitor was previously identified by ID and also has a form submission associated with their record.

When using this function, keep the following in mind:

  • This function call stores the data in the tracker, but the data is not actually passed to HubSpot with this call. The data will only be passed when tracking a page view or an event (with either the trackPageView or trackEvent functions).
  • A contact can only have one ID and/or email address associated with them. If you try to assign two IDs to one email, only the first ID will be associated with the email address.
  • You must include an email address to tie the data to a contact.
  • If your account was created before September 8, 2021 and is set up to allow contact properties to be updated through the tracking code, you can also include other contact properties to be updated with this function.
  • This function will not restore previously deleted contacts. These contacts must be restored in HubSpot. When restored, the cookie association won't be linked to the new contact record.

The HubSpot tracking code will automatically record a page view when the code is first loaded, but you can also manually track page views in a single-page application without reloading the tracking code. You can use the setPath and trackPageView functions to update and track the current page. For example:

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

Update the path of the current page stored in the tracker. This function should be used by single-page applications to update the current page whenever a page is loaded. After using this function to update the path, you'll need to call the trackPageView function to track the view of the current page.

Single-page applications should push a setPath call into _hsq before the tracking code loads to set the URL that gets tracked for the first page view. See the track page view section below for an example.

When calling setPath, you'll include the path of the current page. The set path will be treated as relative to the current domain being viewed. The path should always start with a slash. If your URL also contains parameters, these will need to be included in the path as well. View the above code for examples.

_hsq.push(['trackPageView']);

Track the page view for the current page. This function is automatically called when the tracking code is loaded on a page, but you can manually call this function to track subsequent views in a single page application.

This function does not support any arguments. The page title tracked will be the current value of document.title.

The URL that gets tracked is based on one of the following:

  • The path set using the setPath function. If your site is built as a single-page application, this function is the preferred method of setting the tracked path. View the setPath section above for disclaimers about the function.
  • If setPath has never been called, the tracked URL will be the referrer HTTP header in the request being made by the visitor's browser to HubSpot's tracking servers (modifying the browser history state would update the value used for that header). The referrer header will not support URL fragments (anything after the # in the URL), as fragments are not included in the referrer header.

When using this function, keep in mind the following:

  • While you can't prevent this function from being automatically called when the tracking code loads, you can control the URL recorded for the page by pushing a setPath call into _hsq before the tracking code is loaded.
  • If your site is a single-page application, you should avoid including a <link rel="canonical"> tag in your page. If your page uses <link rel="canonical"> tags, you'll need to use the setPath function to update the path of your new pages, as the canonical URL set from the link tag will override any detected URL if you're only updating the browser history state.

If your site has a cookie consent banner you can manage cookies placed into your visitor's browser. Learn more about managing cookies.

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

The HubSpot tracking code can be used across multiple sites with separate domains. This function will allow you to get the query parameters required to create links that will allow you to track your visitors across those separate domains. These query parameters are used by the HubSpot tracking code to identify a visitor across domains by ensuring that the separate cookies for the separate domains are merged to a single tracked visitor. You can also use cross-domain query parameters in links that are dynamically added to the page after the tracking code is loaded.

Cross-domain links are only needed when linking to a distinct domain (e.g., domain-one.com and domain-two.com) that is also being tracked for a single HubSpot account. You do not need cross-domain link parameters when tracking visits between subdomains (e.g., www.domain-one.com and blog.domain-one.com).

_hsq.push(['refreshPageHandlers'])

This function reapplies any analytics event handlers that are set up in the analytics settings for the HubSpot account.

This would include reapplying any clicked element events that have been set up.

You can use this function to automatically reapply click handlers when content on the page is updated, such as updating a section of content or displaying a modal window on the page.

If you have an Enterprise subscription, you can create custom events to track visitor interactions on your website through the tracking code. For example, you can create a custom JavaScript event that listens for a button click, then sends event data to HubSpot based on the visitor and interaction.

Once the event is created, you can use the trackCustomBehavioralEvent function to send event data to custom JavaScript events and custom behavioral events.

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

Use this function to send custom event data via the tracking code. For example, the code below would trigger a custom behavioral event with the internal name pe123456_course_registration when a visitor clicks an element with the signUp ID.

FieldTypeDescription
nameStringThe internal name of the event that you created in HubSpot (e.g., pe123456_my_event_name). You can retrieve an event's internal name either via the custom event definitions API or in HubSpot's UI, as shown below.
propertiesObjectA list of key-value pairs, with one key-value pair per property. You can retrieve an event's property names via the custom event definitions API or in HubSpot's UI, as shown below.

Because the function is handled by the tracking code, event completions will automatically be associated with the visitor's corresponding contact record via their usertoken cookie.

To find the internal event name and property names:

  • In your HubSpot account, navigate to Data Management > Custom Events.
  • Click the name of the event that you want to track.
  • At the top, under the event title, you can copy the Internal name for targeting the event in your JavaScript code.

internal-event-name

  • Click the Property info tab, then view the Internal Name column to retrieve the values needed for updating event properties in your JavaScript code.
  • You can also edit the event's JavaScript code and manage its properties by clicking Edit event in the upper right.

edit-javascript-event

When creating a JavaScript event in HubSpot, HubSpot will provide a code snippet that you can customize and add to your tracking code without needing to navigate into your account settings.

default-code-in-event-creation-wizard

You can also customize your tracking code manually in your account settings:

  • In your HubSpot account, click the settings icon in the top navigation bar.
  • In the left sidebar menu, navigate to Tracking & Analytics > Tracking Code.
  • Under the Embed code section, click Customize JavaScript.
  • To add a new JavaScript snippet, click Add custom JavaScript. Or, update an existing snippet by hovering over the existing row, then clicking Edit.

add-javascript-to-tracking-code

  • In the right sidebar, add your custom JavaScript, then click Save. Your tracking code will be updated automatically.