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

'use client'

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

'use client'

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

'use client'

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>


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 | “”]

ContentTracking

Functions

logAllContentBlocksOnPage

logAllContentBlocksOnPage(): void

Print all content blocks to the console for debugging purposes

Returns

void


trackAllContentImpressions

trackAllContentImpressions(): void

Scans the entire DOM for content blocks and tracks impressions after all page elements load. It does not send duplicates on repeated calls unless trackPageView was called in between trackAllContentImpressions invocations

Returns

void


trackContentImpression

trackContentImpression(contentName, contentPiece, contentTarget): void

Parameters

| Name | Type | | :—— | :—— | | contentName | string | | contentPiece | string | | contentTarget | string |

Returns

void


trackContentImpressionsWithinNode

trackContentImpressionsWithinNode(domNode): void

Parameters

| Name | Type | | :—— | :—— | | domNode | Node |

Returns

void


trackContentInteraction

trackContentInteraction(contentInteraction, contentName, contentPiece, contentTarget): void

Tracks manual content interaction event

Parameters

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

Returns

void


trackContentInteractionNode

trackContentInteractionNode(domNode, contentInteraction?): void

Tracks interaction with a block in domNode. Can be called from code placed in onclick attribute

Parameters

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

Returns

void


trackVisibleContentImpressions

trackVisibleContentImpressions(checkOnScroll?, watchInterval?): void

Scans DOM for all visible content blocks and tracks impressions

Parameters

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

Returns

void

CookieManagement

Functions

deleteCookies

deleteCookies(): void

Deletes existing tracking cookies on the next page view

Returns

void


disableCookies

disableCookies(): void

Disables all first party cookies. Existing cookies will be deleted in the next page view

Returns

void


enableCookies

enableCookies(): void

Enables all first party cookies. Cookies will be created on the next tracking request

Returns

void


getConfigVisitorCookieTimeout

getConfigVisitorCookieTimeout(): Promise<number>

Returns expiration time of visitor cookies (in milliseconds)

Returns

Promise<number>


getCookieDomain

getCookieDomain(): Promise<string>

Returns domain of the analytics tracking cookies (set with setCookieDomain()).

Returns

Promise<string>


getCookiePath

getCookiePath(): Promise<string>

Returns the analytics tracking cookies path

Returns

Promise<string>


getSessionCookieTimeout

getSessionCookieTimeout(): Promise<number>

Returns expiration time of session cookies

Returns

Promise<number>


hasCookies

hasCookies(): Promise<boolean>

Returns true if cookies are enabled in this browser

Returns

Promise<boolean>


setCookieDomain

setCookieDomain(domain): void

Sets the domain for the analytics tracking cookies

Parameters

| Name | Type | | :—— | :—— | | domain | string |

Returns

void


setCookieNamePrefix

setCookieNamePrefix(prefix): void

Sets the prefix for analytics tracking cookies. Default is “pk”.

Parameters

| Name | Type | | :—— | :—— | | prefix | string |

Returns

void


setCookiePath

setCookiePath(path): void

Sets the analytics tracking cookies path

Parameters

| Name | Type | | :—— | :—— | | path | string |

Returns

void


setReferralCookieTimeout

setReferralCookieTimeout(seconds): void

Sets the expiration time of referral cookies

Parameters

| Name | Type | | :—— | :—— | | seconds | number |

Returns

void


setSecureCookie

setSecureCookie(secure): void

Toggles the secure cookie flag on all first party cookies (if you are using HTTPS)

Parameters

| Name | Type | | :—— | :—— | | secure | boolean |

Returns

void


setSessionCookieTimeout

setSessionCookieTimeout(seconds): void

Sets the expiration time of session cookies

Parameters

| Name | Type | | :—— | :—— | | seconds | number |

Returns

void


setVisitorCookieTimeout

setVisitorCookieTimeout(seconds): void

Sets the expiration time of visitor cookies

Parameters

| Name | Type | | :—— | :—— | | seconds | number |

Returns

void


setVisitorIdCookie

setVisitorIdCookie(): void

Sets cookie containing analytics ID in browser

Returns

void

CustomDimensions

Functions

deleteCustomDimension

deleteCustomDimension(customDimensionId): void

Removes a custom dimension with the specified ID.

Parameters

| Name | Type | | :—— | :—— | | customDimensionId | string | number |

Returns

void


getCustomDimensionValue

getCustomDimensionValue(customDimensionId): Promise<string | undefined>

Returns the value of a custom dimension with the specified ID.

Parameters

| Name | Type | | :—— | :—— | | customDimensionId | string | number |

Returns

Promise<string | undefined>


setCustomDimensionValue

setCustomDimensionValue(customDimensionId, customDimensionValue): void

Sets a custom dimension value to be used later.

Parameters

| Name | Type | | :—— | :—— | | customDimensionId | string | number | | customDimensionValue | string |

Returns

void

CustomEvent

Table of contents

Functions

trackEvent

trackEvent(category, action, name?, value?, dimensions?): void

Tracks a custom event, e.g. when a visitor interacts with the page

Parameters

| Name | Type | | :—— | :—— | | category | string | | action | string | | name? | string | | value? | number | | dimensions? | Dimensions |

Returns

void

DataLayer

Table of contents

Functions

push

push(data): number

Adds entry to a data layer

Parameters

| Name | Type | | :—— | :—— | | data | any |

Returns

number

GoalConversions

Table of contents

Functions

trackGoal

trackGoal(goalId, conversionValue, dimensions?): void

Tracks manual goal conversion

Parameters

| Name | Type | | :—— | :—— | | goalId | string | number | | conversionValue | number | | dimensions? | Dimensions |

Returns

void

PageViews

Table of contents

Functions

trackPageView

trackPageView(customPageTitle?): void

Tracks a visit on the page that the function was run on

Parameters

| Name | Type | | :—— | :—— | | customPageTitle? | string |

Returns

void

SiteSearch

Table of contents

Functions

trackSiteSearch

trackSiteSearch(keyword, category?, searchCount?, dimensions?): void

Tracks search requests on a website

Parameters

| Name | Type | | :—— | :—— | | keyword | string | | category? | string | | searchCount? | number | | dimensions? | Dimensions |

Returns

void

UserManagement

Functions

getUserId

getUserId(): Promise<string>

The function that will return user ID

Returns

Promise<string>


getVisitorId

getVisitorId(): Promise<string>

Returns 16-character hex ID of the visitor

Returns

Promise<string>


getVisitorInfo

getVisitorInfo(): Promise<VisitorInfo>

Returns visitor information in an array

Returns

Promise<VisitorInfo>


resetUserId

resetUserId(): void

Clears previously set userID, e.g. when visitor logs out

Returns

void


setUserId

setUserId(userId): void

User ID is an additional parameter that allows you to aggregate data. When set up, you will be able to search through sessions by this parameter, filter reports through it or create Multi attribution reports using User ID

Parameters

| Name | Type | | :—— | :—— | | userId | string |

Returns

void

eCommerce

Functions

addEcommerceItem

addEcommerceItem(productSKU, productName, productCategory, productPrice, productQuantity): void

Parameters

| Name | Type | | :—— | :—— | | productSKU | string | | productName | string | | productCategory | string | string[] | | productPrice | number | | productQuantity | number |

Returns

void

Deprecated

Please use the ecommerceAddToCart instead.


clearEcommerceCart

clearEcommerceCart(): void

Returns

void

Deprecated


ecommerceAddToCart

ecommerceAddToCart(products): void

Tracks action of adding products to a cart

Parameters

| Name | Type | | :—— | :—— | | products | Product[] |

Returns

void


ecommerceCartUpdate

ecommerceCartUpdate(products, grandTotal): void

Tracks current state of a cart

Parameters

| Name | Type | | :—— | :—— | | products | Product[] | | grandTotal | string | number |

Returns

void


ecommerceOrder

ecommerceOrder(products, paymentInformation): void

Tracks conversion, including products and payment details

Parameters

| Name | Type | | :—— | :—— | | products | Product[] | | paymentInformation | PaymentInformation |

Returns

void


ecommerceProductDetailView

ecommerceProductDetailView(products): void

Tracks action of viewing product page

Parameters

| Name | Type | | :—— | :—— | | products | Product[] |

Returns

void


ecommerceRemoveFromCart

ecommerceRemoveFromCart(products): void

Tracks action of removing a products from a cart

Parameters

| Name | Type | | :—— | :—— | | products | Product[] |

Returns

void


getEcommerceItems

getEcommerceItems(): Promise<object>

Returns

Promise<object>

Deprecated


removeEcommerceItem

removeEcommerceItem(productSKU): void

Parameters

| Name | Type | | :—— | :—— | | productSKU | string |

Returns

void

Deprecated

Please use the ecommerceRemoveFromCart instead.


setEcommerceView

setEcommerceView(productSKU, productName?, productCategory?, productPrice?): void

Parameters

| Name | Type | | :—— | :—— | | productSKU | string | | productName? | string | | productCategory? | string[] | | productPrice? | string |

Returns

void

Deprecated


trackEcommerceCartUpdate

trackEcommerceCartUpdate(cartAmount): void

Parameters

| Name | Type | | :—— | :—— | | cartAmount | number |

Returns

void

Deprecated

Please use the ecommerceCartUpdate instead.


trackEcommerceOrder

trackEcommerceOrder(orderId, orderGrandTotal, orderSubTotal?, orderTax?, orderShipping?, orderDiscount?): void

Parameters

| Name | Type | | :—— | :—— | | orderId | string | | orderGrandTotal | number | | orderSubTotal? | number | | orderTax? | number | | orderShipping? | number | | orderDiscount? | number |

Returns

void

Deprecated

Please use the ecommerceOrder instead.

Variables

default

Const default: Object

Type declaration

| Name | Type | | :—— | :—— | | getInitScript | typeof PiwikPro.getInitScript | | initialize | typeof PiwikPro.init |

Module: src

Table of contents

Type Aliases

PiwikProProviderProps

Ƭ PiwikProProviderProps: Object

Type declaration

| Name | Type | | :—— | :—— | | children | ReactNode | | containerId | string | | containerUrl | string | | nonce? | string |

Functions

default

default(props, context?): ReactNode

Parameters

| Name | Type | | :—— | :—— | | props | PiwikProProviderProps | | context? | any |

Returns

ReactNode


usePiwikPro

usePiwikPro(): __module

Returns

__module