Nothing Particularly Magnificent

    piral-tracking
    TypeScript icon, indicating that this package has built-in type declarations

    0.14.9 • Public • Published

    Piral Logo

    Piral Tracking · GitHub License npm version tested with jest Gitter Chat

    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.

    Install

    npm i piral-tracking

    Homepage

    piral.io

    DownloadsWeekly Downloads

    430

    Version

    0.14.9

    License

    MIT

    Unpacked Size

    28.5 kB

    Total Files

    25

    Last publish

    Collaborators

    • florianrappl