2.0.1 • Published 2 months ago

@piwikpro/ngx-piwik-pro v2.0.1

Weekly downloads
-
License
MIT
Repository
github
Last release
2 months ago

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 {}

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 { NgxPiwikProModule } from "@piwikpro/ngx-piwik-pro";

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxPiwikProModule.forRoot("container-id", "container-url", "nonce-hash"),
    // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ],
  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 {}
Track of PageViews from the first visit to the site.

The default 'Data Collection' settings assume that the 'Track page views in a single-page application' option is set to true. You will find an iformation that if this option is enabled, we will record every change in the state of the browser history on the page and report it as a page view in the reports. You need to know that this option should be disabled if you want to use the ngx-piwik-pro library.

This setting can be found in: Administration -> Sites & Apps -> (choose your site or apps ) -> Data Collection -> Track page views in a single-page application

In order to work according to the default Data Collection settings, the library skips the first PageViews so as not to cause duplicate entries. However, if you have taken care to disable the above settings, you should also pass the following settings to the library.

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

@NgModule({
  ...
  imports: [
    ...
    NgxPiwikProModule.forRoot('container-id'),
    NgxPiwikProRouterModule.forRoot({ skipFirstPageView: false })
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ]
})
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')
  }

}

Send an event with Data Layer

@Component(...)
export class TestPageComponent implements OnInit {

  constructor(
    protected dataLayerService: DataLayerService
  ) {}

  ngOnInit() {
    this.dataLayerService.push({ event: 'test-event' })
  }

}


Namespaces

Type Aliases

Variables


ContentTracking


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

contentName: string

contentPiece: string

contentTarget: string

Returns

void


trackContentImpressionsWithinNode()

trackContentImpressionsWithinNode(domNode): void

Parameters

domNode: Node

Returns

void


trackContentInteraction()

trackContentInteraction(contentInteraction, contentName, contentPiece, contentTarget): void

Tracks manual content interaction event

Parameters

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

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

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


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

domain: string

Returns

void


setCookieNamePrefix()

setCookieNamePrefix(prefix): void

Sets the prefix for analytics tracking cookies. Default is "pk".

Parameters

prefix: string

Returns

void


setCookiePath()

setCookiePath(path): void

Sets the analytics tracking cookies path

Parameters

path: string

Returns

void


setReferralCookieTimeout()

setReferralCookieTimeout(seconds): void

Sets the expiration time of referral cookies

Parameters

seconds: number

Returns

void


setSecureCookie()

setSecureCookie(secure): void

Toggles the secure cookie flag on all first party cookies (if you are using HTTPS)

Parameters

secure: boolean

Returns

void


setSessionCookieTimeout()

setSessionCookieTimeout(seconds): void

Sets the expiration time of session cookies

Parameters

seconds: number

Returns

void


setVisitorCookieTimeout()

setVisitorCookieTimeout(seconds): void

Sets the expiration time of visitor cookies

Parameters

seconds: number

Returns

void


setVisitorIdCookie()

setVisitorIdCookie(): void

Sets cookie containing analytics ID in browser

Returns

void


CustomDimensions


deleteCustomDimension()

deleteCustomDimension(customDimensionId): void

Removes a custom dimension with the specified ID.

Parameters

customDimensionId: string | number

Returns

void


getCustomDimensionValue()

getCustomDimensionValue(customDimensionId): Promise\<string | undefined>

Returns the value of a custom dimension with the specified ID.

Parameters

customDimensionId: string | number

Returns

Promise\<string | undefined>


setCustomDimensionValue()

setCustomDimensionValue(customDimensionId, customDimensionValue): void

Sets a custom dimension value to be used later.

Parameters

customDimensionId: string | number

customDimensionValue: string

Returns

void


CustomEvent


trackEvent()

trackEvent(category, action, name?, value?, dimensions?): void

Tracks a custom event, e.g. when a visitor interacts with the page

Parameters

category: string

action: string

name?: string

value?: number

dimensions?: Dimensions

Returns

void


DataLayer

Type Aliases


push()

push(data): number

Adds entry to a data layer

Parameters

data: DataLayerEntry

Returns

number


setDataLayerName()

setDataLayerName(name): void

Parameters

name: string

Returns

void


Type Alias: DataLayerEntry

DataLayerEntry: Record\<string, AnyData>


DownloadAndOutlink


addDownloadExtensions()

addDownloadExtensions(extensions): void

Adds new extensions to the download extensions list

Parameters

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

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

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

classes: string[]

Returns

void


setDownloadExtensions()

setDownloadExtensions(extensions): void

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

Parameters

extensions: string[]

Returns

void


setIgnoreClasses()

setIgnoreClasses(classes): void

Set a list of class names that indicate a link should not be tracked

Parameters

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

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

time: number

Returns

void


trackLink()

trackLink(url, linkType, dimensions?, callback?): void

Manually tracks outlink or download event with provided values

Parameters

url: string

linkType: string

dimensions?: Dimensions

callback?

Returns

void


ErrorTracking


enableJSErrorTracking()

enableJSErrorTracking(unique?): void

Enables tracking of unhandled JavaScript errors.

Parameters

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

error: Error

Returns

void


GoalConversions


trackGoal()

trackGoal(goalId, conversionValue, dimensions?): void

Tracks manual goal conversion

Parameters

goalId: string | number

conversionValue: number

dimensions?: Dimensions

Returns

void


PageViews


trackPageView()

trackPageView(customPageTitle?): void

Tracks a visit on the page that the function was run on

Parameters

customPageTitle?: string

Returns

void


SiteSearch


trackSiteSearch()

trackSiteSearch(keyword, category?, searchCount?, dimensions?): void

Tracks search requests on a website

Parameters

keyword: string

category?: string

searchCount?: number

dimensions?: Dimensions

Returns

void


UserManagement


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

userId: string

Returns

void


eCommerce


addEcommerceItem()

addEcommerceItem(productSKU, productName, productCategory, productPrice, productQuantity): void

Parameters

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

products: Product[]

Returns

void


ecommerceCartUpdate()

ecommerceCartUpdate(products, grandTotal): void

Tracks current state of a cart

Parameters

products: Product[]

grandTotal: string | number

Returns

void


ecommerceOrder()

ecommerceOrder(products, paymentInformation): void

Tracks conversion, including products and payment details

Parameters

products: Product[]

paymentInformation: PaymentInformation

Returns

void


ecommerceProductDetailView()

ecommerceProductDetailView(products): void

Tracks action of viewing product page

Parameters

products: Product[]

Returns

void


ecommerceRemoveFromCart()

ecommerceRemoveFromCart(products): void

Tracks action of removing a products from a cart

Parameters

products: Product[]

Returns

void


getEcommerceItems()

getEcommerceItems(): Promise\<object>

Returns

Promise\<object>

Deprecated


removeEcommerceItem()

removeEcommerceItem(productSKU): void

Parameters

productSKU: string

Returns

void

Deprecated

Please use the ecommerceRemoveFromCart instead.


setEcommerceView()

setEcommerceView(productSKU, productName?, productCategory?, productPrice?): void

Parameters

productSKU: string

productName?: string

productCategory?: string[]

productPrice?: string

Returns

void

Deprecated


trackEcommerceCartUpdate()

trackEcommerceCartUpdate(cartAmount): void

Parameters

cartAmount: number

Returns

void

Deprecated

Please use the ecommerceCartUpdate instead.


trackEcommerceOrder()

trackEcommerceOrder(orderId, orderGrandTotal, orderSubTotal?, orderTax?, orderShipping?, orderDiscount?): void

Parameters

orderId: string

orderGrandTotal: number

orderSubTotal?: number

orderTax?: number

orderShipping?: number

orderDiscount?: number

Returns

void

Deprecated

Please use the ecommerceOrder instead.


Type Alias: Dimensions

Dimensions: Record\<`dimension${number}`, string>


Type Alias: InitOptions

InitOptions: object

Type declaration

dataLayerName?

optional dataLayerName: string

Defaults to 'dataLayer'

nonce?

optional nonce: string


Type Alias: PaymentInformation

PaymentInformation: object

Type declaration

discount?

optional discount: number | string

grandTotal

grandTotal: number | string

orderId

orderId: string

shipping?

optional shipping: number | string

subTotal?

optional subTotal: number | string

tax?

optional tax: number | string


Type Alias: Product

Product: object

Type declaration

brand?

optional brand: string

category?

optional category: LimitedArrayFiveStrings

customDimensions?

optional customDimensions: Record\<number, string>

name?

optional name: string

price?

optional price: number

quantity?

optional quantity: number

sku

sku: string

variant?

optional variant: string


Type Alias: VisitorInfo

VisitorInfo: "0" | "1", string, number, string | number, number, number | "", number | ""


Variable: default

const default: object

Type declaration

getInitScript

getInitScript: typeof PiwikPro.getInitScript

initialize

initialize: typeof PiwikPro.init

2.0.1

2 months ago

2.0.0

5 months ago

1.2.0

10 months ago

1.1.1

11 months ago

1.1.0

11 months ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago

0.1.1

3 years ago

0.1.0

3 years ago

0.0.9

3 years ago