Skip to content

Latest commit

 

History

History
126 lines (99 loc) · 11.9 KB

configuration-reference.md

File metadata and controls

126 lines (99 loc) · 11.9 KB
Raw

matomo-logo ngx-matomo-client

← return to documentation

Configuration reference

The configuration should be provided in your application's root module, either using NgModule or provideMatomo(options, ...additionalFeatures):

Classic apps Standalone apps 
import {
  NgxMatomoModule,
  NgxMatomoRouterModule,
  MatomoRouteDataInterceptor,
} from 'ngx-matomo-client';

@NgModule({
  imports: [
    NgxMatomoModule.forRoot({
      // Main options here
      siteId: 42,
      trackerUrl: 'http://...',
    }),
    NgxMatomoRouterModule.forRoot({
      // Router options here
    }),
  ],
})
export class AppModule {}
 
import {
  provideMatomo,
  withRouter,
  withScriptFactory,
  withRouterInterceptors,
} from 'ngx-matomo-client';

@NgModule({
  providers: [
    provideMatomo(
      // Main options here
      {
        siteId: 42,
        trackerUrl: 'http://...',
      },

      // Optionally add one or more features:
      withRouter({
        // Router options here
      }),
      withScriptFactory(),
      withRouterInterceptors()
    ),
  ],
})
export class AppModule {}

Options

Main configuration options (for NgxMatomoModule.forRoot or provideMatomo) are:

Option Type Default value Description Available in MANUAL mode
mode MatomoInitializationMode MatomoInitializationMode.AUTO Set whether tracking code should be automatically embedded or not.
If set to MatomoInitializationMode.MANUAL, some other option cannot be used.		 -
siteId number or string required, unless trackers is set Your Matomo site id (may be found in your Matomo server's settings). no
trackerUrl string required, unless trackers is set Your Matomo server url. no
trackerUrlSuffix string matomo.php Suffix to append to trackerUrl. no
trackers array of {siteId: string, trackerUrl: string, trackerUrlSuffix?: string} none, required unless siteId and trackerUrl are set A list of multiple Matomo servers. Note that tracking code will be downloaded from the FIRST tracker in the list (unless scriptUrl option is set). Mutually exclusive with the three previous options. no
scriptUrl string tracker url suffixed with matomo.js Url of Matomo tracker's script. no
disabled boolean false If set to true then all tracking operations become no-op. Note that in this case, all getter methods will return rejected Promises. yes
trackAppInitialLoad boolean false if router is enabled, true otherwise If set to true, will call trackPageView on application init. This should probably never be used on a routed single-page application. yes
enableLinkTracking boolean or 'enable-pseudo' true If set to true (the default), enable link tracking, excluding middle-clicks and contextmenu events.
If set to enable-pseudo, enable link tracking, including middle-clicks and contextmenu events.
If set to false, disable link tracking.		 yes
enableJSErrorTracking boolean false If set to true, enable JS errors tracking. yes
acceptDoNotTrack boolean false Set whether to not track users who opt out of tracking using Do Not Track setting yes
requireConsent MatomoConsentMode MatomoConsentMode.NONE Configure user consent requirement. yes
runOutsideAngularZone boolean false If set to true, will run matomo calls outside of angular's NgZone. This may help if the call causes the app to freeze. yes

Router configuration options (for NgxMatomoRouterModule.forRoot or withRouter) are:

Option Type Default value Description
prependBaseHref boolean true Set whether the application's base href should be prepended to current url when tracking page views. Set it to false to disable this behavior.
trackPageTitle boolean true Set whether to detect page title when tracking views.
By default, page title is automatically detected from DOM document title.
Note that if set to false, Matomo is likely to still use the initial document title for all tracked page views.
delay number
Set to -1 to run synchronously		 0 (no delay but still asynchronous) Set a delay after navigation event before page view is tracked.
If your document title is updated asynchronously after Router events, you may have to set a delay to correctly detect document title.
If set to 0, tacking is still asynchronous. Set it to -1 to execute tracking synchronously.
See also previous sections for more advanced page title customization.
exclude string, RegExp, string[] or RegExp[] [] Set some url patterns to exclude from page views tracking.

Additional features

Available features for provideMatomo are:

withRouter

Enable automatic page view tracking. This requires @angular/router.

See options for router configuration above.

withRouteData

Add automatic Matomo data retrieval from Angular routes configuration. This requires withRouter() feature. See Using route data in README for details.

withRouterInterceptors

Add interceptors to hook into the automatic page view tracking. This requires withRouter() feature. See Using custom interceptor in README for details.

withScriptFactory

Allow to customize Matomo's script element creation. See How can I customize the inserted script tag? in FAQ.