ngx-matomo-client
Version:
Matomo (fka. Piwik) client for Angular applications
211 lines (210 loc) • 10.1 kB
TypeScript
import { InjectionToken } from '@angular/core';
/** Internal marker token to detect that router has been enabled */
export declare const MATOMO_ROUTER_ENABLED: InjectionToken<boolean>;
/** Injection token for {@link MatomoConfiguration} */
export declare const MATOMO_CONFIGURATION: InjectionToken<MatomoConfiguration>;
/**
* For internal use only. Injection token for {@link InternalMatomoConfiguration}
*
*/
export declare const INTERNAL_MATOMO_CONFIGURATION: InjectionToken<InternalMatomoConfiguration>;
export declare function createInternalMatomoConfiguration(): InternalMatomoConfiguration;
/**
* For internal use only. Injection token for deferred {@link InternalMatomoConfiguration}.
*
*/
export declare const DEFERRED_INTERNAL_MATOMO_CONFIGURATION: InjectionToken<DeferredInternalMatomoConfiguration>;
export declare function createDeferredInternalMatomoConfiguration(): DeferredInternalMatomoConfiguration;
/**
* For internal use only. Injection token for fully loaded async {@link InternalMatomoConfiguration}.
*
*/
export declare const ASYNC_INTERNAL_MATOMO_CONFIGURATION: InjectionToken<Promise<InternalMatomoConfiguration>>;
/**
* For internal use only. Module configuration merged with default values.
*
*/
export type InternalMatomoConfiguration = Omit<MatomoConfiguration, 'mode' | 'requireConsent'> & Omit<Required<BaseMatomoConfiguration>, 'requireConsent'> & {
mode?: MatomoInitializationBehavior;
requireConsent: MatomoConsentRequirement;
};
export interface DeferredInternalMatomoConfiguration {
readonly configuration: Promise<InternalMatomoConfiguration>;
markReady(configuration: InternalMatomoConfiguration): void;
}
/**
* - __auto__: automatically inject matomo script using provided configuration
* - __manual__: do not inject Matomo script. In this case, initialization script must be provided
* - __deferred__: automatically inject matomo script when deferred tracker configuration is provided using `MatomoInitializerService.initializeTracker()`.
*/
export type MatomoInitializationBehavior = 'auto' | 'manual' | 'deferred';
/** @deprecated Use {@link MatomoInitializationBehavior} instead */
export declare enum MatomoInitializationMode {
/**
* Automatically inject matomo script using provided configuration
*
* @deprecated Use `'auto'` instead
*/
AUTO = 0,
/**
* Do not inject Matomo script. In this case, initialization script must be provided
*
* @deprecated Use `'manual'` instead
*/
MANUAL = 1,
/**
* Automatically inject matomo script when deferred tracker configuration is provided using `MatomoInitializerService.initializeTracker()`.
*
* @deprecated Use `'deferred'` instead
*/
AUTO_DEFERRED = 2
}
export declare function coerceInitializationMode(value: MatomoInitializationBehaviorInput): MatomoInitializationBehavior;
export type MatomoConsentRequirement = 'none' | 'cookie' | 'tracking';
/** @deprecated Use {@link MatomoConsentRequirement} instead */
export declare enum MatomoConsentMode {
/** Do not require any consent, always track users */
NONE = 0,
/** Require cookie consent */
COOKIE = 1,
/** Require tracking consent */
TRACKING = 2
}
export declare function coerceConsentRequirement(value: MatomoConsentMode | MatomoConsentRequirement): MatomoConsentRequirement;
export interface MatomoTrackerConfiguration {
/** Matomo site id */
siteId: number | string;
/** Matomo server url */
trackerUrl: string;
/** The trackerUrlSuffix is always appended to the trackerUrl. It defaults to matomo.php */
trackerUrlSuffix?: string;
}
export interface MultiTrackersConfiguration {
/**
* Configure multiple tracking servers. <b>Order matters: if no custom script url is
* provided, Matomo script will be downloaded from first tracker.</b>
*/
trackers: MatomoTrackerConfiguration[];
}
export interface BaseMatomoConfiguration {
/** Set to `true` to disable tracking */
disabled?: boolean;
/** If `true`, track a page view when app loads (default `false`) */
trackAppInitialLoad?: boolean;
/**
* Configure link clicks tracking
*
* If `true` (the default value), enable link tracking, excluding middle-clicks and contextmenu events.
* If `enable-pseudo`, enable link tracking, including middle-clicks and contextmenu events.
* If `false`, to disable this Matomo feature (default `true`).
*
* Used when {@link trackAppInitialLoad} is `true` and when automatic page tracking is enabled.
*
* @see {@link MatomoTracker.enableLinkTracking} for more details
*/
enableLinkTracking?: boolean | 'enable-pseudo';
/** Set to `true` to not track users who opt out of tracking using <i>Do Not Track</i> setting */
acceptDoNotTrack?: boolean;
/**
* Configure user consent requirement
*
* To identify whether you need to ask for any consent, you need to determine whether your lawful
* basis for processing personal data is "Consent" or "Legitimate interest", or whether you can
* avoid collecting personal data altogether.
*
* Matomo differentiates between cookie and tracking consent:
* - In the context of <b>tracking consent</b> no cookies will be used and no tracking request
* will be sent unless consent was given. As soon as consent was given, tracking requests will
* be sent and cookies will be used.
* - In the context of <b>cookie consent</b> tracking requests will always be sent. However,
* cookies will be only used if consent for storing and using cookies was given by the user.
*
* Note that cookies impact reports accuracy.
*
* See Matomo guide: {@link https://developer.matomo.org/guides/tracking-consent}
*/
requireConsent?: MatomoConsentRequirement | MatomoConsentMode;
/** Set to `true` to enable Javascript errors tracking as <i>events</i> (with category <i>JavaScript Errors</i>) */
enableJSErrorTracking?: boolean;
/** Set to `true` to run matomo calls outside of angular NgZone. This may fix angular freezes. */
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;
}
/**
* Mapping type to extend input types with legacy `MatomoInitializationMode` type
*
* TODO remove when `MatomoInitializationMode` is removed
*/
export interface MatomoInitializationBehaviorInputMapping {
manual: MatomoInitializationMode.MANUAL;
auto: MatomoInitializationMode.AUTO;
deferred: MatomoInitializationMode.AUTO_DEFERRED;
}
/**
* Special type to map a `MatomoInitializationBehavior` to either itself or the legacy equivalent `MatomoInitializationMode`
*
* @example
* MatomoInitializationBehaviorInput<'auto'>
* // Equivalent to:
* 'auto' | MatomoInitializationMode.AUTO
*
* MatomoInitializationBehaviorInput<'manual'>
* // Equivalent to:
* 'manual' | MatomoInitializationMode.MANUAL
*
* MatomoInitializationBehaviorInput<'deferred'>
* // Equivalent to:
* 'deferred' | MatomoInitializationMode.AUTO_DEFERRED
*
* TODO remove when `MatomoInitializationMode` is removed and use `MatomoInitializationBehavior` instead
*/
export type MatomoInitializationBehaviorInput<T extends MatomoInitializationBehavior = MatomoInitializationBehavior> = T | MatomoInitializationBehaviorInputMapping[T];
export interface BaseAutoMatomoConfiguration<M extends 'auto' | 'deferred' = 'auto'> {
/**
* Set the script initialization mode (default is `'auto'`)
*
* @see MatomoInitializationBehavior
*/
mode?: MatomoInitializationBehaviorInput<M>;
/** Matomo script url (default is `matomo.js` appended to main tracker url) */
scriptUrl: string;
}
type Without<T, U> = {
[P in Exclude<keyof T, keyof U>]?: never;
};
type XOR<T, U> = T | U extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
type XOR3<T, U, V> = XOR<T, XOR<U, V>>;
export type ManualMatomoConfiguration = {
/**
* Set the script initialization mode (default is `'auto'`)
*
* @see MatomoInitializationBehavior
*/
mode: MatomoInitializationBehaviorInput<'manual'>;
};
export type DeferredMatomoConfiguration = {
/**
* Set the script initialization mode (default is `'auto'`)
*
* @see MatomoInitializationBehavior
*/
mode: MatomoInitializationBehaviorInput<'deferred'>;
};
export type ExplicitAutoConfiguration<M extends 'auto' | 'deferred' = 'auto'> = Partial<BaseAutoMatomoConfiguration<M>> & XOR<MatomoTrackerConfiguration, MultiTrackersConfiguration>;
export type EmbeddedAutoConfiguration<M extends 'auto' | 'deferred' = 'auto'> = BaseAutoMatomoConfiguration<M> & Partial<MultiTrackersConfiguration>;
export type AutoMatomoConfiguration<M extends 'auto' | 'deferred' = 'auto'> = XOR<ExplicitAutoConfiguration<M>, EmbeddedAutoConfiguration<M>>;
export type MatomoConfiguration = BaseMatomoConfiguration & XOR3<AutoMatomoConfiguration, ManualMatomoConfiguration, DeferredMatomoConfiguration>;
export declare function isAutoConfigurationMode(config: MatomoConfiguration | InternalMatomoConfiguration): config is AutoMatomoConfiguration;
export declare function isEmbeddedTrackerConfiguration<M extends 'auto' | 'deferred'>(config: AutoMatomoConfiguration<M>): config is EmbeddedAutoConfiguration<M>;
export declare function isExplicitTrackerConfiguration<M extends 'auto' | 'deferred'>(config: AutoMatomoConfiguration<M>): config is ExplicitAutoConfiguration<M>;
export declare function isMultiTrackerConfiguration(config: AutoMatomoConfiguration<'auto' | 'deferred'>): config is MultiTrackersConfiguration;
export declare function getTrackersConfiguration(config: ExplicitAutoConfiguration<'auto' | 'deferred'>): MatomoTrackerConfiguration[];
export {};