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.
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.
We also have a video for this plugin:
The following functions are brought to the Pilet API.
Tracks a custom event incl. properties and other standard metrics.
Tracks an error or exceptional behavior incl. properties.
Starts a tracking frame. The frame can be ended via the returned callback.
::: 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 });
});
:::
The extension gives the core a set of new events to be listened to:
track-event
track-error
-
track-frame-start
andtrack-frame-end
The events are fully typed.
Piral is released using the MIT license. For more information see the license file.