piral-tracking

Piral Tracking ·

This is a plugin that only has a peer dependency to piral-core. What piral-tracking brings to the table is a set of Pilet API extensions that can be used with piral or piral-core.

The set includes the track... APIs to be used in pilets for using a set of analytics, telemetry, and tracking tools from your Piral instance.

By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

Why and When

Quite often somebody is interested how a particular action was done. Which button was clicked? How far was the webpage scrolled? The tracker tools are among the standard reportoire to cover these questions. The problem in a distributed context is "how to reach them"? Should every microfrontend come up with their own tracking solution?

Usually, the answer to this should be no. This plugin gives you an abstraction that can be used with almost any tracking solution. The abstraction allows each pilet to use a common API to track.

Alternatives: Use your preferred tracking application standalone.

Video

We also have a video for this plugin:

@youtube

Documentation

The following functions are brought to the Pilet API.

trackEvent()

Tracks a custom event incl. properties and other standard metrics.

trackError()

Tracks an error or exceptional behavior incl. properties.

trackFrame()

Starts a tracking frame. The frame can be ended via the returned callback.

Usage

::: summary: For pilet authors

You can use the trackEvent function from the Pilet API to track a custom event with an arbitrary definition.

Example use:

import { PiletApi } from '<name-of-piral-instance>';

export function setup(piral: PiletApi) {
  piral.trackEvent('sample-pilet-ready');
}

You can use the trackError function from the Pilet API to track an error from the pilet.

Example use:

import { PiletApi } from '<name-of-piral-instance>';

export function setup(piral: PiletApi) {
  try {
    throw new Error('Ouch!');
  } catch (e) {
    piral.trackError(e);
  }
}

You can use the trackFrame function from the Pilet API to track a custom event with integrated running time measurement.

Example use:

import { PiletApi } from '<name-of-piral-instance>';

export function setup(piral: PiletApi) {
  const frame = piral.trackFrame('sample-pilet-computation');

  setTimeout(() => {
    frame();
  }, 4000);
}

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createTrackingApi from the piral-tracking package.

import { createTrackingApi } from 'piral-tracking';

The integration looks like:

const instance = createInstance({
  // important part
  plugins: [createTrackingApi()],
  // ...
});

There are no options available.

The integration of other trackers is done by listening to the events. Example for Application Insights:

import { createInstance } from 'piral';
import { createTrackingApi } from 'piral-tracking';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';

const appInsights = new ApplicationInsights({
  // ...
});

appInsights.loadAppInsights();

const instance = createInstance({
  plugins: [createTrackingApi()]
});

instance.on('track-event', evt => {
  const name = evt.name;
  const properties = {
    ...evt.properties,
    piletName: evt.pilet,
  };
  appInsights.trackEvent({ name, properties });
});

:::

Events

The extension gives the core a set of new events to be listened to:

• track-event
• track-error
• track-frame-start and track-frame-end

The events are fully typed.

License

Piral is released using the MIT license. For more information see the license file.

Changelog

1.9.0 (tbd)

• Fixed platform providers for piral-ng with Angular 20 in non-standalone form (#764)
• Fixed debug mode deserialization in case of modifications from other security contexts (#775)
• Removed container property from the unhandled-error event arguments (#777)
• Improved dialog order in piral-modals (#773) by @pranav-hsg
• Improved output when installation of packages fails (#759)
• Improved error message when template resolution fails (#763)
• Updated some dependencies such as axios (#765)
• Updated dets to latest release
• Updated piral-cli-webpack5 to never output empty main.css files in pilets
• Updated piral-oidc to use up-to-date oidc-client-ts instead of discontinued oidc-client library (#769)
• Added support for Angular 20 in piral-ng
• Added warning in piral-cli when shared dependencies are wrongly declared (#768)
• Added support for Promise-based Webpack configuration files in piral-cli-webpack5 (#774) by @grant-progress
• Added remoteTypesSource to piral.json for specifying an URL for extra declarations
• Added remoteTypesTarget to pilet.json for storing obtained extra declarations locally