Piwik PRO Library for Nuxt

Dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager, Piwik PRO Consent Manager and Piwik PRO tracking client in Nuxt applications.

Installation

NPM

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

npm install @piwikpro/nuxt-piwik-pro

Basic setup

In your Nuxt Project, include @piwikpro/nuxt-piwik-pro as a nuxt module in nuxt.config.ts file. To set up the Piwik PRO Tag Manager container in the app, pass configuration object as a module inline-options. Configuration options can be found below.

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

Usage

Piwik PRO container will be initialized under the hood by @piwikpro/nuxt-piwik-pro module itself. Module also inject client-only plugin to Nuxt application instance which allow you to use all Piwik PRO services globally as a part of Nuxt context returned from useNuxtApp() composable as a $piwikPRO.

Remember that Piwik PRO is a client-only library. This means you won't have access to any of its services 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 use Piwik PRO services safety, you can 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 .ts file in /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 `<ClientOnly/>` Nuxt component

Alternatively, you can wrap Component with Piwik PRO usage by <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 client-only page

Or if you want use PiwikPRO services directly in Page component, you can add client to its file name.

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

Examples of usage

Please explore the ./example directory to get to know how to use this package with a specific examples and it's various methods.

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`

PiwikPROHandler

Ƭ PiwikPROHandler<T>: (piwikPRO: PiwikPROServicesType) => T | Promise<T>

Type parameters

Name	Type
`T`	`unknown`

Type declaration

▸ (piwikPRO): T | Promise<T>

Parameters

Name	Type
`piwikPRO`	`PiwikPROServicesType`

Returns

T | Promise<T>

PiwikPROServicesType

Ƭ PiwikPROServicesType: typeof PiwikPROServices

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

PiwikPRO

• Const PiwikPRO: Object

Type declaration

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

default

▸ default(this, inlineOptions, nuxt): _ModuleSetupReturn

Parameters

Name	Type
`this`	`void`
`inlineOptions`	`PluginArgs`
`nuxt`	`Nuxt`

Returns

_ModuleSetupReturn

ClientConfiguration

ContentTracking

CookieManagement

CrossDomainTracking

Type Aliases

LinkDecorator

Ƭ LinkDecorator: (url: string, value: string, name: string) => string | null

Type declaration

▸ (url, value, name): string | null

Parameters

Name	Type
`url`	`string`
`value`	`string`
`name`	`string`

Returns

string | null

VisitorIdGetter

Ƭ VisitorIdGetter: (url: string, name: string) => string

Type declaration

▸ (url, name): string

Parameters

Name	Type
`url`	`string`
`name`	`string`

Returns

string

customCrossDomainLinkDecorator

▸ customCrossDomainLinkDecorator(decorator): void

Sets custom cross domains URL decorator for injecting visitor ID into URLs. Used when cross domain linking is enabled.

Parameters

Name	Type
`decorator`	`LinkDecorator`

Returns

void

customCrossDomainLinkVisitorIdGetter

▸ customCrossDomainLinkVisitorIdGetter(getter): void

Sets custom cross domain URL parser for extracting visitor ID from URLs. Should extract data injected by URL decorator. The getter should return visitor ID extracted from page URL.

Parameters

Name	Type
`getter`	`VisitorIdGetter`

Returns

void

disableCrossDomainLinking

▸ disableCrossDomainLinking(): void

Disables cross domain linking.

Returns

void

enableCrossDomainLinking

▸ enableCrossDomainLinking(): void

Enables cross domain linking. Visitors across domains configured with "setDomains" function will be linked by passing visitor ID parameter in links.

Returns

void

getCrossDomainLinkingUrlParameter

▸ getCrossDomainLinkingUrlParameter(): Promise<string>

Returns the name of a cross domain URL parameter (query parameter by default) holding visitor ID. This is "pk_vid" by default.

Returns

Promise<string>

isCrossDomainLinkingEnabled

▸ isCrossDomainLinkingEnabled(): Promise<boolean>

Returns boolean telling whether cross domain linking is enabled.

Returns

Promise<boolean>

setCrossDomainLinkingTimeout

▸ setCrossDomainLinkingTimeout(timeout): void

Changes the time in which two visits across domains will be linked. The default timeout is 180 seconds (3 minutes).

Parameters

Name	Type
`timeout`	`number`

Returns

void

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

Heartbeat

When a visitor is not producing any events (e.g. because they are reading an article or watching a video), we don’t know if they are still on the page. This might skew page statistics, e.g. time on page value. Heartbeat timer allows us to determine how much time visitors spend on a page by sending heartbeats to the Tracker as long as the page is in focus.

Parameters

Name	Type
`delays?`	`number`[]

Returns

void

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github/workflows		.github/workflows
docs		docs
example		example
scripts		scripts
src		src
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTION.md		CONTRIBUTION.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
`products`	`Product`[]
`paymentInformation`	`PaymentInformation`

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
`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/nuxt-piwik-pro

Folders and files

Latest commit

History

Repository files navigation

Piwik PRO Library for Nuxt

Installation

NPM

Basic setup

Configuration options

Nonce

Usage

Remember that Piwik PRO is a client-only library. This means you won't have access to any of its services on the server side.

Usage with usePiwikPro()

export usePiwikPro() as a Nuxt composable

Usage with <ClientOnly/> Nuxt component

Usage in client-only page

Examples of usage

Table of contents

Namespaces

Type Aliases

Variables

Type Aliases

Dimensions

InitOptions

Type declaration

PaymentInformation

Type declaration

PiwikPROHandler

Type parameters

Type declaration

Parameters

Returns

PiwikPROServicesType

Product

Type declaration

VisitorInfo

Variables

PiwikPRO

Type declaration

default

Parameters

Returns

ClientConfiguration

Table of contents

getDomains

Returns

setDomains

Parameters

Returns

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

Usage with `usePiwikPro()`

export `usePiwikPro()` as a Nuxt composable

Usage with `<ClientOnly/>` Nuxt component