SDKs overview

Hotjar's approach to SDKs and libraries centers around a single, lightweight JavaScript tracking code designed for direct integration into web pages. This script is the primary mechanism for collecting user behavior data, including heatmaps, session recordings, and feedback responses. Unlike many API providers that offer distinct client-side SDKs for multiple programming languages (e.g., Python, Ruby, Java), Hotjar's core data collection relies on its universal JavaScript snippet. This design ensures broad compatibility across web environments, including traditional websites, single-page applications (SPAs), and mobile web experiences.

The JavaScript snippet is responsible for initializing Hotjar services, tracking user interactions, and sending data back to Hotjar's servers. Developers embed this code directly into the <head> section of their website. Beyond this core tracking script, Hotjar provides a public API primarily for programmatic data export and integration with other analytics platforms or internal systems. This API allows for retrieving collected data or managing certain Hotjar configurations, enabling more advanced workflows for developers who need to integrate Hotjar data into larger data ecosystems or custom dashboards.

The design philosophy prioritizes ease of deployment and minimal impact on page load performance, crucial factors for client-side analytics tools. Developers looking to interact with Hotjar's features programmatically typically use the JavaScript tracking code for front-end control and the RESTful API for back-end data management.

Official SDKs by language

Hotjar's official developer tools are primarily focused on its core JavaScript tracking script for client-side data collection and a RESTful API for server-side data interaction. The concept of an "SDK" in the traditional sense (e.g., a dedicated library for Python or Java to interact with Hotjar's services) is not applied to client-side data collection beyond the universal JavaScript snippet. This approach simplifies integration for web developers, as the same script works across various front-end frameworks and CMS platforms.

The following table outlines the primary official developer resources provided by Hotjar:

Language/Environment Package/Resource Description Maturity
JavaScript (Web) Hotjar Tracking Code Primary client-side script for data collection (heatmaps, recordings, surveys). Embedded directly in HTML. Stable, Production
REST API Hotjar Public API HTTP-based API for exporting data, managing surveys, and integrating with other systems. Stable, Production
JavaScript (Web) Hotjar Events API Allows sending custom events from the client-side JavaScript to Hotjar for enhanced tracking. Stable, Production

The Hotjar Tracking Code is continuously maintained and updated by Hotjar, ensuring compatibility with modern web browsers and standards. Its JavaScript Tracking Code documentation provides detailed instructions on its functionalities and advanced usage.

Installation

Installation of Hotjar's primary JavaScript tracking code involves adding a small snippet to the <head> section of your website. This method ensures that Hotjar begins collecting data as early as possible during the page load process, capturing a comprehensive view of user interactions. The process is straightforward and typically completed in a few steps:

  1. Retrieve Your Tracking Code: Log in to your Hotjar account. Navigate to the Sites & Organizations section, select your site, and locate the tracking code. Each site has a unique Hotjar Site ID.
  2. Copy the Snippet: The code snippet will look similar to the example provided in the official Hotjar JavaScript Tracking Code documentation.
  3. Paste into Your Website: Paste the copied code snippet immediately after the <head> tag on every page you wish to track. For most content management systems (CMS) or frameworks, there's a global header file or a specific setting to embed scripts across all pages.

Example Installation with a Content Management System (CMS)

Many CMS platforms offer specific ways to integrate analytics scripts without directly editing theme files. For example:

  • WordPress: Use a plugin like "Insert Headers and Footers" or edit your theme's header.php file.
  • Shopify: Navigate to Online Store > Themes > Actions > Edit code. Find theme.liquid and paste the code within the <head> section.
  • Google Tag Manager (GTM): This is a recommended method for managing Hotjar and other tracking scripts. Create a new Custom HTML tag in GTM, paste the Hotjar snippet, and set it to fire on all pages. This method centralizes script management and can improve deployment efficiency. Google Tag Manager's quickstart guide provides further details on setup.

For Single Page Applications (SPAs), Hotjar automatically tracks route changes and new content, but specific configuration might be necessary for accurate session recording and event tracking, as detailed in the Hotjar SPA documentation.

Quickstart example

The quickstart for Hotjar primarily involves embedding the JavaScript tracking code. Once embedded, Hotjar automatically begins collecting data for heatmaps and session recordings based on your site's configuration. For more advanced tracking, such as identifying users or sending custom events, additional JavaScript calls are made using the global hj object.

Basic JavaScript Tracking Code Embed

Place this snippet in the <head> section of your HTML, replacing YOUR_SITE_ID with your actual Hotjar Site ID:

<script>
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:YOUR_SITE_ID,hjsv:6};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>

Identifying Users

To associate Hotjar data with specific users in your system (without collecting personally identifiable information unless explicitly configured), you can use the hj('identify') function. This is useful for filtering recordings or heatmaps by user segments.

// Example: Identify a logged-in user with a unique ID and optional attributes
hj('identify', 'USER_ID_FROM_YOUR_SYSTEM', {
    name: 'John Doe',
    email: '[email protected]', // Use with caution due to privacy; consider hashing
    plan: 'Premium',
    signupDate: '2023-01-15'
});

For privacy considerations, Hotjar recommends avoiding the transmission of sensitive PII directly. Refer to the Hotjar user identification documentation for best practices regarding data privacy and GDPR compliance.

Sending Custom Events

You can trigger custom events in Hotjar to track specific user actions that are not automatically captured, such as form submissions, button clicks, or feature usage. These events can then be used to filter recordings or target surveys.

// Example: Track a 'ProductAddedToCart' event
hj('event', 'ProductAddedToCart');

// Example: Track a 'CheckoutCompleted' event with properties
hj('event', 'CheckoutCompleted', {
    orderId: 'ORD-12345',
    totalAmount: 99.99
});

Custom events are a powerful way to segment and analyze user behavior more granularly. More details on custom events can be found in the Hotjar Custom Events API documentation.

Triggering Surveys or Feedback Widgets

While surveys and feedback widgets are often configured directly within the Hotjar UI, you can programmatically trigger them using the hj object based on specific user actions or conditions.

// Example: Trigger a specific survey based on its ID
hj('trigger', 'survey_ID_from_Hotjar_UI');

This allows for dynamic presentation of feedback tools, enhancing the contextual relevance for users. Consult the Hotjar External API Reference for comprehensive information on all available hj object methods.

Community libraries

Due to Hotjar's primary reliance on a direct JavaScript snippet for client-side data collection and a standard REST API for data export, there is less emphasis on extensive community-developed client-side SDKs compared to platforms that require complex API interactions from various programming languages. The core JavaScript snippet is self-contained and designed to work out-of-the-box across web environments.

However, community contributions often manifest in the form of integrations with popular frameworks, CMS platforms, or tools that simplify the deployment and management of the Hotjar tracking code. These are typically not standalone SDKs but rather plugins, modules, or guides that facilitate Hotjar's integration:

  • CMS Plugins: Community-developed plugins for platforms like WordPress, Drupal, or Joomla often include fields to easily paste the Hotjar tracking code or Site ID, abstracting the manual HTML editing process. These plugins streamline installation for non-technical users.
  • Framework Integrations: While Hotjar's script works natively with modern JavaScript frameworks (React, Angular, Vue.js), developers sometimes create wrapper components or hooks to manage the Hotjar initialization or event sending within the framework's lifecycle. These are typically small, project-specific utilities rather than broadly distributed libraries.
  • Google Tag Manager Templates: The community and Hotjar itself provide custom tag templates for Google Tag Manager, simplifying the deployment of Hotjar and its advanced features (like user identification or custom events) through a visual interface. These templates are widely used to manage Hotjar without direct code modification on the website. The Google Tag Manager template gallery hosts various community and vendor-provided templates.
  • Data Connectors: For the Hotjar Public API, developers might create scripts or connectors in languages like Python or Node.js to pull data into data warehouses, business intelligence tools, or custom reporting dashboards. These are typically custom integrations built for specific analytical needs rather than generic, reusable SDKs for interacting with Hotjar's API. Platforms like Tray.io offer pre-built connectors that leverage Hotjar's API for integration with other services.

Developers seeking to extend Hotjar's capabilities or integrate it into complex environments are encouraged to consult the official Hotjar Help Center and developer documentation, which provides guidance on advanced configurations and API usage.