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
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¶
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
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 |
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
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
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>
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 |
DataLayer¶
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
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 |
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 |
GoalConversions¶
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 |
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 |
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 |
ecommerceAddToCart¶
▸ ecommerceAddToCart(products): void
Tracks action of adding products to a cart
Returns¶
void
ecommerceCartUpdate¶
▸ ecommerceCartUpdate(products, grandTotal): void
Tracks current state of a cart
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
Returns¶
void
ecommerceRemoveFromCart¶
▸ ecommerceRemoveFromCart(products): void
Tracks action of removing a products from a cart
Returns¶
void
removeEcommerceItem¶
▸ removeEcommerceItem(productSKU): void
Parameters¶
| Name | Type |
| :—— | :—— |
| productSKU | string |
setEcommerceView¶
▸ setEcommerceView(productSKU, productName?, productCategory?, productPrice?): void
Parameters¶
| Name | Type |
| :—— | :—— |
| productSKU | string |
| productName? | string |
| productCategory? | string[] |
| productPrice? | string |
trackEcommerceCartUpdate¶
▸ trackEcommerceCartUpdate(cartAmount): void
Parameters¶
| Name | Type |
| :—— | :—— |
| cartAmount | number |
trackEcommerceOrder¶
▸ trackEcommerceOrder(orderId, orderGrandTotal, orderSubTotal?, orderTax?, orderShipping?, orderDiscount?): void
Parameters¶
| Name | Type |
| :—— | :—— |
| orderId | string |
| orderGrandTotal | number |
| orderSubTotal? | number |
| orderTax? | number |
| orderShipping? | number |
| orderDiscount? | number |