In addition to tracking page views, the HubSpot tracking code has functions that allow you to identify visitors, track events, and manually track page views (without reloading the page).

Function calls are pushed into the _hsq array:

var _hsq = window._hsq = window._hsq || [];
_hsq.push(["method", "arg1"]);

Anything already in the _hsq array is processed when the tracking code is loaded, so you can push an identify call to the array before the code loads to have the identity information pushed with the initial trackPageView call.

Note: trackPageView is automatically called when the tracking code loads, so you should not push any trackPageView calls to _hsq before the page loads.

How do identities work?

The HubSpot Analytics system identifies unique records using two pieces of data, the usertoken (stored in the visitors browser in the hubspotutk cookie) and the email address.  When the HubSpot tracking code tracks an action (such as a page view) for a visitor, the tracking code automatically associates that action with the usertoken.  When you use the Tracking Code API to identify a record by its email address, the analytics system will tie that email address to the usertoken, so that the HubSpot Contacts system can update the contact record with that email address, or create a new contact record with the email address if no contact with that email exists yet. HubSpot will validate the email address used for any process that would create or update a contact record. The Contacts system uses the analytics data associated with the  usertoken to show analytics data (page views, original source, etc.) for the contact record.

With this in mind, you should only use the Identify method when you know the identity (i.e. the email address) of the person viewing the page.  Using a placeholder email for unknown visitors will create a contact record with that placeholder email, and the visitor's usertoken cookie will be associated with that record, meaning that all unknown visitors would be associated with that single placeholder contact.

Keep in mind that the identify function only sets the identities in the tracker.  The identities do not get passed to HubSpot until you make a separate trackPageView or trackEvent call.

Please note that the HTTP API cannot be used to associate analytics data with a contact record, though you can still use the &email= parameter in the URL to associate the event with the contact with that email address (or create a new contact if the email address does not belong to an existing record).

Tracking Events

The trackEvent function is used to track Events in your HubSpot Reports.  Events are used to track that some event occurred, and can be tied to a HubSpot Contact record so that you can see if/when a contact triggered that event.  While you can set up simple events in the HubSpot Application, you can use the Events API to track more complicated processes on your website, or track events that occur offline.

Which one of the two Event APIs should I use?

There are two APIs that work with Events, the trackEvent function in the Tracking Code API (which is the preferred API) and the HTTP API.

The trackEvent function requires that the HubSpot tracking code be installed on the page.  Since this function  works alongside HubSpot's analytics tracking, any events triggered through the JavaScript API will automatically be associated with the visitor's hubspotutk cookie (often called the usertoken), so the event would automatically be tied to the contact associated with that usertoken (see the section about identities below for more information).

The HTTP API can be used in cases where the HubSpot tracking code cannot be installed, so it can be used to track offline events (so you could trigger an event based on data processed in a CRM).  While the HTTP API cannot be used to tie analytics data to a contact record, you can identify a contact record by email address, so that offline events can still be tied to contact records.

Event IDs and names

Events can be triggered, using a numerical ID or a string name. If you're creating events in HubSpot, from the Reports > Events app, events will automatically be assigned a numerical ID, and you'll need to use that numerical ID to trigger that specific event. You can get the ID out of the URL when viewing the event in HubSpot. See this page for more details about creating events.

Second, you can trigger an event using a string name for the event. If you use a name, and there is not an existing event that already has that name, a new event with that name will be dynamically created. If there is an event was previously dynamically created with a matching name, then the event will count towards that existing event. This allows you to dynamically create new events, without needing to create them manually in HubSpot.

Tracking in single-page applications

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:

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

See the documentation for setPath and trackPageView for more details on those functions.

Checking consent banner status

If your site uses the privacy consent banner, you can use the addPrivacyConsentListener function to check the consent status of the visitor. See the documentation for the addPrivacyConsentListener function for more details.

Removing consent banner cookies

If you need to remove the consent banner cookies for a visitor, such as in the case of a GDPR related deletion request, you can use the revokeCookieConsent function. See the documentation for the revokeCookieConsent function for more details.

Place do not track cookie

In the event where you need to prevent all tracking by the HubSpot tracking code, you can place the do not track cookie into a visitor's browser. See the documentation for the doNotTrack function for more details.