Vue Hotjar Plugin

Common errors

• Cannot read property '$hj' of undefined

  cause Attempting to access `this.$hj` in a Vue 3 component or when `isProduction` is `false` without a check. In Vue 3, `$hj` is not injected by this package. If `isProduction` is `false`, `$hj` is explicitly `false`.
  fix For Vue 2, ensure `isProduction` is `true` or wrap `$hj` calls in `if (this.$hj) { ... }`. For Vue 3, this package does not provide `$hj`. Use `vue-hotjar-next` for Vue 3 support, or directly interact with `window.hj` after Hotjar has loaded.

• TypeError: Cannot read properties of undefined (reading 'use')

  cause This error typically indicates that `Vue` is not correctly imported or available when `Vue.use(Hotjar, ...)` is called, or an incorrect `Vue` instance is being used for initialization.
  fix Ensure `import Vue from 'vue'` is at the top of your main application file and that you are using a Vue 2 application context for this plugin. Verify `vue` is correctly installed as a dependency.

Warnings

• breaking This `vue-hotjar` package is designed for Vue 2.x.x. For Vue 3.x.x projects, it offers only partial support, and users may encounter issues, particularly with TypeScript typings due to interface updates in Vue 3. A separate package, `vue-hotjar-next`, is available for full Vue 3 compatibility.
  Fix: For Vue 3 projects, consider using `vue-hotjar-next` instead. If staying with `vue-hotjar` for Vue 3, be aware of potential typing conflicts and limited functionality.
• gotcha The `$hj` global property, which provides access to the Hotjar API, is only available if your Vue version is 2.x.x. It is explicitly disabled for Vue 3.0.0 and above for compatibility reasons.
  Fix: Ensure your project is running Vue 2.x.x to use the `$hj` global property. For Vue 3, you must use the `vue-hotjar-next` package or directly interact with `window.hj` if the plugin doesn't offer an alternative for Vue 3.
• gotcha The `$hj` global property will return `false` if the `isProduction` parameter is set to `false` during plugin initialization. This means any calls to `$hj` methods must be wrapped in a conditional check.
  Fix: Always wrap `$hj` calls in a conditional statement, e.g., `if (this.$hj) { this.$hj('event', 'my_event'); }`, especially during development or when `isProduction` is false.
• gotcha The package has not been updated since June 2021. This might lead to compatibility issues with newer versions of Vue 2 (though less likely) or newer Hotjar SDK features/changes not explicitly covered by this plugin.
  Fix: Before integrating, verify compatibility with your specific Vue 2 environment and ensure the Hotjar features you plan to use are supported by this older plugin. Consider alternatives or direct Hotjar script integration if this plugin's features are insufficient or outdated.

Install

• npm install vue-hotjar npm
• yarn add vue-hotjar yarn
• pnpm add vue-hotjar pnpm

Imports

• Hotjar
  wrong:

  import { Hotjar } from 'vue-hotjar'

  correct:

  import Hotjar from 'vue-hotjar'

  The plugin is exported as a default export.
• Vue.use
  wrong:

  import Hotjar from 'vue-hotjar'; new Vue({ el: '#app', render: h => h(App) }) // Hotjar not initialized

  correct:

  import Vue from 'vue'; import Hotjar from 'vue-hotjar'; Vue.use(Hotjar, { id: 'XXXXXXX' })

  Hotjar must be initialized via `Vue.use()` for the plugin to register correctly.
• $hj
  wrong:

  this.$hj('event', 'user_action');

  correct:

  if (this.$hj) { this.$hj('event', 'user_action'); }

  The `$hj` global property is only available for Vue 2.x.x and returns `false` if `isProduction` is set to `false`, requiring a check before use.

Quickstart

This quickstart demonstrates how to install `vue-hotjar`, initialize it with a Hotjar Site ID, and conditionally use the global `$hj` property for tracking custom events or identifying users.

import Vue from 'vue';
import Hotjar from 'vue-hotjar';

// Hotjar Site ID can be found at insights.hotjar.com under tracking.
// It's recommended to bind `isProduction` to your Node environment variable.
// snippetVersion defaults to 6 if not specified.
Vue.use(Hotjar, {
  id: process.env.VUE_APP_HOTJAR_ID ?? '1234567',
  isProduction: process.env.NODE_ENV === 'production',
  snippetVersion: 6
});

// Example component where $hj can be used (Vue 2.x.x only)
export default {
  methods: {
    trackPurchase(userId, amount) {
      if (this.$hj) {
        this.$hj('identify', userId, {
          email: 'user@example.com',
          purchase_amount: amount,
          ab_test: 'variant-B',
        });
        this.$hj('stateChange', '/purchase-complete');
      }
    }
  }
};