How to add analytics to Vue

Adding analytics to your Vue application helps you understand how users interact with your app. Helion's Web SDK integrates smoothly with Vue 3 and Vue Router, providing automatic page view tracking, custom events, and user identification without requiring Vue-specific bindings.

Helion is an open-source alternative to Mixpanel and Google Analytics. It delivers powerful insights while respecting user privacy through cookieless tracking by default.

Prerequisites

• A Vue 3 project (Vite or Vue CLI)
• An Helion account (sign up free)
• Your Client ID from the Helion dashboard

Install the SDK

The Helion Web SDK is a lightweight package that works in any JavaScript environment, including Vue. Install it using npm, and pnpm or yarn work the same way.

npm install @helionlabs/web

Create an Helion instance

Create a dedicated file for your Helion instance. This centralizes your analytics configuration and makes the instance easy to import throughout your application.

import { Helion } from '@helionlabs/web';

export const hl = new Helion({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});

The trackScreenViews option automatically tracks page views when the URL changes. This works with Vue Router's client-side navigation. The trackAttributes option enables declarative tracking using data-track attributes on HTML elements.

Using environment variables

For production applications, store your Client ID in environment variables.

import { Helion } from '@helionlabs/web';

export const hl = new Helion({
  clientId: import.meta.env.VITE_HELION_CLIENT_ID,
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});

VITE_HELION_CLIENT_ID=your-client-id

Initialize on app load

Import the Helion instance in your app's entry point to ensure it initializes when your application loads. This is all you need to start tracking page views automatically.

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import './lib/op'; // Initialize Helion

const app = createApp(App);
app.use(router);
app.mount('#app');

Make Helion available globally (optional)

If you prefer accessing Helion through the Vue instance rather than importing it in each component, you can add it as a global property.

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { op } from './lib/op';

const app = createApp(App);
app.config.globalProperties.$op = op;
app.use(router);
app.mount('#app');

This makes this.$op available in Options API components and allows you to inject it in Composition API components.

Track page views

With trackScreenViews: true, Helion automatically tracks page views when the browser's URL changes. This works out of the box with Vue Router.

If you need to track page views manually or want to include additional route metadata, you can use a Vue Router navigation guard.

import { createRouter, createWebHistory } from 'vue-router';
import { op } from '../lib/op';
import routes from './routes';

const router = createRouter({
  history: createWebHistory(),
  routes,
});

router.afterEach((to) => {
  op.track('screen_view', {
    path: to.path,
    name: String(to.name),
  });
});

export default router;

If you use this approach, set trackScreenViews: false in your Helion configuration to avoid duplicate tracking.

Track custom events

Import the Helion instance in your components to track events. The track method accepts an event name and an optional properties object.

Using Composition API

<template>
  <button type="button" @click="handleClick">Sign Up</button>
</template>

<script setup lang="ts">
import { op } from '../lib/op';

function handleClick() {
  op.track('button_clicked', {
    button_name: 'signup',
    button_location: 'hero',
  });
}
</script>

Using Options API

<template>
  <button type="button" @click="handleClick">Sign Up</button>
</template>

<script>
import { op } from '../lib/op';

export default {
  methods: {
    handleClick() {
      op.track('button_clicked', {
        button_name: 'signup',
        button_location: 'hero',
      });
    },
  },
};
</script>

Track form submissions

Form tracking helps you understand conversion rates and identify where users drop off.

<template>
  <form @submit.prevent="handleSubmit">
    <input
      v-model="email"
      type="email"
      placeholder="Enter your email"
    />
    <button type="submit">Submit</button>
  </form>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { op } from '../lib/op';

const email = ref('');

function handleSubmit() {
  op.track('form_submitted', {
    form_name: 'contact',
    form_location: 'homepage',
  });

  // Your form submission logic
}
</script>

Use data attributes for declarative tracking

The Web SDK supports declarative tracking using data-track attributes. This is useful for simple click tracking without writing JavaScript.

<template>
  <button
    data-track="button_clicked"
    data-track-button_name="signup"
    data-track-button_location="hero"
  >
    Sign Up
  </button>
</template>

When a user clicks this button, Helion automatically sends a button_clicked event with the specified properties. This requires trackAttributes: true in your configuration.

Identify users

Once a user logs in or provides identifying information, call identify to associate their activity with a profile. This enables user-level analytics and cohort analysis.

<template>
  <div>Welcome, {{ user?.firstName }}!</div>
</template>

<script setup lang="ts">
import { watch } from 'vue';
import { op } from '../lib/op';

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
  plan: string;
  createdAt: string;
}

const props = defineProps<{ user: User | null }>();

watch(
  () => props.user,
  (user) => {
    if (user) {
      op.identify({
        profileId: user.id,
        firstName: user.firstName,
        lastName: user.lastName,
        email: user.email,
        properties: {
          plan: user.plan,
          signupDate: user.createdAt,
        },
      });
    }
  },
  { immediate: true }
);
</script>

Clear user data on logout

When users log out, clear the stored profile data to ensure subsequent events aren't associated with the previous user.

<template>
  <button @click="handleLogout">Logout</button>
</template>

<script setup lang="ts">
import { op } from '../lib/op';

const emit = defineEmits<{ logout: [] }>();

function handleLogout() {
  op.clear();
  emit('logout');
}
</script>

Set global properties

Properties set with setGlobalProperties are included with every event. This is useful for app version tracking, feature flags, or A/B test variants.

<script setup lang="ts">
import { onMounted } from 'vue';
import { op } from './lib/op';

onMounted(() => {
  op.setGlobalProperties({
    app_version: '1.0.0',
    environment: import.meta.env.MODE,
  });
});
</script>

Verify your setup

Open your Vue app in the browser and navigate between a few pages. Interact with elements that trigger custom events. Then open your Helion dashboard and check the Real-time view to see events appearing.

If events aren't appearing, check the browser console for errors. Verify your Client ID is correct and ensure ad blockers aren't blocking requests to the Helion API. The Network tab in your browser's developer tools can help you confirm that requests are being sent.

Next steps

The Web SDK has additional features like property incrementing and event filtering. Read the full Web SDK documentation for the complete API reference.

For Nuxt.js applications, the setup is similar. Initialize Helion in a Nuxt plugin and the automatic page view tracking will work with Nuxt's router.