Piwik PRO Library for Next.js

Dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in Next.js applications.

Installation

To use this package in your project, run the following command.

npm

npm install @piwikpro/next-piwik-pro

Yarn

yarn add @piwikpro/next-piwik-pro

Basic setup

In your Next.js Project, include the default PiwikProProvider in the layout.tsx file. To set up the Piwik PRO Tag Manager container in the app.

In the arguments, pass your container id and your container url as parameters (marked container-id and container-url in the example below).

layout.tsx

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>
  )
}

Setup with pages router

In the next.config.js use transpilePackages option.

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

module.exports = nextConfig

Setup with environmental variables

If you plan to use environmental variables to config your Piwik account you can do it with adding them to your .env file. Remember that variables to be visible in component need to be named with NEXT_PUBLIC_ prefix, in other cases they will be visible only in Node context but not in Next.

.env

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

layout.tsx

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 nonce

The nonce attribute is useful to allow-list specific elements, such as a particular inline script or style elements. It can help you to avoid using the CSP unsafe-inline directive, which would allow-list all inline scripts or styles.

If you want your nonce to be passed to the script, pass it as the third argument when calling the script initialization method.

layout.tsx

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 in your page you need to include usePiwikPro from the library. Make sure to use usePiwikPro in client components only, otherwise you will get an error. To make it work You need to use it in separated client component (use component)

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

Then you need to define modules you want to use and initialize it from previously included usePiwikPro context. In example below you can see the initialization of the PageViews module.

const { PageViews } = usePiwikPro()

You can use those methods in all hooks and props for ex. useEffect or onClick.

useEffect

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

onClick

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

Type Aliases

Dimensions

Ƭ Dimensions: Record<`dimension${number}`, string>

InitOptions

Ƭ InitOptions: Object

Type declaration

Name	Type	Description
`dataLayerName?`	`string`	Defaults to 'dataLayer'
`nonce?`	`string`	-

PaymentInformation

Ƭ PaymentInformation: Object

Type declaration

Name	Type
`discount?`	`number` \| `string`
`grandTotal`	`number` \| `string`
`orderId`	`string`
`shipping?`	`number` \| `string`
`subTotal?`	`number` \| `string`
`tax?`	`number` \| `string`

Product

Ƭ Product: Object

Type declaration

Name	Type
`brand?`	`string`
`category?`	`LimitedArrayFiveStrings`
`customDimensions?`	`Record`<`number`, `string`>
`name?`	`string`
`price?`	`number`
`quantity?`	`number`
`sku`	`string`
`variant?`	`string`

VisitorInfo

Ƭ VisitorInfo: [isNew: "0" | "1", visitorId: string, firstVisitTS: number, previousVisitCount: string | number, currentVisitTS: number, lastVisitTS: number | "", lastEcommerceOrderTS: number | ""]

Variables

default

• Const default: Object

Type declaration

Name	Type
`getInitScript`	typeof `PiwikPro.getInitScript`
`initialize`	typeof `PiwikPro.init`

ContentTracking

CookieManagement

CustomDimensions

CustomEvent

DataLayer

Type Aliases

DataLayerEntry

Ƭ DataLayerEntry: Record<string, AnyData>

push

▸ push(data): number

Adds entry to a data layer

Parameters

Name	Type
`data`	`DataLayerEntry`

Returns

number

setDataLayerName

▸ setDataLayerName(name): void

Parameters

Name	Type
`name`	`string`

Returns

void

DownloadAndOutlink

When a visitor produces an events and closes the page immediately afterwards, e.g. when opening a link, the request might get cancelled. To avoid loosing the last event this way, JavaScript Tracking Client will lock the page for a fraction of a second (if wait time hasn’t passed), giving the request time to reach the Collecting & Processing Pipeline

Parameters

Name	Type
`time`	`number`

Returns

void

trackLink

▸ trackLink(url, linkType, dimensions?, callback?): void

Manually tracks outlink or download event with provided values

Parameters

Name	Type
`url`	`string`
`linkType`	`string`
`dimensions?`	`Dimensions`
`callback?`	() => `void`

Returns

void

ErrorTracking

Attempts to send error tracking request using same format as native errors caught by enableJSErrorTracking(). Such error request will still follow rules set for tracker, so it will be sent only when JS error tracking is enabled (enableJSErrorTracking function was called before this attempt). It will also respect rules for tracking only unique errors.

Parameters

Name	Type
`error`	`Error`

Returns

void

GoalConversions

PageViews

SiteSearch

UserManagement

eCommerce

Module: src

Type Aliases

PiwikProProviderProps

Ƭ PiwikProProviderProps: { children: ReactNode ; containerId: string ; containerUrl: string } & InitOptions

default

▸ default(props, context?): ReactNode

Parameters

Name	Type
`props`	`PiwikProProviderProps`
`context?`	`any`

Returns

ReactNode

usePiwikPro

▸ usePiwikPro(): __module

Returns

__module

Name		Name	Last commit message	Last commit date
Latest commit History 87 Commits
.github/workflows		.github/workflows
docs		docs
example		example
scripts		scripts
src		src
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json

Name	Type	Description
`contentInteraction`	`string`	Type of interaction (e.g. "click")
`contentName`	`string`	Name of a content block
`contentPiece`	`string`	Name of the content that was displayed (e.g. link to an image)
`contentTarget`	`string`	Where the content leads to (e.g. URL of some external website)

Name	Type	Description
`domNode`	`Node`	Node marked as content block or containing content blocks. If content block can’t be found, nothing will tracked.
`contentInteraction?`	`string`	Name of interaction (e.g. "click")

Name	Type	Description
`checkOnScroll?`	`boolean`	Whether to scan for visible content on scroll event
`watchInterval?`	`number`	Delay, in milliseconds, between scans for new visible content. Periodic checks can be disabled by passing 0

Name	Type
`products`	`Product`[]
`paymentInformation`	`PaymentInformation`

Name	Type
`customDimensionId`	`string` \| `number`
`customDimensionValue`	`string`

Name	Type
`category`	`string`
`action`	`string`
`name?`	`string`
`value?`	`number`
`dimensions?`	`Dimensions`

Name	Type
`goalId`	`string` \| `number`
`conversionValue`	`number`
`dimensions?`	`Dimensions`

Name	Type
`keyword`	`string`
`category?`	`string`
`searchCount?`	`number`
`dimensions?`	`Dimensions`

Name	Type
`productSKU`	`string`
`productName`	`string`
`productCategory`	`string` \| `string`[]
`productPrice`	`number`
`productQuantity`	`number`

Name	Type
`productSKU`	`string`
`productName?`	`string`
`productCategory?`	`string`[]
`productPrice?`	`string`

Name	Type
`orderId`	`string`
`orderGrandTotal`	`number`
`orderSubTotal?`	`number`
`orderTax?`	`number`
`orderShipping?`	`number`
`orderDiscount?`	`number`

License

PiwikPRO/next-piwik-pro

Folders and files

Latest commit

History

Repository files navigation

Piwik PRO Library for Next.js

Installation

npm

Yarn

Basic setup

layout.tsx

Setup with pages router

Setup with environmental variables

.env

layout.tsx

Setup with nonce

layout.tsx

Usage

useEffect

onClick

Table of contents

Namespaces

Type Aliases

Variables

Type Aliases

Dimensions

InitOptions

Type declaration

PaymentInformation

Type declaration

Product

Type declaration

VisitorInfo

Variables

default

Type declaration

ContentTracking

Table of contents

logAllContentBlocksOnPage

Returns

trackAllContentImpressions

Returns

trackContentImpression

Parameters

Returns

trackContentImpressionsWithinNode

Parameters

Returns

trackContentInteraction

Parameters

Returns

trackContentInteractionNode

Parameters

Returns

trackVisibleContentImpressions

Parameters

Returns

CookieManagement

Table of contents

deleteCookies

Returns

disableCookies

Returns

enableCookies

Returns

getConfigVisitorCookieTimeout

Returns

getCookieDomain

Returns

getCookiePath

Returns

getSessionCookieTimeout

Returns

hasCookies

Returns

setCookieDomain

Parameters

Returns

setCookieNamePrefix