Familiarize yourself with the tracker API.

While this library does not have a dependency on Redux, it is most suited for apps that use it. The benefits of unidirectional data flow and action-oriented design should not be overlooked for interactive web apps.

If you haven't used Redux, you may want to read this 5-minute overview first to understand the problem it solves and its core components.

Code for this library is written in TypeScript for static checking.

Provides options to control the Middleware's runtime behavior.

type MiddlewareSettings= {

  // current environment: "development" | "production"
  env: Env;
  
  // prevents auto loading and initialization of vendor sdk
  preventAutoLoadInit?: boolean;

  // allows auto anonymizing of property values in userData for tracking actions
  anonymizeUserData?: string[];

  // allow, restrict or filter flow of actions out the middleware
  relayActions?: boolean | Partial<Record<ActionTypeKeys, boolean>>;
};

Set preventAutoLoadInit: true if vendor SDK will be initialized manually on the page. For the case when vendor SDK is available on the page and preventAutoLoadInit is false (or not provided), the middleware will skip to initialization so the SDK does not get included twice.

Pass an array of keys to anonymizeUserData: ['userId'] to anonymize values in userData. If this option is not provided, value of the userId property will be anonymized by default. To override this behavior, pass an empty array.

relayActions is an optimization to the default middleware behavior where only certain actions are allowed to flow. The option allows you to restrict all relayActions: false or restrict none relayActions: true. Alternatively you can provide an object to override the default filtering. For example, the setting relayActions: { LOAD: true, TRACK: false }, makes LOAD flow through and hit the reducers layer while TRACK will be swallowed by the middleware.

These options are passed on to the Vendor API during initialization. The only required option is the apiKey.

type VendorAPIOptions = {
  // public api key to use for SDK initialization
  apiKey: string;
};

Note that VendorAPIOptions is a base type, which can be extended by the Vendor's implementation. This allows multiple Vendors to accept their version of options while providing type checking during development. Checkout Amplitude's API options as an example.

type AmplitudeAPIOptions = VendorAPIOptions & {
  deviceId?: string;
  logLevel?: 'DISABLE' | 'ERROR' | 'WARN' | 'INFO';
  optOut?: boolean;
  platform?: string;
  trackingOptions?: Partial<TrackingOptions>;
  saveEvents?: boolean;
  sessionTimeout?: number;
};

This section describes the default tracking behavior and how to override it.

For security or privacy purposes, tracking can be completely turned off for a given user using one of the two methods:

For example, in AmplitudeAPIOptions setting optOut=true will disable tracking for the current user.

The way your app provides VendorAPIOptions is interesting. If you recall, the createTrackerStoreEnhancer accepts a function that returns a Promise. This gives your app the control to load the necessary data (that determines optOut) before initializing the vendor API. Tracking actions dispatched before initialize will be saved in a buffer, and processed once the API is initialized.

At any give time, you can manually control the tracking behavior by dispatching PAUSE_TRACKING and RESUME_TRACKING actions. Use respective actions creators: pauseTracking and resumeTracking.

In development mode (on localhost), Tracker will pause tracking activity before API initialize call to prevent unnecessary tracking. To override this behavior, you can use a back door.

In Chrome developer tools:

• window.localhostTracking.on() - resume tracking for localhost
• window.localhostTracking.clear() - pause tracking for localhost
• window.localhostTracking.status() - current tracking status

This section describes various action types used by the tracker API to communicate with your app and internally. It is important to note that each action is prefixed with "[vendorKey]". For Amplitude, for instance, tracking action types begin with "[amplitude]".

Actions are grouped by when they occur (page lifecycle) and their use.

These actions are used to fetch and initialize the Vendor SDK on the web page. Typically you won't need to use any of these actions as they are invoked automatically on page load.

To disable LOAD and INIT from triggering automatically, set preventAutoLoadInit: true in MiddlewareSettings.

Actions LOAD_DONE, INIT_DONE, and INIT_ERR represent outcomes of processing these two actions: LOAD, INIT.

These are the actions you'll be working with the most. Use these actions to report tracking activity in your app. If the action is invoked prior to SDK initialize, the requested action will be automatically queued by the SET_PENDING_ACTION action and later processed via DISPATCH_PENDING_ACTIONS on INIT_DONE.

Actions TRACK_DONE, TRACK_ERR represent outcomes of processing the TRACK action. These notification actions reference the original tracking action through the meta property. TRACK_DONE will have an additional property: anonymizedUserData: true implying that value(s) in userData was hashed. To control the anonymization behavior, see anonymizeUserData in MiddlewareSettings.

Use these actions to override default tracking behavior. On localhost, PAUSE_TRACKING is automatically triggered to prevent automatic logging of unnecessary events during code development. To turn on tracking on localhost, call window.localhostTracking.on() in your developer console. This will trigger the RESUME_TRACKING action.

Use TERMINATE_USER_SESSION to stop tracking activity for the current user.