Piwik PRO Library for Angular

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

Installation

NPM

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

npm install @piwikpro/ngx-piwik-pro

Basic setup

In your Angular Project, include the NgxPiwikProModule in the highest level application module. ie AddModule. To set up the Piwik PRO Tag Manager container in the app, the easiest way is to call the forRoot() method. In the arguments, pass your app ID and your account URL as parameters (marked ‘container-id’ and ‘container-url’ in the example below).

import { NgxPiwikProModule } from '@piwikpro/ngx-piwik-pro';  
  
@NgModule({  
  declarations: [  
    AppComponent  
  ],  
  imports: [  
    BrowserModule,  
    NgxPiwikProModule.forRoot('container-id', 'container-url')  
  // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  
  ],  
  providers: [],  
  bootstrap: [AppComponent]  
})  
export class AppModule { }  

Set up the Routing Module

We provide a second Module Dependency to configure Router Event Bindings and perform automatic page views every time your application navigates to another page.

Add NgxPiwikProRouterModule on AppModule to enable auto track Router events.

IMPORTANT: This Module subscribes to Router events when the bootstrap component is created, and then cleans up any subscriptions related to previous component when it is destroyed. You may get some issues if using this module with server side rendering or multiple bootstrap components. If that’s the case, we recommend subscribing to the page view events manually.

import { NgxPiwikProModule, NgxPiwikProRouterModule } from '@piwikpro/ngx-piwik-pro';  
...  
  
@NgModule({  
  ...  
  imports: [  
    ...  
    NgxPiwikProModule.forRoot('container-id'),  
    NgxPiwikProRouterModule  
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  
  ]  
})  
export class AppModule {}  

Advanced setup for the Routing Module

You can customize some rules to include/exclude routes on NgxPiwikProRouterModule. The include/exclude settings allow:

  • Simple route matching: { include: [ '/full-uri-match' ] };
  • Wildcard route matching: { include: [ '*/public/*' ] };
  • Regular Expression route matching: { include: [ /^\/public\/.*/ ] };
import { NgxPiwikProModule, NgxPiwikProRouterModule } from '@piwikpro/ngx-piwik-pro';  
...  
  
@NgModule({  
  ...  
  imports: [  
    ...  
    NgxPiwikProModule.forRoot('container-id'),  
    NgxPiwikProRouterModule.forRoot({ include: [...], exclude: [...] })  
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  
  ]  
})  
export class AppModule {}  

Piwik PRO Services

Send Custom Events

@Component( ... )  
export class TestFormComponent {  
  
  constructor(  
    private customEventsService: CustomEventsService  
  ) {}  
  
  onUserInputName() {  
    ...  
    this.customEventsService.trackEvent('user_register_form', 'enter_name', 'Name', 'Value');   
  }  
  
  onUserInputEmail() {  
    ...
    this.customEventsService.trackEvent('user_register_form', 'enter_email', 'Email', 'Value');    
  }  
  
  onSubmit() {  
    ...  
    this.customEventsService.trackEvent('user_register_form', 'submit', 'Sent');  
  }  
}

Send page views and virtual page views

@Component(...)  
export class TestPageComponent implements OnInit {  
  
  constructor(  
    protected pageViewsService: PageViewsService  
  ) {}  
  
  ngOnInit() {  
    this.pageViewsService.trackPageView('Title')  
  }  
  
}  

API

Page Views Service

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

Methods

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

User Management

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 Events

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.

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.

Methods

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

E-Commerce Service

Methods

  • addEcommerceItem(productSKU: string, productName: string, productCategory: string | string[], productPrice: number, productQuantity: number) - Adds a product to a virtual shopping cart. If a product with the same SKU is in the cart, it will be removed first. Does not send any data to the Collecting & Processing Pipeline.
  • removeEcommerceItem(productSKU: string) - Removes a product with the provided SKU from a virtual shopping cart. If multiple units of that product are in the virtual cart, all of them will be removed. Does not send any data to the Collecting & Processing Pipeline.
  • clearEcommerceCart() - Removes all items from a virtual shopping cart. Does not send any data to the Collecting & Processing Pipeline.
  • getEcommerceItems() - Returns a copy of items from a virtual shopping cart. Does not send any data to the Collecting & Processing Pipeline
  • trackEcommerceOrder() - Tracks a successfully placed e-commerce order with items present in a virtual cart (registered using addEcommerceItem).
  • trackEcommerceCartUpdate(cartAmount: number) - Tracks items present in a virtual shopping cart (registered with addEcommerceItem)
  • setEcommerceView(productSKU: string, productName?: string, productCategory?: string[], productPrice?: string) - Tracks product or category view. Must be followed by a page view.

Content Tracking Service

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

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.

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

Custom Dimensions

  • 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.