ngx-matomo-client - npm Package Compare versions

Comparing version 6.1.3 to 6.2.0

core/private-api.d.ts

 export { runOnce as ɵrunOnce } from './utils/function';
-export { MATOMO_ROUTER_ENABLED as ɵMATOMO_ROUTER_ENABLED } from './tracker/configuration';
-export { createMatomoFeature as ɵcreateMatomoFeature, MatomoFeatureKind as ɵMatomoFeatureKind, MatomoFeature as ɵMatomoFeature, } from './providers';
+export { appendTrailingSlash as ɵappendTrailingSlash } from './utils/url';
+export { Getters as ɵGetters, Methods as ɵMethods } from './utils/types';
+export { ScriptInjector as ɵScriptInjector } from './utils/script-injector';
+export { INTERNAL_MATOMO_CONFIGURATION as ɵINTERNAL_MATOMO_CONFIGURATION, DEFERRED_INTERNAL_MATOMO_CONFIGURATION as ɵDEFERRED_INTERNAL_MATOMO_CONFIGURATION, ASYNC_INTERNAL_MATOMO_CONFIGURATION as ɵASYNC_INTERNAL_MATOMO_CONFIGURATION, MATOMO_ROUTER_ENABLED as ɵMATOMO_ROUTER_ENABLED, isExplicitTrackerConfiguration as ɵisExplicitTrackerConfiguration, getTrackersConfiguration as ɵgetTrackersConfiguration, isAutoConfigurationMode as ɵisAutoConfigurationMode, } from './tracker/configuration';
+export { InternalMatomoTracker as ɵInternalMatomoTracker } from './tracker/internal-matomo-tracker.service';
+export { createMatomoFeature as ɵcreateMatomoFeature } from './providers';

core/providers.d.ts

@@ -5,14 +5,10 @@ import { EnvironmentProviders, Provider } from '@angular/core';
 declare const PRIVATE_MATOMO_PROVIDERS: unique symbol;
+declare const PRIVATE_MATOMO_CHECKS: unique symbol;
+export type MatomoFeatureKind = unknown;
 /**
  * Additional Matomo features kind
  */
-export declare const enum MatomoFeatureKind {
+export declare const enum CoreMatomoFeatureKind {
     /** @see withScriptFactory */
-    ScriptFactory = 0,
-    /** @see withRouter */
-    Router = 1,
-    /** @see withRouterInterceptors */
-    RouterInterceptors = 2,
-    /** @see withRouteData */
-    BuiltInRouteDataInterceptor = 3
+    ScriptFactory = "ScriptFactory"
 }
@@ -22,4 +18,5 @@ export interface MatomoFeature {
     [PRIVATE_MATOMO_PROVIDERS]: Provider[];
+    [PRIVATE_MATOMO_CHECKS]?: (features: MatomoFeatureKind[]) => void;
 }
-export declare function createMatomoFeature(kind: MatomoFeatureKind, providers: Provider[]): MatomoFeature;
+export declare function createMatomoFeature(kind: MatomoFeatureKind, providers: Provider[], checks?: (features: MatomoFeatureKind[]) => void): MatomoFeature;
 /**
@@ -26,0 +23,0 @@ * Return Matomo providers (typically added to an application's root module)

core/public-api.d.ts

 export * from './private-api';
+/**
+ * @deprecated for internal use only
+ * @breaking-change 6.0.0
+ */
+declare const INTERNAL_MATOMO_CONFIGURATION: import("@angular/core").InjectionToken<import("./tracker/configuration").InternalMatomoConfiguration>;
+export { INTERNAL_MATOMO_CONFIGURATION };
 export { NgxMatomoModule, NgxMatomoTrackerModule, MatomoModule, MATOMO_DIRECTIVES, } from './matomo.module';
@@ -6,3 +12,3 @@ export { provideMatomo, withScriptFactory, MatomoFeatureKind, MatomoFeature } from './providers';
 export { MatomoInitializerService } from './tracker/matomo-initializer.service';
-export { MatomoConfiguration, MATOMO_CONFIGURATION, AutoMatomoConfiguration, MatomoInitializationMode, MatomoConsentMode, InternalMatomoConfiguration, INTERNAL_MATOMO_CONFIGURATION, } from './tracker/configuration';
+export { MatomoConfiguration, MATOMO_CONFIGURATION, AutoMatomoConfiguration, MatomoInitializationMode, MatomoConsentMode, InternalMatomoConfiguration, } from './tracker/configuration';
 export { MATOMO_SCRIPT_FACTORY, MatomoScriptFactory, createDefaultMatomoScriptElement, } from './tracker/script-factory';
@@ -9,0 +15,0 @@ export { MatomoTrackerDirective } from './directives/matomo-tracker.directive';

core/tracker/configuration.d.ts

@@ -105,2 +105,11 @@ import { InjectionToken } from '@angular/core';
     runOutsideAngularZone?: boolean;
+    /**
+     * Set to `true` to avoid sending campaign parameters
+     *
+     * By default, Matomo will send campaign parameters (mtm, utm, etc.) to the tracker and record that information.
+     * Some privacy regulations may not allow for this information to be collected.
+     *
+     * <b>This is available as of Matomo 5.1 only.</b>
+     */
+    disableCampaignParameters?: boolean;
 }
@@ -107,0 +116,0 @@ export interface BaseAutoMatomoConfiguration<M extends MatomoInitializationMode.AUTO | MatomoInitializationMode.AUTO_DEFERRED = MatomoInitializationMode.AUTO> {

core/tracker/matomo-initializer.service.d.ts

@@ -0,6 +1,8 @@
+import { PublicInterface } from '../utils/types';
 import { AutoMatomoConfiguration, MatomoInitializationMode } from './configuration';
 import * as i0 from "@angular/core";
-export declare function createMatomoInitializer(): MatomoInitializerService;
-export declare class NoopMatomoInitializer implements Pick<MatomoInitializerService, 'initialize' | 'initializeTracker'> {
+export declare function createMatomoInitializer(): PublicInterface<MatomoInitializerService>;
+export declare class NoopMatomoInitializer implements PublicInterface<MatomoInitializerService> {
     initialize(): void;
+    init(): void;
     initializeTracker(_: AutoMatomoConfiguration<MatomoInitializationMode.AUTO_DEFERRED>): void;
@@ -12,7 +14,5 @@ }
     private readonly tracker;
-    private readonly scriptFactory;
-    private readonly injector;
-    private readonly document;
+    private readonly scriptInjector;
     constructor();
-    /** @deprecated use {@link initialize initialize()} instead */
+    /** @deprecated Will be removed in v7+. Use {@link initialize initialize()} instead. */
     init(): void;
@@ -24,3 +24,2 @@ readonly initialize: () => void;
     private registerAdditionalTrackers;
-    private injectDOMScript;
     private runPreInitTasks;
@@ -27,0 +26,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<MatomoInitializerService, never>;

core/tracker/matomo-tracker.service.d.ts

@@ -1,4 +0,2 @@
-import { NgZone } from '@angular/core';
-import { Getters, NonEmptyReadonlyArray, RequireAtLeastOne } from '../utils/types';
-import { InternalMatomoConfiguration } from './configuration';
+import { NonEmptyReadonlyArray, RequireAtLeastOne } from '../utils/types';
 import * as i0 from "@angular/core";
@@ -56,4 +54,7 @@ export interface MatomoECommerceItem {
 }
-export declare function createMatomoTracker(config: InternalMatomoConfiguration, platformId: Object, ngZone: NgZone): MatomoTracker;
-export declare abstract class MatomoTracker {
+export declare class MatomoTracker {
+    private readonly delegate;
+    private readonly _pageViewTracked;
+    readonly pageViewTracked: import("rxjs").Observable<void>;
+    constructor();
     /**
@@ -888,24 +889,12 @@ * Logs a visit to this page.
     enableBrowserFeatureDetection(): void;
-    /** Asynchronously call provided method name on matomo tracker instance */
-    protected get<G extends Getters<MatomoInstance>>(getter: G): Promise<ReturnType<MatomoInstance[G]>>;
     /**
-     * Asynchronously call provided method with matomo tracker instance as argument
+     * By default, Matomo will send campaign parameters (mtm, utm, etc.) to the tracker and record that information.
+     * Some privacy regulations may not allow for this information to be collected.
+     * If this applies to you, call this method to prevent campaign parameters from being sent to the tracker.
      *
-     * @return Promise resolving to the return value of given method
+     * <b>This method is available as of Matomo 5.1.</b>
      */
-    protected abstract pushFn<T>(fn: (matomo: MatomoInstance) => T): Promise<T>;
-    protected abstract push(args: unknown[]): void;
+    disableCampaignParameters(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<MatomoTracker, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MatomoTracker>;
 }
-export declare class StandardMatomoTracker extends MatomoTracker {
-    private readonly ngZone;
-    private readonly config;
-    constructor(ngZone: NgZone, config: InternalMatomoConfiguration);
-    protected pushFn<T>(fn: (matomo: MatomoInstance) => T): Promise<T>;
-    protected push(args: unknown[]): void;
-}
-export declare class NoopMatomoTracker extends MatomoTracker {
-    protected push(_: unknown[]): void;
-    protected pushFn<T>(_: (matomo: MatomoInstance) => T): Promise<T>;
-}

core/utils/types.d.ts

@@ -14,1 +14,8 @@ /** Extract from a type T all getter-like method keys, optionally filtered by those returning type U */
 export type NonEmptyReadonlyArray<T> = Readonly<NonEmptyArray<T>>;
+export type PublicInterface<T> = {
+    [K in keyof T]: T[K];
+};
+export type Prefixed<S, PREFIX extends string> = S extends string ? `${PREFIX}${S}` : never;
+export type PrefixedType<MATOMO, PREFIX extends string> = {
+    [K in keyof MATOMO as Prefixed<K, PREFIX>]: MATOMO[K];
+};

package.json

 {
   "name": "ngx-matomo-client",
-  "version": "6.1.3",
+  "version": "6.2.0",
   "author": "Emmanuel Roux (https://github.com/EmmanuelRoux)",
@@ -13,4 +13,4 @@ "description": "Matomo (fka. Piwik) client for Angular applications",
   "peerDependencies": {
-    "@angular/common": "^17.0.0",
-    "@angular/core": "^17.0.0"
+    "@angular/common": "^17.0.0 || ^18.0.0",
+    "@angular/core": "^17.0.0 || ^18.0.0"
   },
@@ -57,2 +57,8 @@ "dependencies": {
     },
+    "./form-analytics": {
+      "types": "./form-analytics/index.d.ts",
+      "esm2022": "./esm2022/form-analytics/ngx-matomo-client-form-analytics.mjs",
+      "esm": "./esm2022/form-analytics/ngx-matomo-client-form-analytics.mjs",
+      "default": "./fesm2022/ngx-matomo-client-form-analytics.mjs"
+    },
     "./router": {
@@ -59,0 +65,0 @@ "types": "./router/index.d.ts",

README.md

@@ -7,3 +7,3 @@ <h1 align="center">
 <p align="center">
-  <a href="https://angular.io/"><img src="https://img.shields.io/badge/Angular-17-limegreen.svg?logo=angular" alt="Angular 17"></a>&nbsp;
+  <a href="https://angular.io/"><img src="https://img.shields.io/badge/Angular-18-limegreen.svg?logo=angular" alt="Angular 18"></a>&nbsp;
   <a href="https://www.npmjs.com/package/ngx-matomo-client"><img src="https://img.shields.io/npm/v/ngx-matomo-client/latest.svg?logo=npm&logoColor=fff&label=NPM+package&color=limegreen" alt="NPM latest version"></a>&nbsp;
@@ -51,2 +51,3 @@ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-limegreen.svg" alt="MIT license"></a>&nbsp;
 | 3, 4 or 5 | 17      | 6.x                                                                                |                                                                                                   |
+| 3, 4 or 5 | 18      | 6.2.x or above                                                                     |                                                                                                   |
 
@@ -69,2 +70,4 @@ [![build](https://github.com/EmmanuelRoux/ngx-matomo-client/actions/workflows/main.yml/badge.svg)](https://github.com/EmmanuelRoux/ngx-matomo-client/actions/workflows/main.yml)
   * [Low-level API](#low-level-api)
+- [Plugins](#plugins)
+  * [Form analytics](#form-analytics)
 - [Migration from `@ngx-matomo/tracker` and `@ngx-matomo/router` (version <= 4)](#migration-from-ngx-matomotracker-and-ngx-matomorouter-version--4)
@@ -180,4 +183,4 @@ - [Configuration reference](#configuration-reference)
 import {
-  NgxMatomoModule,
-  NgxMatomoRouterModule
+  MatomoModule,
+  MatomoRouterModule
 } from 'ngx-matomo-client';
@@ -187,6 +190,6 @@
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       // Your configuration
     }),
-    NgxMatomoRouterModule,
+    MatomoRouterModule,
   ],
@@ -296,4 +299,4 @@ })
 import {
-  NgxMatomoModule,
-  NgxMatomoRouterModule,
+  MatomoModule,
+  MatomoRouterModule,
   MatomoRouteDataInterceptor,
@@ -304,6 +307,6 @@ } from 'ngx-matomo-client';
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       // Your configuration
     }),
-    NgxMatomoRouterModule.forRoot({
+    MatomoRouterModule.forRoot({
       interceptors: [MatomoRouteDataInterceptor],
@@ -397,4 +400,4 @@ }),
 import {
-  NgxMatomoModule,
-  NgxMatomoRouterModule,
+  MatomoModule,
+  MatomoRouterModule,
   MatomoRouteDataInterceptor,
@@ -405,6 +408,6 @@ } from 'ngx-matomo-client';
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       // Your configuration
     }),
-    NgxMatomoRouterModule.forRoot({
+    MatomoRouterModule.forRoot({
       // Add interceptors here:
@@ -645,2 +648,108 @@ interceptors: [
 
+## Plugins
+
+### Form analytics
+
+**Form Analytics support is currently experimental. [Please report any bugs](https://github.com/EmmanuelRoux/ngx-matomo-client/issues), and pull requests are highly appreciated!**
+
+#### Configuration
+
+Form analytics plugin is supported out-of-the-box. Just add `withFormAnalytics()` feature or `MatomoFormAnalyticsModule`
+to your application's root:
+
+<table>
+<tr>
+<th>Classic apps</th>
+<th><a href="https://angular.io/guide/standalone-components">Standalone</a> apps</th>
+</tr>
+<tr>
+<td valign="top">
+
+<!-- prettier-ignore -->
+```ts
+import {
+  MatomoFormAnalyticsModule
+} from 'ngx-matomo-client/form-analytics';
+
+@NgModule({
+  imports: [
+    NgxMatomoModule.forRoot({
+      // Your configuration
+    }),
+    MatomoFormAnalyticsModule,
+  ],
+})
+export class AppModule {}
+```
+
+</td>
+<td valign="top">
+
+<!-- prettier-ignore -->
+```ts
+import {
+  withFormAnalytics
+} from 'ngx-matomo-client/form-analytics';
+
+@NgModule({
+  providers: [
+    provideMatomo(
+      {}, // Your base configuration
+      withFormAnalytics() // Add this feature
+    ),
+  ],
+})
+export class AppModule {}
+```
+
+</td>
+</tr>
+</table>
+
+#### Usage
+
+Matomo client will automatically scan for forms in your pages after each page tracking.
+
+If some forms are dynamically added in your components on another timing, you can use `matomoTrackForm` or
+`matomoTrackForms` directives to track them:
+
+```html
+<!-- Adding matomoTrackForm directive will ensure the form is always tracked -->
+<form id="myForm" matomoTrackForm></form>
+```
+
+If the content of your form is dynamic, and you want to correctly track inner form controls, you will have to rescan the
+form after changes:
+
+```html
+<form id="myForm" matomoTrackForm>
+  <!-- Either add matomoTrackFormField directive to ensure the form is tracked -->
+  <input *ngIf="condition" matomoTrackFormField />
+
+  <!-- Or manually call .track() on the form -->
+  <button type="button" (click)="addControl(matomoTracker)"></button>
+</form>
+```
+
+If a _container_ is dynamically toggled, you can track multiple descendant forms at once by using `matomoTrackForms` (note the final _s_) on the container:
+
+```html
+<div *ngIf="showFormsCondition" matomoTrackForms>
+  <form id="myForm1">...</form>
+  <form id="myForm2">...</form>
+</div>
+```
+
+To automatically track a form submit when an element is clicked (for example a non-submit button), add `matomoTrackFormSubmit` on the button:
+
+```html
+<form id="myForm" matomoTrackForm>
+  <button type="button" matomoTrackFormSubmit>Non-native submit</button>
+</form>
+```
+
+You can also inject `MatomoFormAnalytics` and use low-level api directly.
+
+See official guide at https://developer.matomo.org/guides/form-analytics.
+
 ## Migration from `@ngx-matomo/tracker` and `@ngx-matomo/router` (version <= 4)
@@ -741,6 +850,6 @@
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       /* ... */
     }),
-    NgxMatomoRouterModule.forRoot({
+    MatomoRouterModule.forRoot({
       exclude: [/some-pattern$/],
@@ -817,3 +926,3 @@ }),
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       /* ... */
@@ -874,3 +983,3 @@ }),
   imports: [
-    NgxMatomoModule({
+    MatomoModule({
       /* ... */
@@ -892,3 +1001,3 @@ scriptUrl: 'YOUR_MATOMO_SCRIPT_URL', // your Matomo's script url
   imports: [
-    NgxMatomoModule.forRoot({
+    MatomoModule.forRoot({
       /* ... */
@@ -895,0 +1004,0 @@ mode: MatomoInitializationMode.AUTO_DEFERRED,

router/configuration.d.ts

 import { InjectionToken, Type } from '@angular/core';
+import { NavigationEnd } from '@angular/router';
 import { InternalMatomoConfiguration } from 'ngx-matomo-client/core';
@@ -6,2 +7,3 @@ import { MatomoRouterInterceptor } from './interceptor';
 export type ExclusionConfig = string | RegExp | (string | RegExp)[];
+export type NavigationEndComparator = (previousNavigationEnd: NavigationEnd, currentNavigationEnd: NavigationEnd) => boolean;
 export interface MatomoRouterConfiguration {
@@ -39,2 +41,22 @@ /**
     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';
 }
@@ -41,0 +63,0 @@ export interface MatomoRouterConfigurationWithInterceptors extends MatomoRouterConfiguration {

router/providers.d.ts

 import { Type } from '@angular/core';
-import { ɵMatomoFeature as MatomoFeature } from 'ngx-matomo-client/core';
+import { MatomoFeature as MatomoFeature } from 'ngx-matomo-client/core';
 import { MatomoRouterConfiguration } from './configuration';
 import { MatomoRouterInterceptor } from './interceptor';
+/**
+ * Additional Matomo router features kind
+ */
+export declare const enum RouterMatomoFeatureKind {
+    /** @see withRouter */
+    Router = "Router",
+    /** @see withRouterInterceptors */
+    RouterInterceptors = "RouterInterceptors",
+    /** @see withRouteData */
+    BuiltInRouteDataInterceptor = "BuiltInRouteDataInterceptor"
+}
 /** Enable automatic page views tracking */
@@ -6,0 +17,0 @@ export declare function withRouter(config?: MatomoRouterConfiguration): MatomoFeature;

router/public-api.d.ts

 export { withRouter, withRouterInterceptors, withRouteData } from './providers';
 export { MatomoRouterModule, NgxMatomoRouterModule } from './matomo-router.module';
-export { MatomoRouterConfiguration, MATOMO_ROUTER_CONFIGURATION, ExclusionConfig, MatomoRouterConfigurationWithInterceptors, } from './configuration';
+export { MatomoRouterConfiguration, MATOMO_ROUTER_CONFIGURATION, ExclusionConfig, MatomoRouterConfigurationWithInterceptors, NavigationEndComparator, } from './configuration';
 export { PageTitleProvider, MATOMO_PAGE_TITLE_PROVIDER } from './page-title-providers';
@@ -5,0 +5,0 @@ export { PageUrlProvider, MATOMO_PAGE_URL_PROVIDER } from './page-url-provider';

schematics/ng-add/index.js

@@ -106,3 +106,3 @@ "use strict";
         .filter(el => el.kind === ts.SyntaxKind.CallExpression)
-        .some(el => el.getText().startsWith('NgxMatomo'));
+        .some(el => el.getText().startsWith('Matomo'));
 }
@@ -134,4 +134,4 @@ function getImportEntryPoints(host, options) {
         const imports = findRelevantImports(source, isRelevantImportPath);
-        let mainModuleIdentifier = 'NgxMatomoModule';
-        let routerModuleIdentifier = 'NgxMatomoRouterModule';
+        let mainModuleIdentifier = 'MatomoModule';
+        let routerModuleIdentifier = 'MatomoRouterModule';
         let asteriskAlias;
@@ -151,6 +151,6 @@ let mainModuleImported = false;
                 if (!mainModuleImported) {
-                    mainModuleIdentifier = `${asteriskAlias}.NgxMatomoModule`;
+                    mainModuleIdentifier = `${asteriskAlias}.MatomoModule`;
                 }
                 if (!routerModuleImported) {
-                    routerModuleIdentifier = `${asteriskAlias}.NgxMatomoRouterModule`;
+                    routerModuleIdentifier = `${asteriskAlias}.MatomoRouterModule`;
                 }
@@ -163,2 +163,3 @@ mainModuleImported = true;
                     switch (specifier.name.text) {
+                        case 'MatomoModule':
                         case 'NgxMatomoModule':
@@ -169,2 +170,3 @@ case 'NgxMatomoTrackerModule':
                             break;
+                        case 'MatomoRouterModule':
                         case 'NgxMatomoRouterModule':
@@ -171,0 +173,0 @@ routerModuleImported = true;

schematics/version.d.ts

@@ -1,1 +0,1 @@
-export declare const version = "^6.1.3";
+export declare const version = "^6.2.0";

schematics/version.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
-exports.version = '^6.1.3';
+exports.version = '^6.2.0';
 //# sourceMappingURL=version.js.map

No alert changes

Improved metrics

Total package byte prevSize

983112

increased by17.72%

Number of package files

156

increased by25.81%

Lines of code

9746

increased by12.97%

Number of lines in readme file

1045

increased by11.65%

No dependency changes