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('0a0b8661-8c10-4d59-e8fg-1h926ijkl184', 'https://example.piwik.pro');

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

> Previously, we used 'accountName' to configure PiwikProProvider. The parameter has now been replaced by 'container-url'. The 'accountName' parameter is deprecated and will be removed in the future.

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

API

Page Views Service

A page view is the most basic type of a tracked event. It represents a single page viewing action.

Import

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

Methods

  • trackPageView(customPageTitle?: string) - Tracks a visit on the page that the function was run on.

User Management

Import

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

Methods

  • getUserId() - The function that will return user ID.
  • setUserId(userId: string) - 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.
  • resetUserId() - Clears previously set userID, e.g. when visitor logs out.
  • getVisitorId() - Returns 16-character hex ID of the visitor.
  • getVisitorInfo() - Returns visitor information in an array:
    • new visitor flag indicating new (1) or returning (0) visitor
    • visitor ID (UUID)
    • first visit timestamp (Unix epoch time)
    • previous visit count (0 for first visit)
    • current visit timestamp (Unix epoch time)
    • last visit timestamp (Unix epoch time or ‘’ if N/A)
    • last e-commerce order timestamp (Unix epoch time or ‘’ if N/A)

Custom Event

Custom events enable tracking visitor actions that are not predefined in the existing JavaScript Tracking Client API, allowing web analysts to accurately measure and analyze any domain.

Import

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

Methods

  • trackEvent(category: string, action: string, name?: string, value?: number) - Tracks a custom event, e.g. when a visitor interacts with the page.

Site search Service

Site search tracking gives you insights into how visitors interact with the search engine on your website - what they search for and how many results they get back.

Import

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

Methods

  • trackSiteSearch(keyword: string, category?: string, searchCount?: number, dimensions?: Object) - Tracks search requests on a website.

E-Commerce Service

Import

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

// maximum length of the array is 5
type LimitedArrayFiveStrings<T extends string[] = []> = [string, ...T] | [string, string, string, string, string];

type Product = {
  sku: string;
  name?: string;
  category?: LimitedArrayFiveStrings<string[]>;
  price?: number;
  quantity?: number;
  brand?: string;
  variant?: string;
  customDimensions?: object;
};

Methods

  • ecommerceAddToCart(products: Product[]) - Tracks action of adding products to a cart.
  • ecommerceRemoveFromCart(products: Product[]) - Tracks action of removing a products from a cart.
  • ecommerceOrder(products: Product[], paymentInformation: PaymentInformation) - Tracks conversion (including products and payment details).
  • ecommerceCartUpdate(products: Product[], grandTotal: PaymentInformation['grandTotal']) - Tracks current state of a cart.
  • ecommerceProductDetailView(products: Product[]) - Tracks product or category view. Must be followed by a page view.
Example usage
const { eCommerce } = usePiwikPro()

const products = [{
  sku: 'sku-4',
  name: 'Product 4',
  category: ['product-category', 'product-category-4'],
  brand: 'Brand 4',
  variant: 'Variant 4',
  price: 39.96,
  customDimensions: {
    dimension1: 'value1',
    dimension2: 'value2'
  }
}]

const subTotal = products.reduce((acc, product) => {
  if (product.price) {
    return acc + product.price
  }
  return acc
}, 0)

const tax = 10
const shipping = 4
const discount = 5

const paymentInformation: PaymentInformation = {
  orderId: 'order-123',
  grandTotal: subTotal + tax + shipping - discount,
  subTotal,
  tax,
  shipping,
  discount
}

eCommerce.ecommerceAddToCart(products)

eCommerce.ecommerceRemoveFromCart(products)

ecommerce.ecommerceOrder(products, paymentInformation)

eCommerce.ecommerceCartUpdate(products, paymentInformation.grandTotal)

eCommerce.ecommerceProductDetailView(products)

Content Tracking Service

Content Tracking lets you track what content is visible on your site and how users interact with it.

Import

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

Methods

  • trackContentImpression(contentName: string, contentPiece: string, contentTarget: string) - Tracks manual content impression event.
  • trackContentInteraction(contentInteraction: string, contentName: string, contentPiece: string, contentTarget: string) - Tracks manual content interaction event.

Goal Conversions

Goals let you define important actions registered in your application and track conversions when the conditions for the action are fulfilled.

Import

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

Methods

  • trackGoal(goalId: number | string, conversionValue: number, dimensions?: Object) - Tracks manual goal conversion.

Custom Dimensions

Import

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

Methods

  • setCustomDimensionValue(customDimensionId: string | number, customDimensionValue: string) - Sets a custom dimension value to be used later.
  • deleteCustomDimension(customDimensionId: string) - Removes a custom dimension with the specified ID.
  • getCustomDimensionValue(customDimensionId: string | number) - Returns the value of a custom dimension with the specified ID.

Data Layer

A data layer is a data structure on your site or app where you can store data and access it with tools like Tag Manager. You can include any data you want in your data layer.

Import

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

Methods

  • push(dataLayerObject: Object) - Adds an event to a data layer.