Skip to main content

Analytics - Vivid Module

Simple module to be used in apps and landing pages to add tracking and monitoring.

Installation​

$ yarn add @rexlabs/analytics

Usage​

import {
  // dealing with handlers
  setHandlers,
  addHandler,
  removeHandler,

  // init with handlers
  // this is what you usually want to do in your apps index.{js,ts,tsx}
  initWithHandler,
  initWithSegmentHandler,

  // generic tracking methods
  init,
  identify,
  custom,
  error,
  performance,
  navigation,
  information,
  track
} from '@rexlabs/analytics';

// Providers, for manual use of specific services
// Please use segment instead if possible
import Bugsnag from '@rexlabs/analytics/lib/providers/bugsnag';
import FacebookPixel from '@rexlabs/analytics/lib/providers/facebook-pixel';
import FullStory from '@rexlabs/analytics/lib/providers/full-story';
import GoogleAdwords from '@rexlabs/analytics/lib/providers/google-adwords';
import GoogleTagManager from '@rexlabs/analytics/lib/providers/google-tag-manager';
import Tawk from '@rexlabs/analytics/lib/providers/tawk';

Handlers​

Handlers are like middleware, that gets triggered whenever you run, init, identify, error, performance, navigation, information or track. The idea is that we can implement analytics in our apps independent from the underlying implementation detail, enabling us to swap out whatever 3rd party we're using under the hood without any extra changes in the app code needed.

For our apps, we primarily want to use Segment, so please avoid using other services directly if possible. An exception currently is Bugsnag, since Segment includes an outdates version of it and we want to use the latest version.

Segment​

import { initWithSegment } from '@rexlabs/analytics';
initWithSegment({ id: SEGMENT_KEY, appName: 'yourAppName' });

That's it. After you initialised with the segment handler, every event you're tracking will be handled by it. 😊

By default, the node handler is not included in the main package exports (to not accidentially include any of the code in our web bundles). If you want to track anything through segment in node scripts, you can do the following:

const { initWithHandler } = require('@rexlabs/analytics');
const segmentHandler = require('@rexlabs/analytics/lib/handlers/segment/node');

initWithHandler(segmentHandler, { id: SEGMENT_KEY, appName: 'yourAppName' });

Providers (Components)​

These might be useful if you can't or don't want to use a handler (like our Segment handler) for certain things.

Bugsnag​

We don't run Bugsnag through Segment at the moment, because Segment uses an outdated version (we'll need to revisit that to make sure they haven't updated their version!). For that reason, you'll want to add the bugsnag provider manually ot your app, even if you're using the Segment handler.

import Bugsnag from '@rexlabs/analytics/lib/providers/bugsnag';

function App() {
  return (
    <RandomProviders>
      <Bugsnag
        apiKey={config.BUGSNAG_API_KEY}
        releaseStage={config.RELEASE?.STAGE}
        appVersion={config.RELEASE?.VERSION}
      />
      <AppContent />
    </RandomProviders>
  );
}

Facebook Pixel​

...

FullStory​

...

Adwords​

...

Google Tag Manager​

...

Tawk​

...

Webpack plugin for bundle size tracking​

This plugin will allow you to hook into webpacks final step to send bundle size stats to your analytics provider, e.g.:

// .plzrc.js
const env = require('./env');
const { initWithHandler, track } = require('@rexlabs/analytics');
const webpack = require('@rexlabs/analytics/lib/addons/webpack');
const segmentHandler = require('@rexlabs/analytics/lib/handlers/segment/node');

const BundleSizeReporterPlugin = webpack.default;

initWithHandler(segmentHandler.default, {
  id: env.SEGMENT_ID,
  appName: 'yourAppName'
});

module.exports = {
  // whatever else is in your plz config
  webpack: (config) => {
    if (process.env.NODE_ENV === 'production') {
      config.plugins.push(
        new BundleSizeReporterPlugin({
          handleStats: (stats) => {
            stats.assets.forEach((asset) => {
              track({
                eventName: 'fe_bundle_asset',
                data: {
                  commitHash: stats.hash,
                  name: asset.__name,
                  realName: asset.name,
                  size: asset.size,
                  parsedSize: asset.parsedSize,
                  gzipSize: asset.gzipSize
                }
              });
            });
          }
        })
      );
    }
    return config;
  }
};

Right now this is fairly manual, to give you full control over the handler. The plan is too abstract this out into a SegmentBundleSizeReporterPlugin to be able to adjust and improve it across all our apps over time easily.

Lighthouse reporter​

This package also provides a lighthouse reporter, which is a node script that will run your app through puppeteer and will then run lighthouse reporting on the urls your provide. You can then pass the report through to your analytics handler of choice. E.g.:

#! /usr/bin/env node

const { initWithHandler, track } = require('@rexlabs/analytics');
const { createReport } = require('@rexlabs/analytics/lib/addons/lighthouse');
const segmentHandler = require('@rexlabs/analytics/lib/handlers/segment/node');

const env = require('../../env');

initWithHandler(segmentHandler.default, {
  id: env.SEGMENT_ID,
  appName: 'yourAppName'
});

(async () => {
  const report = await createReport({
    baseUrl: 'https://your-app-url.com',
    urls: ['/contacts', '/properties', '/tenancies'],
    auth: () => {
      // allows you to run anything before the lighthouse reports
      // usually to set the local storage for API auth etc.
    }
  });

  Object.keys(report.urls).forEach((url) => {
    track({ eventName: 'lighthouse_report', data: report.urls[url] });
  });
})();

Copyright (c) 2020 Rex Software All Rights Reserved.