@piwikpro/vue-piwik-pro

Piwik PRO Library for VUE

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

Installation

NPM

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

npm install @piwikpro/vue-piwik-pro

Basic setup

In your Vue Project, include the default VuePiwikPro in the highest level application module. ie main. To set up the Piwik PRO Tag Manager container in the app, the easiest way is to call the VuePiwikPro.initialize() method. VuePiwikPro.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).

// main.ts
import VuePiwikPro from '@piwikpro/vue-piwik-pro'

VuePiwikPro.initialize(
  import.meta.env.VITE_PIWIK_PRO_CONTAINER_ID as string,
  import.meta.env.VITE_PIWIK_PRO_CONTAINER_URL as string
)

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.

// main.ts
import VuePiwikPro from '@piwikpro/vue-piwik-pro'

VuePiwikPro.initialize(
  import.meta.env.VITE_PIWIK_PRO_CONTAINER_ID as string,
  import.meta.env.VITE_PIWIK_PRO_CONTAINER_URL as string,
  { nonce: 'nonce-string' }
)

Basic usage

import { PageViews, GoalConversions } from '@piwikpro/vue-piwik-pro'

PageViews.trackPageView()

GoalConversions.trackGoal(1, 100)

Examples of usage

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

---

Table of contents

• ClientConfiguration
• ContentTracking
• CookieManagement
• CrossDomainTracking
• CustomDimensions
• CustomEvent
• DataLayer
• DownloadAndOutlink
• eCommerce
• ErrorTracking
• GoalConversions
• Heartbeat
• Miscellaneous
• PageViews
• SiteSearch
• UserManagement

Type Aliases

• Dimensions
• EcommerceOptions
• Initialize
• InitOptions
• PaymentInformation
• Product
• VisitorInfo

Variables

• default

---

ClientConfiguration

• getDomains
• setDomains

---

getDomains()

getDomains(): Promise<string[]>

Returns list of internal domains (set with "setDomains" function and used in outlink tracking).

Returns

Promise<string[]>

---

setDomains()

setDomains(domains): void

Allows to define a list of internal domains or mobile app URIs. Used in outlink tracking for determining whether a link is an outlink and in cross domain linking for determining which links should have visitor ID parameter injected.

Parameters

Parameter	Type
domains	string[]

Returns

void

---

ContentTracking

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

---

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

Parameter	Type
contentName	string
contentPiece	string
contentTarget	string

Returns

void

---

trackContentImpressionsWithinNode()

trackContentImpressionsWithinNode(domNode): void

Parameters

Parameter	Type
domNode	Node

Returns

void

---

trackContentInteraction()

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

Tracks manual content interaction event

Parameters

Parameter	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

Parameter	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

Parameter	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

• 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

---

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

Parameter	Type
domain	string

Returns

void

---

setCookieNamePrefix()

setCookieNamePrefix(prefix): void

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

Parameters

Parameter	Type
prefix	string

Returns

void

---

setCookiePath()

setCookiePath(path): void

Sets the analytics tracking cookies path

Parameters

Parameter	Type
path	string

Returns

void

---

setReferralCookieTimeout()

setReferralCookieTimeout(seconds): void

Sets the expiration time of referral cookies

Parameters

Parameter	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

Parameter	Type
secure	boolean

Returns

void

---

setSessionCookieTimeout()

setSessionCookieTimeout(seconds): void

Sets the expiration time of session cookies

Parameters

Parameter	Type
seconds	number

Returns

void

---

setVisitorCookieTimeout()

setVisitorCookieTimeout(seconds): void

Sets the expiration time of visitor cookies

Parameters

Parameter	Type
seconds	number

Returns

void

---

setVisitorIdCookie()

setVisitorIdCookie(): void

Sets cookie containing analytics ID in browser

Returns

void

---

CrossDomainTracking

Type Aliases

• LinkDecorator

• VisitorIdGetter

• customCrossDomainLinkDecorator

• customCrossDomainLinkVisitorIdGetter

• disableCrossDomainLinking

• enableCrossDomainLinking

• getCrossDomainLinkingUrlParameter

• isCrossDomainLinkingEnabled

• setCrossDomainLinkingTimeout

---

customCrossDomainLinkDecorator()

customCrossDomainLinkDecorator(decorator): void

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

Parameters

Parameter	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

Parameter	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

Parameter	Type
timeout	number

Returns

void

---

Type Alias: LinkDecorator()

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

Parameters

Parameter	Type
url	string
value	string
name	string

Returns

string | null

---

Type Alias: VisitorIdGetter()

VisitorIdGetter: (url, name) => string

Parameters

Parameter	Type
url	string
name	string

Returns

string

---

CustomDimensions

• deleteCustomDimension
• getCustomDimensionValue
• setCustomDimensionValue

---

deleteCustomDimension()

deleteCustomDimension(customDimensionId): void

Removes a custom dimension with the specified ID.

Parameters

Parameter	Type
customDimensionId	string | number

Returns

void

---

getCustomDimensionValue()

getCustomDimensionValue(customDimensionId): Promise<undefined | string>

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

Parameters

Parameter	Type
customDimensionId	string | number

Returns

Promise<undefined | string>

---

setCustomDimensionValue()

setCustomDimensionValue(customDimensionId, customDimensionValue): void

Sets a custom dimension value to be used later.

Parameters

Parameter	Type
customDimensionId	string | number
customDimensionValue	string

Returns

void

---

CustomEvent

• trackEvent

---

trackEvent()

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

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

Parameters

Parameter	Type
category	string
action	string
name?	string
value?	number
dimensions?	Dimensions

Returns

void

---

DataLayer

Type Aliases

• DataLayerEntry

• push

• setDataLayerName

---

push()

push(data): number

Adds entry to a data layer

Parameters

Parameter	Type
data	DataLayerEntry

Returns

number

---

setDataLayerName()

setDataLayerName(name): void

Parameters

Parameter	Type
name	string

Returns

void

---

Type Alias: DataLayerEntry

DataLayerEntry: Record<string, AnyData>

---

DownloadAndOutlink

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

---

addDownloadExtensions()

addDownloadExtensions(extensions): void

Adds new extensions to the download extensions list

Parameters

Parameter	Type
extensions	string[]

Returns

void

---

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

Parameter	Type
trackAlsoMiddleAndRightClicks?	boolean

Returns

void

---

getLinkTrackingTimer()

getLinkTrackingTimer(): Promise<number>

Returns lock/wait time after a request set by setLinkTrackingTimer

Returns

Promise<number>

---

removeDownloadExtensions()

removeDownloadExtensions(extensions): void

Removes extensions from the download extensions list

Parameters

Parameter	Type
extensions	string[]

Returns

void

---

setDownloadClasses()

setDownloadClasses(classes): void

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

Parameters

Parameter	Type
classes	string[]

Returns

void

---

setDownloadExtensions()

setDownloadExtensions(extensions): void

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

Parameters

Parameter	Type
extensions	string[]

Returns

void

---

setIgnoreClasses()

setIgnoreClasses(classes): void

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

Parameters

Parameter	Type
classes	string[]

Returns

void

---

setLinkClasses()

setLinkClasses(classes): void

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

Parameters

Parameter	Type
classes	string[]

Returns

void

---

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

Parameter	Type
time	number

Returns

void

---

trackLink()

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

Manually tracks outlink or download event with provided values

Parameters

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

Returns

void

---

ErrorTracking

• enableJSErrorTracking
• trackError

---

enableJSErrorTracking()

enableJSErrorTracking(unique?): void

Enables tracking of unhandled JavaScript errors.

Parameters

Parameter	Type	Description
unique?	boolean	track only unique errors

Returns

void

---

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

Parameter	Type
error	Error

Returns

void

---

GoalConversions

• trackGoal

---

trackGoal()

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

Tracks manual goal conversion

Parameters

Parameter	Type
goalId	string | number
conversionValue	number
dimensions?	Dimensions
options?	EcommerceOptions

Returns

void

---

Heartbeat

• disableHeartBeatTimer
• enableHeartBeatTimer

---

disableHeartBeatTimer()

disableHeartBeatTimer(): void

Disables sending heartbeats if they were previously enabled by "enableHeartBeatTimer" function.

Returns

void

---

enableHeartBeatTimer()

enableHeartBeatTimer(delays?): void

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

Parameter	Type
delays?	number[]

Returns

void

---

Miscellaneous

• setTrackingSourceProvider

---

setTrackingSourceProvider()

setTrackingSourceProvider(provider, version): void

Adds metadata about used framework

Parameters

Parameter	Type
provider	string
version	string

Returns

void

---

PageViews

• trackPageView

---

trackPageView()

trackPageView(customPageTitle?): void

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

Parameters

Parameter	Type
customPageTitle?	string

Returns

void

---

SiteSearch

• trackSiteSearch

---

trackSiteSearch()

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

Tracks search requests on a website

Parameters

Parameter	Type
keyword	string
category?	string
searchCount?	number
dimensions?	Dimensions

Returns

void

---

UserManagement

• deanonymizeUser
• getUserId
• getVisitorId
• getVisitorInfo
• resetUserId
• setUserId
• setUserIsAnonymous

---

deanonymizeUser()

deanonymizeUser(): void

Disables anonymous tracking and sends deanonymization event to the Tracker. Recommended method for disabling anonymous tracking.

Returns

void

---

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

Parameter	Type
userId	string

Returns

void

---

setUserIsAnonymous()

setUserIsAnonymous(isAnonymous): void

Enables or disables anonymous tracking (anonymous = without consent). The next emitted event will have anonymous mode set accordingly.

Parameters

Parameter	Type
isAnonymous	boolean

Returns

void

---

eCommerce

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

---

addEcommerceItem()

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

Parameters

Parameter	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, options?): void

Tracks action of adding products to a cart

Parameters

Parameter	Type
products	Product[]
options?	EcommerceOptions

Returns

void

---

ecommerceCartUpdate()

ecommerceCartUpdate(products, grandTotal, options?): void

Tracks current state of a cart

Parameters

Parameter	Type
products	Product[]
grandTotal	string | number
options?	EcommerceOptions

Returns

void

---

ecommerceOrder()

ecommerceOrder(products, paymentInformation, options?): void

Tracks conversion, including products and payment details

Parameters

Parameter	Type
products	Product[]
paymentInformation	PaymentInformation
options?	EcommerceOptions

Returns

void

---

ecommerceProductDetailView()

ecommerceProductDetailView(products, options?): void

Tracks action of viewing product page

Parameters

Parameter	Type
products	Product[]
options?	EcommerceOptions

Returns

void

---

ecommerceRemoveFromCart()

ecommerceRemoveFromCart(products, options?): void

Tracks action of removing a products from a cart

Parameters

Parameter	Type
products	Product[]
options?	EcommerceOptions

Returns

void

---

getEcommerceItems()

getEcommerceItems(): Promise<object>

Returns

Promise<object>

Deprecated

---

removeEcommerceItem()

removeEcommerceItem(productSKU): void

Parameters

Parameter	Type
productSKU	string

Returns

void

Deprecated

Please use the ecommerceRemoveFromCart instead.

---

setEcommerceView()

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

Parameters

Parameter	Type
productSKU	string
productName?	string
productCategory?	string[]
productPrice?	string

Returns

void

Deprecated

---

trackEcommerceCartUpdate()

trackEcommerceCartUpdate(cartAmount): void

Parameters

Parameter	Type
cartAmount	number

Returns

void

Deprecated

Please use the ecommerceCartUpdate instead.

---

trackEcommerceOrder()

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

Parameters

Parameter	Type
orderId	string
orderGrandTotal	number
orderSubTotal?	number
orderTax?	number
orderShipping?	number
orderDiscount?	number

Returns

void

Deprecated

Please use the ecommerceOrder instead.

---

Type Alias: Dimensions

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

---

Type Alias: EcommerceOptions

EcommerceOptions: object

Type declaration

currencyCode?

optional currencyCode: string

Currency code in ISO 4217 format. If not provided, the currency set in app settings will be used instead.

---

Type Alias: InitOptions

InitOptions: object

Type declaration

dataLayerName?

optional dataLayerName: string

Defaults to 'dataLayer'

nonce?

optional nonce: string

---

Type Alias: Initialize()

Initialize: (containerId, containerUrl, nonceOrOptions?) => void

Parameters

Parameter	Type
containerId	string
containerUrl	string
nonceOrOptions?	string | InitOptions

Returns

void

---

Type Alias: PaymentInformation

PaymentInformation: object

Type declaration

discount?

optional discount: number | string

grandTotal

grandTotal: number | string

orderId

orderId: string

shipping?

optional shipping: number | string

subTotal?

optional subTotal: number | string

tax?

optional tax: number | string

---

Type Alias: Product

Product: object

Type declaration

brand?

optional brand: string

category?

optional category: LimitedArrayFiveStrings

customDimensions?

optional customDimensions: Record<number, string>

name?

optional name: string

price?

optional price: number

quantity?

optional quantity: number

sku

sku: string

variant?

optional variant: string

---

Type Alias: VisitorInfo

VisitorInfo: ["0" | "1", string, number, string | number, number, number | "", number | ""]

---

Variable: default

default: object

Type declaration

getInitScript()

getInitScript: (__namedParameters) => string

Parameters

Parameter	Type
__namedParameters	{ containerId: string; containerUrl: string; dataLayerName: string; nonceValue: string; }
__namedParameters.containerId	string
__namedParameters.containerUrl	string
__namedParameters.dataLayerName?	string
__namedParameters.nonceValue?	string

Returns

string

initialize

initialize: Initialize