Piwik PRO Tracking Base Library

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

Installation

NPM

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

npm install @piwikpro/tracking-base-library

Basic setup

In your project, include the default PiwikPro in the highest level application module. ie index. To set up the Piwik PRO Tag Manager container in the app, the easiest way is to call the PiwikPro. initialize() method. PiwikPro.initialize() must be initialized using this function before any of the other tracking functions will record any data.

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

import PiwikPro from '@piwikpro/tracking-base-library';

PiwikPro.initialize('container-id', 'container-url');

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 an option to the third argument when calling the script initialization method.

import PiwikPro from '@piwikpro/tracking-base-library';

PiwikPro.initialize('container-id', 'container-url', { nonce: 'nonce-string' });

Custom Data Layer Name

import PiwikPro from '@piwikpro/tracking-base-library';

PiwikPro.initialize('container-id', 'container-url', { dataLayerName: 'my-data-layer' });

Basic usage

import { PageViews, GoalConversions } from "@piwikpro/tracking-base-library"

PageViews.trackPageView();

GoalConversions.trackGoal(1, 100);

Table of contents

Namespaces

• ContentTracking
• CookieManagement
• CustomDimensions
• CustomEvent
• DataLayer
• DownloadAndOutlink
• ErrorTracking
• GoalConversions
• PageViews
• SiteSearch
• UserManagement
• eCommerce

Type Aliases

• Dimensions
• InitOptions
• PaymentInformation
• Product
• VisitorInfo

Variables

• default

Type Aliases

Dimensions

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

Defined in

interfaces/utils.ts:11

InitOptions

Ƭ InitOptions: Object

Type declaration

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

Defined in

core/index.ts:4

PaymentInformation

Ƭ PaymentInformation: Object

Type declaration

| Name | Type | | :------ | :------ | | discount? | number | string | | grandTotal | number | string | | orderId | string | | shipping? | number | string | | subTotal? | number | string | | tax? | number | string |

Defined in

interfaces/payment.ts:1

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 |

Defined in

interfaces/product.ts:3

VisitorInfo

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

Defined in

interfaces/visitorInfo.ts:1

Variables

default

• default: Object

Type declaration

| Name | Type | | :------ | :------ | | getInitScript | (__namedParameters: { containerId: string ; containerUrl: string ; dataLayerName?: string }) => string | | initialize | (containerId: string, containerUrl: string, nonce?: string) => void(containerId: string, containerUrl: string, options?: InitOptions) => void |

Defined in

index.ts:22

ContentTracking

Table of contents

• logAllContentBlocksOnPage
• trackAllContentImpressions
• trackContentImpression
• trackContentImpressionsWithinNode
• trackContentInteraction
• trackContentInteractionNode
• trackVisibleContentImpressions

logAllContentBlocksOnPage

▸ logAllContentBlocksOnPage(): void

Print all content blocks to the console for debugging purposes

Returns

void

Defined in

services/content-tracking/contentTracking.service.ts:49

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

Defined in

services/content-tracking/contentTracking.service.ts:9

trackContentImpression

▸ trackContentImpression(contentName, contentPiece, contentTarget): void

Parameters

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

Returns

void

Defined in

services/content-tracking/contentTracking.service.ts:33

trackContentImpressionsWithinNode

▸ trackContentImpressionsWithinNode(domNode): void

Parameters

| Name | Type | | :------ | :------ | | domNode | Node |

Returns

void

Defined in

services/content-tracking/contentTracking.service.ts:29

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

Defined in

services/content-tracking/contentTracking.service.ts:76

trackContentInteractionNode

▸ trackContentInteractionNode(domNode, contentInteraction?): void

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

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | domNode | Node | undefined | Node marked as content block or containing content blocks. If content block can’t be found, nothing will tracked. | | contentInteraction | string | 'Unknown' | Name of interaction (e.g. "click") |

Returns

void

Defined in

services/content-tracking/contentTracking.service.ts:58

trackVisibleContentImpressions

▸ trackVisibleContentImpressions(checkOnScroll?, watchInterval?): void

Scans DOM for all visible content blocks and tracks impressions

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | checkOnScroll | boolean | true | Whether to scan for visible content on scroll event | | watchInterval | number | 750 | Delay, in milliseconds, between scans for new visible content. Periodic checks can be disabled by passing 0 |

Returns

void

Defined in

services/content-tracking/contentTracking.service.ts:18

CookieManagement

Table of contents

• deleteCookies
• disableCookies
• enableCookies
• getConfigVisitorCookieTimeout
• getCookieDomain
• getCookiePath
• getSessionCookieTimeout
• hasCookies
• setCookieDomain
• setCookieNamePrefix
• setCookiePath
• setReferralCookieTimeout
• setSecureCookie
• setSessionCookieTimeout
• setVisitorCookieTimeout
• setVisitorIdCookie

deleteCookies

▸ deleteCookies(): void

Deletes existing tracking cookies on the next page view

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:22

disableCookies

▸ disableCookies(): void

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

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:8

enableCookies

▸ enableCookies(): void

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

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:15

getConfigVisitorCookieTimeout

▸ getConfigVisitorCookieTimeout(): Promise<number>

Returns expiration time of visitor cookies (in milliseconds)

Returns

Promise<number>

Defined in

services/cookie-management/cookieManagement.service.ts:86

getCookieDomain

▸ getCookieDomain(): Promise<string>

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

Returns

Promise<string>

Defined in

services/cookie-management/cookieManagement.service.ts:48

getCookiePath

▸ getCookiePath(): Promise<string>

Returns the analytics tracking cookies path

Returns

Promise<string>

Defined in

services/cookie-management/cookieManagement.service.ts:67

getSessionCookieTimeout

▸ getSessionCookieTimeout(): Promise<number>

Returns expiration time of session cookies

Returns

Promise<number>

Defined in

services/cookie-management/cookieManagement.service.ts:112

hasCookies

▸ hasCookies(): Promise<boolean>

Returns true if cookies are enabled in this browser

Returns

Promise<boolean>

Defined in

services/cookie-management/cookieManagement.service.ts:29

setCookieDomain

▸ setCookieDomain(domain): void

Sets the domain for the analytics tracking cookies

Parameters

| Name | Type | | :------ | :------ | | domain | string |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:138

setCookieNamePrefix

▸ setCookieNamePrefix(prefix): void

Sets the prefix for analytics tracking cookies. Default is "pk".

Parameters

| Name | Type | | :------ | :------ | | prefix | string |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:131

setCookiePath

▸ setCookiePath(path): void

Sets the analytics tracking cookies path

Parameters

| Name | Type | | :------ | :------ | | path | string |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:145

setReferralCookieTimeout

▸ setReferralCookieTimeout(seconds): void

Sets the expiration time of referral cookies

Parameters

| Name | Type | | :------ | :------ | | seconds | number |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:105

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

Defined in

services/cookie-management/cookieManagement.service.ts:152

setSessionCookieTimeout

▸ setSessionCookieTimeout(seconds): void

Sets the expiration time of session cookies

Parameters

| Name | Type | | :------ | :------ | | seconds | number |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:166

setVisitorCookieTimeout

▸ setVisitorCookieTimeout(seconds): void

Sets the expiration time of visitor cookies

Parameters

| Name | Type | | :------ | :------ | | seconds | number |

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:159

setVisitorIdCookie

▸ setVisitorIdCookie(): void

Sets cookie containing analytics ID in browser

Returns

void

Defined in

services/cookie-management/cookieManagement.service.ts:173

CustomDimensions

Table of contents

• deleteCustomDimension
• getCustomDimensionValue
• setCustomDimensionValue

deleteCustomDimension

▸ deleteCustomDimension(customDimensionId): void

Removes a custom dimension with the specified ID.

Parameters

| Name | Type | | :------ | :------ | | customDimensionId | string | number |

Returns

void

Defined in

services/custom-dimensions/customDimensions.service.ts:21

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>

Defined in

services/custom-dimensions/customDimensions.service.ts:30

setCustomDimensionValue

▸ setCustomDimensionValue(customDimensionId, customDimensionValue): void

Sets a custom dimension value to be used later.

Parameters

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

Returns

void

Defined in

services/custom-dimensions/customDimensions.service.ts:8

CustomEvent

Table of contents

• trackEvent

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

Defined in

services/custom-events/customEvents.service.ts:8

DataLayer

Table of contents

Type Aliases

• DataLayerEntry

• push

• setDataLayerName

Type Aliases

DataLayerEntry

Ƭ DataLayerEntry: Record<string, AnyData>

Defined in

services/dataLayer/dataLayer.service.ts:11

push

▸ push(data): number

Adds entry to a data layer

Parameters

| Name | Type | | :------ | :------ | | data | DataLayerEntry |

Returns

number

Defined in

services/dataLayer/dataLayer.service.ts:15

setDataLayerName

▸ setDataLayerName(name): void

Parameters

| Name | Type | | :------ | :------ | | name | string |

Returns

void

Defined in

services/dataLayer/dataLayer.service.ts:7

DownloadAndOutlink

Table of contents

• addDownloadExtensions
• enableLinkTracking
• getLinkTrackingTimer
• removeDownloadExtensions
• setDownloadClasses
• setDownloadExtensions
• setIgnoreClasses
• setLinkClasses
• setLinkTrackingTimer
• trackLink

addDownloadExtensions

▸ addDownloadExtensions(extensions): void

Adds new extensions to the download extensions list

Parameters

| Name | Type | | :------ | :------ | | extensions | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:61

enableLinkTracking

▸ enableLinkTracking(trackAlsoMiddleAndRightClicks?): void

Enables automatic link tracking. If called with true, left, right and middle clicks on links will be treated as opening a link. Opening a links to an external site (different domain) creates an outlink event. Opening a link to a downloadable file creates a download event

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | trackAlsoMiddleAndRightClicks | boolean | true |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:30

getLinkTrackingTimer

▸ getLinkTrackingTimer(): Promise<number>

Returns lock/wait time after a request set by setLinkTrackingTimer

Returns

Promise<number>

Defined in

services/download-and-outlink/download-and-outlink.service.ts:89

removeDownloadExtensions

▸ removeDownloadExtensions(extensions): void

Removes extensions from the download extensions list

Parameters

| Name | Type | | :------ | :------ | | extensions | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:68

setDownloadClasses

▸ setDownloadClasses(classes): void

Sets a list of class names that indicate whether a list is a download and not an outlink

Parameters

| Name | Type | | :------ | :------ | | classes | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:47

setDownloadExtensions

▸ setDownloadExtensions(extensions): void

Overwrites the list of file extensions indicating that a link is a download

Parameters

| Name | Type | | :------ | :------ | | extensions | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:54

setIgnoreClasses

▸ setIgnoreClasses(classes): void

Set a list of class names that indicate a link should not be tracked

Parameters

| Name | Type | | :------ | :------ | | classes | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:108

setLinkClasses

▸ setLinkClasses(classes): void

Sets a list of class names that indicate whether a link is an outlink and not download

Parameters

| Name | Type | | :------ | :------ | | classes | string[] |

Returns

void

Defined in

services/download-and-outlink/download-and-outlink.service.ts:40

setLinkTrackingTimer

▸ setLinkTrackingTimer(time): void

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

Defined in

services/download-and-outlink/download-and-outlink.service.ts:82

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

Defined in

services/download-and-outlink/download-and-outlink.service.ts:9

ErrorTracking

Table of contents

• enableJSErrorTracking
• trackError

enableJSErrorTracking

▸ enableJSErrorTracking(unique?): void

Enables tracking of unhandled JavaScript errors.

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | unique | boolean | true | track only unique errors |

Returns

void

Defined in

services/error-tracking/errorTracking.service.ts:8

trackError

▸ trackError(error): void

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

Defined in

services/error-tracking/errorTracking.service.ts:16

GoalConversions

Table of contents

• trackGoal

trackGoal

▸ trackGoal(goalId, conversionValue, dimensions?): void

Tracks manual goal conversion

Parameters

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

Returns

void

Defined in

services/goal-conversions/goal-conversions.service.ts:8

PageViews

Table of contents

• trackPageView

trackPageView

▸ trackPageView(customPageTitle?): void

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

Parameters

| Name | Type | | :------ | :------ | | customPageTitle? | string |

Returns

void

Defined in

services/pageViews/pageViews.service.ts:7

SiteSearch

Table of contents

• trackSiteSearch

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

Defined in

services/site-search/site-search.service.ts:8

UserManagement

Table of contents

• getUserId
• getVisitorId
• getVisitorInfo
• resetUserId
• setUserId

getUserId

▸ getUserId(): Promise<string>

The function that will return user ID

Returns

Promise<string>

Defined in

services/user-management/userManagement.service.ts:9

getVisitorId

▸ getVisitorId(): Promise<string>

Returns 16-character hex ID of the visitor

Returns

Promise<string>

Defined in

services/user-management/userManagement.service.ts:44

getVisitorInfo

▸ getVisitorInfo(): Promise<VisitorInfo>

Returns visitor information in an array

Returns

Promise<VisitorInfo>

Defined in

services/user-management/userManagement.service.ts:63

resetUserId

▸ resetUserId(): void

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

Returns

void

Defined in

services/user-management/userManagement.service.ts:37

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

Defined in

services/user-management/userManagement.service.ts:30

eCommerce

Table of contents

• addEcommerceItem
• clearEcommerceCart
• ecommerceAddToCart
• ecommerceCartUpdate
• ecommerceOrder
• ecommerceProductDetailView
• ecommerceRemoveFromCart
• getEcommerceItems
• removeEcommerceItem
• setEcommerceView
• trackEcommerceCartUpdate
• trackEcommerceOrder

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.

Defined in

services/e-commerce/e-commerce.service.ts:14

clearEcommerceCart

▸ clearEcommerceCart(): void

Returns

void

Deprecated

Defined in

services/e-commerce/e-commerce.service.ts:130

ecommerceAddToCart

▸ ecommerceAddToCart(products): void

Tracks action of adding products to a cart

Parameters

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

Returns

void

Defined in

services/e-commerce/e-commerce.service.ts:34

ecommerceCartUpdate

▸ ecommerceCartUpdate(products, grandTotal): void

Tracks current state of a cart

Parameters

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

Returns

void

Defined in

services/e-commerce/e-commerce.service.ts:113

ecommerceOrder

▸ ecommerceOrder(products, paymentInformation): void

Tracks conversion, including products and payment details

Parameters

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

Returns

void

Defined in

services/e-commerce/e-commerce.service.ts:96

ecommerceProductDetailView

▸ ecommerceProductDetailView(products): void

Tracks action of viewing product page

Parameters

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

Returns

void

Defined in

services/e-commerce/e-commerce.service.ts:123

ecommerceRemoveFromCart

▸ ecommerceRemoveFromCart(products): void

Tracks action of removing a products from a cart

Parameters

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

Returns

void

Defined in

services/e-commerce/e-commerce.service.ts:48

getEcommerceItems

▸ getEcommerceItems(): Promise<object>

Returns

Promise<object>

Deprecated

Defined in

services/e-commerce/e-commerce.service.ts:55

removeEcommerceItem

▸ removeEcommerceItem(productSKU): void

Parameters

| Name | Type | | :------ | :------ | | productSKU | string |

Returns

void

Deprecated

Please use the ecommerceRemoveFromCart instead.

Defined in

services/e-commerce/e-commerce.service.ts:41

setEcommerceView

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

Parameters

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

Returns

void

Deprecated

Defined in

services/e-commerce/e-commerce.service.ts:137

trackEcommerceCartUpdate

▸ trackEcommerceCartUpdate(cartAmount): void

Parameters

| Name | Type | | :------ | :------ | | cartAmount | number |

Returns

void

Deprecated

Please use the ecommerceCartUpdate instead.

Defined in

services/e-commerce/e-commerce.service.ts:106

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.

Defined in

services/e-commerce/e-commerce.service.ts:74