Nuxt.js

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

Adding BuddyStat via Nuxt Scripts (Recommended)

Nuxt Scripts ships a first-class BuddyStat 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 BuddyStat 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 BuddyStat in `nuxt.config.ts`

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

Useful options:

siteId (required): Your BuddyStat 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 when using a self-hosted BuddyStat instance (e.g. https://your-instance.com/api).
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_BUDDYSTAT_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 BuddyStat dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that the BuddyStat script is loaded.

Custom Event Tracking

Use the useScriptBuddystatAnalytics 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 } = useScriptBuddystatAnalytics()

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

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

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

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

For Nuxt 3:

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

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

For Nuxt 2:

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

export default {
  // ... other configurations
  head: {
    // ... other head properties
    script: [
      {
        src: 'https://app.buddystat.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 BuddyStat 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 BuddyStat 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: BuddyStat'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.buddystat.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.buddystat:

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

<script setup>
function trackCustomEvent() {
  if (import.meta.client && window.buddystat) { // Ensure running on client and buddystat exists
    window.buddystat.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