Nuxt

Looking for a step-by-step tutorial? Check out the Nuxt analytics guide.

Good to know

Keep in mind that all tracking here happens on the client!

Read more about server side tracking in the Server Side Tracking section.

Installation

Install dependencies

pnpm install @helionlabs/nuxt

Initialize

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@helionlabs/nuxt'],
  helion: {
    clientId: 'your-client-id',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  },
});

Options

Common options

apiUrl - The url of the helion API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Web options

trackScreenViews - If true, the library will automatically track screen views (default: false)
trackOutgoingLinks - If true, the library will automatically track outgoing links (default: false)
trackAttributes - If true, you can trigger events by using html attributes (<button type="button" data-track="your_event" />) (default: false)
sessionReplay - Session replay configuration object (default: disabled). See session replay docs for full options.
- enabled - Enable session replay recording (default: false)
- maskAllInputs - Mask all input field values (default: true)
- maskTextSelector - CSS selector for text elements to mask (default: [data-helion-replay-mask])
- blockSelector - CSS selector for elements to replace with a placeholder (default: [data-helion-replay-block])
- blockClass - Class name that blocks elements from being recorded
- ignoreSelector - CSS selector for elements excluded from interaction tracking
- flushIntervalMs - How often (ms) recorded events are sent to the server (default: 10000)
- maxEventsPerChunk - Maximum events per payload chunk (default: 200)
- maxPayloadBytes - Maximum payload size in bytes (default: 1048576)
- scriptUrl - Custom URL for the replay script (script-tag builds only)

Nuxt options

clientId - Your Helion client ID (required)
apiUrl - The API URL to send events to (default: https://api.helionlabs.dev)
trackScreenViews - Automatically track screen views (default: true)
trackOutgoingLinks - Automatically track outgoing links (default: true)
trackAttributes - Automatically track elements with data-track attributes (default: true)
trackHashChanges - Track hash changes in URL (default: false)
disabled - Disable tracking (default: false)
proxy - Enable server-side proxy to avoid adblockers (default: false)

Usage

Using the composable

The useHelion composable is auto-imported, so you can use it directly in any component:

<script setup>
const hl = useHelion(); // Auto-imported!

function handleClick() {
  op.track('button_click', { button: 'signup' });
}
</script>

<template>
  <button @click="handleClick">Trigger event</button>
</template>

Accessing via useNuxtApp

You can also access the Helion instance directly via useNuxtApp():

<script setup>
const { $helionlabs } = useNuxtApp();

$helionlabs.track('my_event', { foo: 'bar' });
</script>

Tracking Events

You can track events with two different methods: by calling the op.track() method directly or by adding data-track attributes to your HTML elements.

<script setup>
const hl = useHelion();
op.track('my_event', { foo: 'bar' });
</script>

Identifying Users

To identify a user, call the op.identify() method with a unique identifier.

<script setup>
const hl = useHelion();

op.identify({
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});
</script>

Setting Global Properties

To set properties that will be sent with every event:

<script setup>
const hl = useHelion();

op.setGlobalProperties({
  app_version: '1.0.2',
  environment: 'production',
});
</script>

Incrementing Properties

To increment a numeric property on a user profile.

value is the amount to increment the property by. If not provided, the property will be incremented by 1.

<script setup>
const hl = useHelion();

op.increment({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>

Decrementing Properties

To decrement a numeric property on a user profile.

value is the amount to decrement the property by. If not provided, the property will be decremented by 1.

<script setup>
const hl = useHelion();

op.decrement({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>

Clearing User Data

To clear the current user's data:

<script setup>
const hl = useHelion();

op.clear();
</script>

Server side

If you want to track server-side events, you should create an instance of our Javascript SDK. Import Helion from @helionlabs/sdk

When using server events it's important that you use a secret to authenticate the request. This is to prevent unauthorized requests since we cannot use cors headers.

You can use the same clientId but you should pass the associated client secret to the SDK.

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

const opServer = new Helion({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

opServer.track('my_server_event', { ok: '✅' });

// Pass `profileId` to track events for a specific user
opServer.track('my_server_event', { profileId: '123', ok: '✅' });

Serverless & Edge Functions

If you log events in a serverless environment, make sure to await the event call to ensure it completes before the function terminates.

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

const opServer = new Helion({
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
});

export default defineEventHandler(async (event) => {
  // Await to ensure event is logged before function completes
  await opServer.track('my_server_event', { foo: 'bar' });
  return { message: 'Event logged!' };
});

Proxy events

With the proxy option enabled, you can proxy your events through your server, which ensures all events are tracked since many adblockers block requests to third-party domains.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@helionlabs/nuxt'],
  helion: {
    clientId: 'your-client-id',
    proxy: true, // Enables proxy at /api/helion/*
  },
});

When proxy: true is set:

The module automatically sets apiUrl to /api/helion
A server handler is registered at /api/helion/**
All tracking requests route through your server

This helps bypass adblockers that might block requests to api.helionlabs.dev.

Common options

Web options

On this page