Dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in Angular 8+ applications.
To use this package in your project, run the following command.
npm install @piwikpro/ngx-piwik-proIn 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 {}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 {}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 {}NgxPiwikProRouterModule. The include/exclude settings allow:{ include: [ '/full-uri-match' ] };{ include: [ '*/public/*' ] };{ include: [ /^\/public\/.*/ ] };import { NgxPiwikProModule, NgxPiwikProRouterModule } from '@piwikpro/ngx-piwik-pro';
...
@NgModule({
...
imports: [
...
NgxPiwikProModule.forRoot('container-id'),
NgxPiwikProRouterModule.forRoot({ include: [...], exclude: [...] })
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
]
})
export class AppModule {}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 {}@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');
}
}
@Component(...)
export class TestPageComponent implements OnInit {
constructor(
protected pageViewsService: PageViewsService
) {}
ngOnInit() {
this.pageViewsService.trackPageView('Title')
}
}@Component(...)
export class TestPageComponent implements OnInit {
constructor(
protected dataLayerService: DataLayerService
) {}
ngOnInit() {
this.dataLayerService.push({ event: 'test-event' })
}
}logAllContentBlocksOnPage():
void
Print all content blocks to the console for debugging purposes
void
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
void
trackContentImpression(
contentName,contentPiece,contentTarget):void
• contentName: string
• contentPiece: string
• contentTarget: string
void
trackContentImpressionsWithinNode(
domNode):void
• domNode: Node
void
trackContentInteraction(
contentInteraction,contentName,contentPiece,contentTarget):void
Tracks manual content interaction event
• 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)
void
trackContentInteractionNode(
domNode,contentInteraction?):void
Tracks interaction with a block in domNode. Can be called from code placed in onclick attribute
• 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")
void
trackVisibleContentImpressions(
checkOnScroll?,watchInterval?):void
Scans DOM for all visible content blocks and tracks impressions
• 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
void
deleteCookies():
void
Deletes existing tracking cookies on the next page view
void
disableCookies():
void
Disables all first party cookies. Existing cookies will be deleted in the next page view
void
enableCookies():
void
Enables all first party cookies. Cookies will be created on the next tracking request
void
getConfigVisitorCookieTimeout():
Promise\<number>
Returns expiration time of visitor cookies (in milliseconds)
Promise\<number>
getCookieDomain():
Promise\<string>
Returns domain of the analytics tracking cookies (set with setCookieDomain()).
Promise\<string>
getCookiePath():
Promise\<string>
Returns the analytics tracking cookies path
Promise\<string>
getSessionCookieTimeout():
Promise\<number>
Returns expiration time of session cookies
Promise\<number>
hasCookies():
Promise\<boolean>
Returns true if cookies are enabled in this browser
Promise\<boolean>
setCookieDomain(
domain):void
Sets the domain for the analytics tracking cookies
• domain: string
void
setCookieNamePrefix(
prefix):void
Sets the prefix for analytics tracking cookies. Default is "pk".
• prefix: string
void
setCookiePath(
path):void
Sets the analytics tracking cookies path
• path: string
void
setReferralCookieTimeout(
seconds):void
Sets the expiration time of referral cookies
• seconds: number
void
setSecureCookie(
secure):void
Toggles the secure cookie flag on all first party cookies (if you are using HTTPS)
• secure: boolean
void
setSessionCookieTimeout(
seconds):void
Sets the expiration time of session cookies
• seconds: number
void
setVisitorCookieTimeout(
seconds):void
Sets the expiration time of visitor cookies
• seconds: number
void
setVisitorIdCookie():
void
Sets cookie containing analytics ID in browser
void
deleteCustomDimension(
customDimensionId):void
Removes a custom dimension with the specified ID.
• customDimensionId: string | number
void
getCustomDimensionValue(
customDimensionId):Promise\<string|undefined>
Returns the value of a custom dimension with the specified ID.
• customDimensionId: string | number
Promise\<string | undefined>
setCustomDimensionValue(
customDimensionId,customDimensionValue):void
Sets a custom dimension value to be used later.
• customDimensionId: string | number
• customDimensionValue: string
void
trackEvent(
category,action,name?,value?,dimensions?):void
Tracks a custom event, e.g. when a visitor interacts with the page
• category: string
• action: string
• name?: string
• value?: number
• dimensions?: Dimensions
void
push(
data):number
Adds entry to a data layer
• data: DataLayerEntry
number
setDataLayerName(
name):void
• name: string
void
DataLayerEntry:
Record\<string,AnyData>
addDownloadExtensions(
extensions):void
Adds new extensions to the download extensions list
• extensions: string[]
void
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
• trackAlsoMiddleAndRightClicks?: boolean
void
getLinkTrackingTimer():
Promise\<number>
Returns lock/wait time after a request set by setLinkTrackingTimer
Promise\<number>
removeDownloadExtensions(
extensions):void
Removes extensions from the download extensions list
• extensions: string[]
void
setDownloadClasses(
classes):void
Sets a list of class names that indicate whether a list is a download and not an outlink
• classes: string[]
void
setDownloadExtensions(
extensions):void
Overwrites the list of file extensions indicating that a link is a download
• extensions: string[]
void
setIgnoreClasses(
classes):void
Set a list of class names that indicate a link should not be tracked
• classes: string[]
void
setLinkClasses(
classes):void
Sets a list of class names that indicate whether a link is an outlink and not download
• classes: string[]
void
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
• time: number
void
trackLink(
url,linkType,dimensions?,callback?):void
Manually tracks outlink or download event with provided values
• url: string
• linkType: string
• dimensions?: Dimensions
• callback?
void
enableJSErrorTracking(
unique?):void
Enables tracking of unhandled JavaScript errors.
• unique?: boolean
track only unique errors
void
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.
• error: Error
void
trackGoal(
goalId,conversionValue,dimensions?):void
Tracks manual goal conversion
• goalId: string | number
• conversionValue: number
• dimensions?: Dimensions
void
trackPageView(
customPageTitle?):void
Tracks a visit on the page that the function was run on
• customPageTitle?: string
void
trackSiteSearch(
keyword,category?,searchCount?,dimensions?):void
Tracks search requests on a website
• keyword: string
• category?: string
• searchCount?: number
• dimensions?: Dimensions
void
getUserId():
Promise\<string>
The function that will return user ID
Promise\<string>
getVisitorId():
Promise\<string>
Returns 16-character hex ID of the visitor
Promise\<string>
getVisitorInfo():
Promise\<VisitorInfo>
Returns visitor information in an array
Promise\<VisitorInfo>
resetUserId():
void
Clears previously set userID, e.g. when visitor logs out
void
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
• userId: string
void
addEcommerceItem(
productSKU,productName,productCategory,productPrice,productQuantity):void
• productSKU: string
• productName: string
• productCategory: string | string[]
• productPrice: number
• productQuantity: number
void
Please use the ecommerceAddToCart instead.
clearEcommerceCart():
void
void
ecommerceAddToCart(
products):void
Tracks action of adding products to a cart
• products: Product[]
void
ecommerceCartUpdate(
products,grandTotal):void
Tracks current state of a cart
• products: Product[]
• grandTotal: string | number
void
ecommerceOrder(
products,paymentInformation):void
Tracks conversion, including products and payment details
• products: Product[]
• paymentInformation: PaymentInformation
void
ecommerceProductDetailView(
products):void
Tracks action of viewing product page
• products: Product[]
void
ecommerceRemoveFromCart(
products):void
Tracks action of removing a products from a cart
• products: Product[]
void
getEcommerceItems():
Promise\<object>
Promise\<object>
removeEcommerceItem(
productSKU):void
• productSKU: string
void
Please use the ecommerceRemoveFromCart instead.
setEcommerceView(
productSKU,productName?,productCategory?,productPrice?):void
• productSKU: string
• productName?: string
• productCategory?: string[]
• productPrice?: string
void
trackEcommerceCartUpdate(
cartAmount):void
• cartAmount: number
void
Please use the ecommerceCartUpdate instead.
trackEcommerceOrder(
orderId,orderGrandTotal,orderSubTotal?,orderTax?,orderShipping?,orderDiscount?):void
• orderId: string
• orderGrandTotal: number
• orderSubTotal?: number
• orderTax?: number
• orderShipping?: number
• orderDiscount?: number
void
Please use the ecommerceOrder instead.
Dimensions:
Record\<`dimension${number}`,string>
InitOptions:
object
optionaldataLayerName:string
Defaults to 'dataLayer'
optionalnonce:string
PaymentInformation:
object
optionaldiscount:number|string
grandTotal:
number|string
orderId:
string
optionalshipping:number|string
optionalsubTotal:number|string
optionaltax:number|string
Product:
object
optionalbrand:string
optionalcategory:LimitedArrayFiveStrings
optionalcustomDimensions:Record\<number,string>
optionalname:string
optionalprice:number
optionalquantity:number
sku:
string
optionalvariant:string
VisitorInfo: [
"0"|"1",string,number,string|number,number,number|"",number|""]
constdefault:object
getInitScript: typeof
PiwikPro.getInitScript
initialize: typeof
PiwikPro.init