Vue Gtag Next

Common errors

• Error: "gtag" is not defined

  cause The gtag.js script was not correctly loaded or initialized before the VueGtagNext plugin attempted to use it, or the plugin itself failed to initialize.
  fix Ensure the VueGtagNext plugin is correctly installed with `app.use()` and that the `property.id` configuration is valid. Check network requests to confirm `gtag.js` is loading.

• TypeError: app.use is not a function

  cause This typically indicates that `app` is not a valid Vue 3 application instance, or you are attempting to use `app.use` on a non-Vue 3 environment.
  fix Ensure you are importing `createApp` from 'vue' and calling `createApp(App)` to create your application instance before calling `app.use()`.

• Cannot read properties of undefined (reading 'event') when using useGtag()

  cause The `useGtag` composable was called outside of a component's setup context or before the `VueGtagNext` plugin was installed on the Vue application instance.
  fix Ensure `app.use(VueGtagNext, { ... })` is called before your component that uses `useGtag` is mounted. Call `useGtag()` only within the `setup()` function of a Vue component.

Warnings

• breaking The package explicitly states it is 'not production ready' and was developed when 'Vue 3 is not out yet' (as of October 2020). It has not received updates since 2020, making it highly likely to be incompatible with modern Vue 3 versions and best practices.
  Fix: Consider using an actively maintained Google Analytics integration for Vue 3, or implement gtag.js manually until this package receives updates or an alternative emerges.
• gotcha Lack of maintenance since October 2020 means the package may not include updates to the gtag.js specification, potentially leading to outdated or incorrect tracking implementations for newer Google Analytics features (e.g., GA4 specific events).
  Fix: Always cross-reference your tracking implementation with the official gtag.js documentation to ensure accuracy. Manually verify data in Google Analytics.
• gotcha Due to its abandoned status, there is no ongoing security auditing or bug fixes. Using unmaintained tracking libraries can pose supply chain security risks if vulnerabilities are discovered and not patched.
  Fix: Assess the security implications carefully. For critical applications, prefer actively maintained libraries or direct gtag.js integration.

Install

• npm install vue-gtag-next npm
• yarn add vue-gtag-next yarn
• pnpm add vue-gtag-next pnpm

Imports

• default
  wrong:

  const VueGtagNext = require('vue-gtag-next')

  correct:

  import VueGtagNext from 'vue-gtag-next'

  The default export is the plugin function used with app.use(). ESM is required for Vue 3 applications.
• useGtag

  import { useGtag } from 'vue-gtag-next'

  This provides the Composition API hook for accessing gtag functions within components. Available since v1.14.0.
• gtag

  import { gtag } from 'vue-gtag-next'

  This exports the raw gtag function for direct use, primarily outside of Vue components or for advanced scenarios. Available since v1.14.0.

Quickstart

This quickstart initializes the VueGtagNext plugin with a Google Analytics ID and demonstrates sending both a page view event and a custom event from a Vue 3 component using the Composition API's `useGtag` hook.

import { createApp } from 'vue';
import VueGtagNext, { useGtag } from 'vue-gtag-next';

const App = {
  template: `
    <div>
      <h1>Google Analytics Demo</h1>
      <button @click="sendPageView">Send Page View</button>
      <button @click="sendEvent">Send Custom Event</button>
    </div>
  `,
  setup() {
    const { event } = useGtag();

    const sendPageView = () => {
      event('page_view', {
        page_title: 'Home Page',
        page_path: '/',
      });
      console.log('Page view sent!');
    };

    const sendEvent = () => {
      event('button_click', {
        event_category: 'engagement',
        event_label: 'Call to Action',
        value: 1,
      });
      console.log('Custom event sent!');
    };

    return { sendPageView, sendEvent };
  },
};

const app = createApp(App);

app.use(VueGtagNext, {
  property: {
    id: process.env.VUE_APP_GA_ID ?? 'G-XXXXXXXXXX' // Replace with your actual GA ID
  },
  enabled: true, // Enable or disable tracking
  bootstrap: true, // Inject gtag.js script automatically
});

app.mount('#app');