Next.js

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 Next.js, follow these steps:

In your project folder, run the following command:

npm install @piwikpro/next-piwik-pro

yarn add @piwikpro/next-piwik-pro

Add the PiwikProProvider to the layout.tsx file. In the arguments, pass your account address (example: https://example.piwik.pro/) and the site ID (Where to find it?):

import PiwikProProvider from '@piwikpro/next-piwik-pro'

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang='en'>
      <body>
        <PiwikProProvider
          containerId='container-id'
          containerUrl='container-url'
        >
          {children}
        </PiwikProProvider>
      </body>
    </html>
  )
}

Installation with a page router

To install JS library for Next.js with a page router, follow these steps:

In next.config.js, use the transpilePackages option:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@piwikpro/next-piwik-pro']
}

module.exports = nextConfig

Setup with environment variables

To set up environment variables, follow these steps:

If you plan to use environment variables to configure your Piwik PRO account, add them to your .env file. Variables must be prefixed with NEXT_PUBLIC_ to be accessible in components. Without this prefix, they will only be available in the Node.js context, not in Next.js.

NEXT_PUBLIC_CONTAINER_ID=0a0b8661-8c10-4d59-e8fg-1h926ijkl184
NEXT_PUBLIC_CONTAINER_URL=https://example.piwik.pro

import PiwikProProvider from '@piwikpro/next-piwik-pro'

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang='en'>
      <body>
        <PiwikProProvider
          containerUrl={process.env.NEXT_PUBLIC_CONTAINER_URL}
          containerId={process.env.NEXT_PUBLIC_CONTAINER_ID}
        >
          {children}
        </PiwikProProvider>
      </body>
    </html>
  )
}

Setup with a nonce

The nonce attribute allows you to allow-list specific elements, such as an inline script or style element. This 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.

import PiwikProProvider from '@piwikpro/next-piwik-pro'

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang='en'>
      <body>
        <PiwikProProvider
          containerId='container-id'
          containerUrl='container-url'
          nonce='nonce-string'
        >
          {children}
        </PiwikProProvider>
      </body>
    </html>
  )
}

Usage

To use methods on your page, include usePiwikPro from the library. Ensure you only use usePiwikPro in client components; otherwise, you'll encounter an error. For proper functionality, use it in a separate client component.

import { usePiwikPro } from '@piwikpro/next-piwik-pro'

Next, define the modules you want to use and initialize them using the usePiwikPro context included earlier. The example below shows how to initialize the PageViews module.

const { PageViews } = usePiwikPro()

You can use these methods with any hooks or props, such as useEffect or onClick.

useEffect(() => {
  PageViews.trackPageView('optional title')
}, [])

<button
  onClick={() => {
    CustomEvent.trackEvent('Post', pageData.title)
  }}
>
  CustomEvent.trackEvent button
</button>

Methods

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

addDownloadExtensions()
addEcommerceItem() (deprecated)

hasCookies()

isCrossDomainLinkingEnabled()

logAllContentBlocksOnPage()