ngx-matomo-client/router/index.d.ts

Matomo (fka. Piwik) client for Angular applications

import * as i0 from '@angular/core';
import { InjectionToken, Type, Provider, ModuleWithProviders } from '@angular/core';
import { MatomoFeature, MatomoECommerceView, MatomoTracker } from 'ngx-matomo-client/core';
import { NavigationEnd, Router, ActivatedRouteSnapshot } from '@angular/router';
import { Observable } from 'rxjs';

declare const MATOMO_ROUTER_INTERCEPTORS: InjectionToken<MatomoRouterInterceptor[]>;
/** Interceptor used to hook just before every page tracking */
type MatomoRouterInterceptorFn = (event: NavigationEnd) => Observable<void> | Promise<void> | void;
/** Interceptor used to hook into the page tracking process */
interface MatomoRouterInterceptor {
    /**
     * Called after a router event has occurred and before page view has been tracked (i.e. before `trackPageView()` has been called)
     *
     * If an Observable or a Promise is returned, the observable (first emission or completion) or promise resolution is awaited before tracking call.
     */
    beforePageTrack(event: NavigationEnd): Observable<void> | Promise<void> | void;
}
declare function provideInterceptor(typeOrFn: Type<MatomoRouterInterceptor> | MatomoRouterInterceptorFn): Provider;
declare function provideInterceptors(types: (Type<MatomoRouterInterceptor> | MatomoRouterInterceptorFn)[] | undefined): Provider[];

declare const MATOMO_ROUTER_CONFIGURATION: InjectionToken<MatomoRouterConfiguration>;
type ExclusionConfig = string | RegExp | (string | RegExp)[];
type NavigationEndComparator = (previousNavigationEnd: NavigationEnd, currentNavigationEnd: NavigationEnd) => boolean;
interface MatomoRouterConfiguration {
    /**
     * Set whether the application base href should be included in Matomo tracked urls
     *
     * Optional, default is `true`
     */
    prependBaseHref?: boolean;
    /**
     * Set whether the page title should be set when tracking page views
     *
     * Note that if set to `false`, Matomo is likely to still use the initial document title for all
     * tracked page views.
     *
     * Optional, default is `true`
     */
    trackPageTitle?: boolean;
    /**
     * Set a delay after navigation event, before the page view is tracked. This is useful to let a
     * chance to the components to update document title.
     *
     * Set it to 0 (the default) to execute tracking asynchronously without further delay
     * Set it to -1, to execute tracking synchronously (not recommended)
     *
     * Optional, default is `0` (but still asynchronous)
     */
    delay?: number;
    /**
     * Pass some regular expressions to exclude some urls from being tracked as page views
     *
     * Optional, default is no url excluded
     */
    exclude?: ExclusionConfig;
    /**
     * Custom url comparator to detect url change between Angular route navigations.
     *
     * This may be useful, because by default all `NavigationEnd` events will trigger a page track and this may happen
     * after query params change only (without url actually changing).
     *
     * You can define a custom comparator here to compare url by ignoring query params.
     *
     * Note: this is different from providing the url sent to Matomo for actual tracking. The url sent to Matomo will be
     * the full page url, including any base href, and is configured using a {@link PageUrlProvider} (see
     * `MATOMO_PAGE_URL_PROVIDER` token).
     *
     * Optional, default is to compare `NavigationEnd.urlAfterRedirects`
     *
     * Possible values:
     * - `'fullUrl'` (or undefined): default value, compare using `NavigationEnd.urlAfterRedirects`
     * - `'ignoreQueryParams'`: compare using `NavigationEnd.urlAfterRedirects` but ignoring query params
     * - `NavigationEndComparator`: compare using a custom `NavigationEndComparator` function
     */
    navigationEndComparator?: NavigationEndComparator | 'ignoreQueryParams' | 'fullUrl';
}
interface MatomoRouterConfigurationWithInterceptors extends MatomoRouterConfiguration {
    /**
     * Interceptors types to register.
     *
     * For more complex scenarios, it is possible to configure any interceptor by
     * providing token `MATOMO_ROUTER_INTERCEPTORS` as `multi` provider(s).
     */
    interceptors?: (Type<MatomoRouterInterceptor> | MatomoRouterInterceptorFn)[];
}

declare const MATOMO_PAGE_URL_PROVIDER: InjectionToken<PageUrlProvider>;
interface PageUrlProvider {
    getCurrentPageUrl(event: NavigationEnd): Observable<string> | Promise<string>;
}
type PageUrlProviderFn = (event: NavigationEnd) => Observable<string> | Promise<string>;
declare function providePageUrlProvider(typeOrFn: Type<PageUrlProvider> | PageUrlProviderFn): Provider;

/** Enable automatic page views tracking */
declare function withRouter(config?: MatomoRouterConfiguration): MatomoFeature;
/** Add some matomo router interceptors */
declare function withRouterInterceptors(interceptors: (Type<MatomoRouterInterceptor> | MatomoRouterInterceptorFn)[]): MatomoFeature;
/**
 * Enable retrieval of tracking information from route data
 *
 * @see MatomoRouteData
 * @param key A custom key to get lookup route data - default is 'matomo'
 */
declare function withRouteData(key?: string): MatomoFeature;
declare function withPageUrlProvider(provider: Type<PageUrlProvider> | PageUrlProviderFn): MatomoFeature;

declare class MatomoRouterModule {
    static forRoot(configWithInterceptors?: MatomoRouterConfigurationWithInterceptors): ModuleWithProviders<MatomoRouterModule>;
    static ɵfac: i0.ɵɵFactoryDeclaration<MatomoRouterModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<MatomoRouterModule, never, never, never>;
    static ɵinj: i0.ɵɵInjectorDeclaration<MatomoRouterModule>;
}
/**
 * @deprecated use MatomoRouterModule instead
 * @breaking-change 8.0.0
 */
declare class NgxMatomoRouterModule {
    static forRoot(configWithInterceptors?: MatomoRouterConfigurationWithInterceptors): ModuleWithProviders<NgxMatomoRouterModule>;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxMatomoRouterModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<NgxMatomoRouterModule, never, never, never>;
    static ɵinj: i0.ɵɵInjectorDeclaration<NgxMatomoRouterModule>;
}

/**
 * @deprecated Use an interceptor calling `setDocumentTitle()` instead
 * @see MatomoRouterInterceptor
 * @see MATOMO_ROUTER_INTERCEPTORS
 */
declare const MATOMO_PAGE_TITLE_PROVIDER: InjectionToken<PageTitleProvider>;
/**
 * @deprecated Use an interceptor calling `setDocumentTitle()` instead
 * @see MatomoRouterInterceptor
 * @see MATOMO_ROUTER_INTERCEPTORS
 */
interface PageTitleProvider {
    getCurrentPageTitle(event: NavigationEnd): Observable<string>;
}

/**
 * Simple interceptor base looking into route's data for tracking
 *
 * @see MatomoRouteDataInterceptor
 */
declare abstract class MatomoRouteInterceptorBase<D> implements MatomoRouterInterceptor {
    protected readonly router: Router;
    beforePageTrack(event: NavigationEnd): Observable<void> | Promise<void> | void;
    protected getRoute(_: NavigationEnd): ActivatedRouteSnapshot;
    protected abstract extractRouteData(route: ActivatedRouteSnapshot): D;
    protected abstract processRouteData(data: D): Observable<void> | Promise<void> | void;
}

/** Token to define the route's data key to be looked-up by `MatomoRouteDataInterceptor`  */
declare const MATOMO_ROUTE_DATA_KEY: InjectionToken<string>;
/** Standard properties that may be read from route data */
interface MatomoRouteData {
    title?: string;
    ecommerce?: MatomoECommerceView;
}
/**
 * Simple interceptor looking at 'matomo' key of route's data for tracking.
 *
 * It is possible to extend this class or {@link MatomoRouteInterceptorBase}
 * for custom behavior (to use another data key, etc.)
 *
 * @example
 * // Using provided MatomoRouteDataInterceptor (looks into 'matomo' data key)
 * const routes: Routes = [
 *   {
 *     path: '/hello',
 *     component: HelloComponent,
 *     data: {
 *       matomo: {
 *         title: 'Page title',
 *       } as MatomoRouteData
 *     }
 *   },
 * ];
 *
 * NgxMatomoRouterModule.forRoot({
 *   interceptors: [MatomoRouteDataInterceptor],
 * }),
 *
 * @example
 * // Using custom 'myCustomAnalyticsKey' data key
 * const routes: Routes = [
 *   {
 *     path: '/hello',
 *     component: HelloComponent,
 *     data: {
 *       myCustomAnalyticsKey: {
 *         title: 'Page title',
 *       } as MatomoRouteData
 *     }
 *   },
 * ];
 *
 * @Injectable()
 * export class MyCustomInterceptor extends MatomoRouteDataInterceptor {
 *   readonly dataKey = 'myCustomAnalyticsKey';
 * }
 *
 * NgxMatomoRouterModule.forRoot({
 *   interceptors: [MyCustomInterceptor],
 * }),
 *
 * @see MatomoRouteInterceptorBase
 * @see MatomoRouteData
 */
declare class MatomoRouteDataInterceptor extends MatomoRouteInterceptorBase<MatomoRouteData | undefined> {
    protected readonly tracker: MatomoTracker;
    protected readonly dataKey: string;
    protected extractRouteData(route: ActivatedRouteSnapshot): MatomoRouteData | undefined;
    protected processRouteData(data: MatomoRouteData | undefined): Observable<void> | Promise<void> | void;
    static ɵfac: i0.ɵɵFactoryDeclaration<MatomoRouteDataInterceptor, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<MatomoRouteDataInterceptor>;
}

export { MATOMO_PAGE_TITLE_PROVIDER, MATOMO_PAGE_URL_PROVIDER, MATOMO_ROUTER_CONFIGURATION, MATOMO_ROUTER_INTERCEPTORS, MATOMO_ROUTE_DATA_KEY, MatomoRouteDataInterceptor, MatomoRouteInterceptorBase, MatomoRouterModule, NgxMatomoRouterModule, provideInterceptor, provideInterceptors, providePageUrlProvider, withPageUrlProvider, withRouteData, withRouter, withRouterInterceptors };
export type { ExclusionConfig, MatomoRouteData, MatomoRouterConfiguration, MatomoRouterConfigurationWithInterceptors, MatomoRouterInterceptor, MatomoRouterInterceptorFn, NavigationEndComparator, PageTitleProvider, PageUrlProvider, PageUrlProviderFn };