Nuxt.js

This guide explains how to integrate OnyxMetric with your Nuxt.js application for analytics tracking.

Adding OnyxMetric via Nuxt Scripts (Recommended)

Nuxt Scripts ships a first-class OnyxMetric Analytics integration. It loads the script optimally, handles SPA route tracking, and gives you a typed composable for custom events. This is the recommended method for Nuxt 3 and Nuxt 4 applications.

Retrieve Your Site ID

Navigate to your OnyxMetric dashboard to obtain your Site ID. You'll need this for the siteId option below.

Install the Nuxt Scripts module

npx nuxi module add scripts

This installs @nuxt/scripts and adds it to the modules array in your nuxt.config.

Configure OnyxMetric in `nuxt.config.ts`

export default defineNuxtConfig({
  modules: ['@nuxt/scripts'],
  scripts: {
    registry: {
      onyxmetricAnalytics: {
        siteId: 'YOUR_SITE_ID', // Replace with your Site ID
        trigger: 'onNuxtReady',
      },
    },
  },
})

Useful options:

siteId (required): Your OnyxMetric site ID.
autoTrackPageview: Track page views automatically (enabled by default).
trackSpa: Track client-side route changes (enabled by default).
analyticsHost: Override the script/API host if you serve the tracking script through your own proxy (e.g. https://yourdomain.com/api). See the proxy guide.
sessionReplay, webVitals, trackOutbound: Optional features you can enable as needed.

You can keep your Site ID out of source control by setting it via environment variable. Nuxt Scripts reads NUXT_PUBLIC_SCRIPTS_ONYX_ANALYTICS_SITE_ID at runtime, so you can leave siteId unset in config and provide it through your environment instead.

Verify Installation

After restarting your Nuxt development server or deploying your application, open your OnyxMetric dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that the OnyxMetric script is loaded.

Custom Event Tracking

Use the useScriptOnyxMetricAnalytics composable to track custom events from any component. The returned proxy queues calls until the script is ready, so it's safe to call immediately:

<template>
  <button @click="handleAction">Track Important Action</button>
</template>

<script setup>
const { proxy } = useScriptOnyxMetricAnalytics()

function handleAction() {
  proxy.event('nuxt_interaction', { detail: 'User clicked important button' })
}
</script>

Alternative: Adding OnyxMetric via `app.head.script`

If you'd rather not use the Nuxt Scripts module, you can add the OnyxMetric script directly through your Nuxt configuration.

Modify `nuxt.config.ts` (or `.js`)

For Nuxt 3:

Add the OnyxMetric script to the app.head.script array in your nuxt.config.ts file:

export default defineNuxtConfig({
  // ... other configurations
  app: {
    head: {
      script: [
        {
          src: 'https://app.onyxmetric.com/api/script.js',
          defer: true,
          'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID
        },
      ],
    },
  },
})

For Nuxt 2:

Add the OnyxMetric script to the head.script array in your nuxt.config.js file:

export default {
  // ... other configurations
  head: {
    // ... other head properties
    script: [
      {
        src: 'https://app.onyxmetric.com/api/script.js',
        defer: true,
        'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID
      },
    ],
  },
}

Ensure you replace YOUR_SITE_ID with your actual Site ID from your OnyxMetric dashboard. This method ensures the script is included in the <head> of all your pages.

Verify Installation

After restarting your Nuxt.js development server or deploying your application, open your OnyxMetric dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that script.js is loaded.

SPA Page View Tracking: OnyxMetric's tracking script is designed to automatically detect route changes in Nuxt.js applications and track them as page views. If you find that page views are not being tracked correctly after navigation (which is uncommon for Nuxt), you might need to manually trigger page views using window.onyx.pageview() after each route change. You could use Nuxt's router events or middleware for this if necessary, but test the default behavior first.

Custom Event Tracking

From any Vue component within your Nuxt.js application, you can track custom events directly via window.onyx:

<template>
  <button @click="trackCustomEvent">Track Important Action</button>
</template>

<script setup>
function trackCustomEvent() {
  if (import.meta.client && window.onyx) { // Ensure running on client and onyxmetric exists
    window.onyx.event('nuxt_interaction', { detail: 'User clicked important button' });
  }
}
</script>

Using import.meta.client (Nuxt 3+) or checking typeof window !== 'undefined' is good practice before accessing window if your component might render or execute logic on the server side. (On Nuxt 2, use the legacy process.client flag instead.)

On this page