Angular

This library lets you start collecting data from your web app. It also helps you control which data you collect – like page views, virtual page views, custom events, and more. The library contains modules with methods.

To call methods in Angular, you’ll use CustomEventsService or PageViewsService.

Installation

To install JS library for Angular, follow these steps:

In your project folder, run the following command:

npm install @piwikpro/ngx-piwik-pro

yarn add @piwikpro/ngx-piwik-pro

Add the NgxPiwikProModule module in your highest level app module. Call the forRoot() method by passing your site ID (Where to find it?) and the account address (Example: https://example.piwik.pro/)

import { NgxPiwikProModule } from "@piwikpro/ngx-piwik-pro";

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxPiwikProModule.forRoot("site-id", "account-address", {
      nonce: "nonce-string",
      dataLayerName: 'my-data-layer'
    }),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Note: This method makes sure that collected data is sent to the your account in Piwik PRO and is reported as a corresponding site or app.

Add tracking methods like page views or custom events to your application.
Data will appear in reports in about an hour. Data in the tracker debugger will appear instantly.

Additional setup for SPA

If your web app is built as a single-page application (SPA), you need to track virtual page views. In SPAs, when a user goes from one page to the other, the page doesn’t reload. It loads just once at the beginning of the session. Because of that, page views can’t be recorded in the usual way. You need virtual page views.

To automatically track virtual page views in Angular projects, you need to follow these steps:

Add NgxPiwikProRouterModule on AppModule to enable automatic tracking of Router events.

Example:

import { NgxPiwikProModule, NgxPiwikProRouterModule } from '@piwikpro/ngx-piwik-pro';
...

@NgModule({
...
  imports: [
    ...
    NgxPiwikProModule.forRoot("site-id", "account-address"),
    NgxPiwikProRouterModule
    //  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ]
  })
  export class AppModule {}

Note: The NgxPiwikProRouterModule module subscribes to Router events when the bootstrap component is created. After that, it cleans up any subscriptions related to the previous component when it is destroyed. If you use this module with server-side rendering or multiple bootstrap components, you may get some issues. In that case, we recommend subscribing to the page view events manually.

Additionally, you can use the following include/exclude settings:

{ include: [ ‘/full-uri-match’ ] } – simple route matching
{ include: [ ‘/public/’ ] } – wildcard route matching
{ include: [ /^/public/.*/ ] } – regular expression route matching

Example:

import { NgxPiwikProModule, NgxPiwikProRouterModule } from '@piwikpro/ngx-piwik-pro';
  ...

@NgModule({
  ...
  imports: [
    ...
    NgxPiwikProModule.forRoot("site-id", "account-address"),
    NgxPiwikProRouterModule.forRoot({ include: [...], exclude: [...] })
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ]
})
export class AppModule {}

Setup with nonce

The nonce attribute lets you to allow-list specific elements, such as specific inline scripts or style elements. It helps you avoid using the CSP unsafe-inline directive, which would allow all inline scripts or styles.

To pass your nonce to a script, add it as the third argument when calling the script initialization method.

import { NgxPiwikProModule } from "@piwikpro/ngx-piwik-pro";

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxPiwikProModule.forRoot("container-id", "container-url", {nonce: "nonce-hash"}),
    //                                                         ^^^^^^^^^^^^^^^^^^^^^^^
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Methods

Here’s a list of all JS methods you can use in your Angular project. Descriptions and other information are available after clicking on links.

addDownloadExtensions()
addEcommerceItem() (deprecated)

hasCookies()

isCrossDomainLinkingEnabled()

logAllContentBlocksOnPage()