Docs

Nuxt

Suggest Edits

This library lets you start collecting data from your web app. It also helps you control which data you collect – like page views, virtual page views, custom events and more. The library contains modules with methods.

Installation

To install JS library for Nuxt, follow these steps:

  1. In your project folder, run the following command:
npm install @piwikpro/nuxt-piwik-pro
  1. In your Nuxt project, include @piwikpro/nuxt-piwik-pro as a Nuxt module in the nuxt.config.ts file. In the arguments, pass your account address (example: https://example.piwik.pro/) and the site ID (Where to find it?):
// nuxt.config.ts
export default defineNuxtConfig({
  //...
  modules: [
    [
      "@piwikpro/nuxt-piwik-pro",
      {
        containerId: process.env.PIWIK_PRO_CONTAINER_ID,
        containerUrl: process.env.PIWIK_PRO_CONTAINER_URL,
      },
    ],
  ],
  //...
});

Configuration options

type ConfigOptions = {
 containerId: string;
 containerUrl: string;
 dataLayerName?: string;
 nonce?: string;
}

Nonce

The nonce attribute is useful for allowing specific elements, such as particular inline scripts or style elements. It helps you avoid using the CSP unsafe-inline directive, which would allow all inline scripts or styles.

To pass a nonce to a script, include it as the third argument when calling the script initialization method.

Usage

The @piwikpro/nuxt-piwik-pro module initializes the Piwik PRO container automatically. The module also injects a client-only plugin into the Nuxt application instance, allowing you to use all Piwik PRO services globally as part of the Nuxt context returned by the useNuxtApp() composable, accessed via $piwikPRO.

Keep in mind that Piwik PRO is a client-only library, so its services are not available on the server side.

// In any component or other part of application code
const { $piwikPRO } = useNuxtApp();
// $piwikPRO won't be available on server-side code!
if (module.meta.client) {
  $piwikPRO.PageViews.trackPageView();
  $piwikPRO.GoalConversions.trackGoal(1, 100);
}

Usage with usePiwikPro()

To safely use Piwik PRO services, import usePiwikPro() from @piwikpro/nuxt-piwik-pro/composables.

// In any component or other part of application code
import { usePiwikPro } from "@piwikpro/nuxt-piwik-pro/composables";
// callback can be sync or async function
const userId = await usePiwikPro(
  ({ PageViews, GoalConversions, UserManagement }) => {
    PageViews.trackPageView();
    GoalConversions.trackGoal(1, 100);
    return UserManagement.getUserId();
  }
);

Export usePiwikPro() as a Nuxt composable

To make this composable globally available, create a .ts file in the /composables directory and export usePiwikPro() from @piwikpro/nuxt-piwik-pro/composables.

// composables/usePiwikPro.ts
export { usePiwikPro } from "@piwikpro/nuxt-piwik-pro/composables";

// In any component or other part of application code
const userId = await usePiwikPro(
  ({ PageViews, GoalConversions, UserManagement }) => {
    PageViews.trackPageView();
    GoalConversions.trackGoal(1, 100);
    return UserManagement.getUserId();
  }
);

Usage with Nuxt component

Alternatively, you can wrap the component with Piwik PRO usage using the <ClientOnly /> Nuxt component.

// In client-only <WithPiwikPROUsage/> component
const { $piwikPRO } = useNuxtApp();
$piwikPRO.PageViews.trackPageView();
$piwikPRO.GoalConversions.trackGoal(1, 100);

// Server-side code
<template>
   <ClientOnly fallback-tag="span" fallback="Loading comments...">
       <WithPiwikPROUsage/>
   </ClientOnly>
</template>

Usage in a client-only page

If you want to use Piwik PRO services directly in a page component, you can add client to the file name.

// In piwik-pro.client.ts page component
const { $piwikPRO } = useNuxtApp();
$piwikPRO.PageViews.trackPageView();
$piwikPRO.GoalConversions.trackGoal(1, 100);

Examples of usage

Explore the ./example directory to see how to use this package with specific examples and its various methods.

Methods

Here’s a list of all JS methods you can use in your Nuxt project. Descriptions and other information are available after clicking on links.

A

C

D

E

G

H

I

L

R

S

T

Updated 8 days ago