Skip to content

Latest commit

 

History

History
1921 lines (915 loc) · 34 KB

README.md

File metadata and controls

1921 lines (915 loc) · 34 KB
Raw

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