Skip to content
/ react-piwik-pro Public

A dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in React-based applications.

License

MIT license
1 star 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

PiwikPRO/react-piwik-pro

BranchesTags

Repository files navigation

Piwik PRO Library for React

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

Installation

NPM

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

npm install @piwikpro/react-piwik-pro

Basic setup

In your React 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/react-piwik-pro';

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

ReactDOM.render(<App />, document.getElementById('root'))

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.

import PiwikPro from '@piwikpro/react-piwik-pro';

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

ReactDOM.render(<App />, document.getElementById('root'))

Custom Data Layer name

import PiwikPro from '@piwikpro/react-piwik-pro';

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

ReactDOM.render(<App />, document.getElementById('root'))

Piwik PRO Services

Send Custom Events

import { CustomEvent } from '@piwikpro/react-piwik-pro'

export class TestFormComponent {

  onUserInputName() {
    ...
    CustomEvent.trackEvent('user_register_form', 'enter_name', 'Name', 'Value');
  }

  onUserInputEmail() {
    ...
    CustomEvent.trackEvent('user_register_form', 'enter_email', 'Email', 'Value');
  }

  onSubmit() {
    ...
    CustomEvent.trackEvent('user_register_form', 'submit', 'Sent');
  }
}

Send page views and virtual page views

import { PageViews } from '@piwikpro/react-piwik-pro';
...

const App = () => {

  PageViews.trackPageView('optional title');

  return ...;
}

export default App

Send an event with Data Layer

import { DataLayer } from '@piwikpro/react-piwik-pro';
...

const App = () => {

  DataLayer.push({ event: 'test-event' });

  return ...;
}

export default App

Table of contents

Namespaces

Type Aliases

Variables

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

Table of contents

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

Table of contents

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

Table of contents

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

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

Type Aliases

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

Table of contents

addDownloadExtensions

▸ addDownloadExtensions(extensions): void

Adds new extensions to the download extensions list

Parameters
Name 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
Name 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
Name 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
Name Type
classes string[]
Returns

void

setDownloadExtensions

▸ setDownloadExtensions(extensions): void

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

Parameters
Name Type
extensions string[]
Returns

void

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

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

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

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

Table of contents

enableJSErrorTracking

▸ enableJSErrorTracking(unique?): void

Enables tracking of unhandled JavaScript errors.

Parameters
Name 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
Name Type
error Error
Returns

void

GoalConversions

Table of contents

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

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

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

Table of contents

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

Table of contents

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.

About

A dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in React-based applications.

Topics

team-integrations

Resources

Readme

License

MIT license

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

5 watching

Forks

2 forks
Report repository

Releases 16

2.1.3 Latest
Dec 13, 2024
+ 15 releases

Packages

No packages published

Contributors 5

Languages