kbc-telemetry

Telemetry module for boilerplate apps, using react-tracking. For more information, see NYTimes React Tracking.

kbc-telemetry also handles when the application goes offline, and refreshes the session (default: set to 1 minute interval checks and ends session after 10 minutes of inactivity).

Usage

Setup

Import and use TelemetryProvider component as a wrapper for your app:

import { TelemetryProvider } from '@kano/kbc-telemetry';

Wrap your app in <TelemetryProvider> (IMPORTANT: this should be a top level wrapper only second to <Router>) and pass config information. To start tracking you will need to pass the trackUser function as props to your App component. If the app is user-less, you can set this to null on app first load.

const config = {
    app: app.name,
    appVersion: app.version
    url: app.url,
    env: app.env,
    trackingInterval?: 1000, // Check and send tracking data to database - Optional
    refreshIdleSessionInterval?: 30 * 1000, // Check if user is still active but not sending events - Optional
    sessionSoftTimeout?: 1 * 60 * 1000, // Soft session timeout default with possibility of a resume_session - Optional
    sessionHardTimeout?: 3 * 60 * 1000, // End the session without possibility of a resume_session event unless another tab has been updating the cookie session - Optional
    refreshCookieInterval?: 1 * 60 * 1000, // Refresh any available cookie session - Optional
    hasCrossDomainStorage?: boolean, //  cross-domain storage opt in/out - Optional
}

render() {
    return (
        <Router>
            <TelemetryProvider config={config}>
                {(trackUser) => (
                    <App trackUser={(userId) => trackUser(userId)} />
                )}
            </TelemetryProvider>
        </Router>
    );
}

Within components

Tracking data can be sent in multiple ways:

Decorators

Either on component level or at method level.

import { track } from '@kano/kbc-telemetry';

@track({ event: 'name_of_your_event' })
class MyComponent extends Component {

    @track({ event: 'I_did_something', action: 'click' })
    handleSomething() {
        // I run something
    }
}

Above shows the initial parameter as an object. But it can also be sent as a function, which accesses 3 parameters component props, component state, function arguments as an array, for example:

@track((props, state, args) => ({ event: props.event, data: { something: state.something, args: args[0] } })
handleSomething(iAmArgsZero) {
    // I run something
}

For decorators, there are explict fields that can be set as follows:

| Decorator | Field Options | | --------------------------- | ---------------- | | @track() | event?: String data?: Any action?: String module?: String | | @trackError() | error: { name: String, stack: String, message: String } |

Props

You can also use as props: this.props.tracking.trackEvent({}). This currently doesn't enforce the field options above.

To use tracking in props, the component must be wrapped using one of the 3 options below:

Opt 1) export / track()(Comp)

Wrapping it in track(), as follows (NOTE: the decorator must be passed an event object, the most common way to do this is by passing a module property - if you do not wish to pass anything please see Opt 3):

import { track, ITrackingProps } from '@kano/kbc-telemetry';

const FooComp = (props: ITrackingProps) => {
	return <div onClick={() => props.tracking.trackEvent({ action: 'click' })} />;
}

export default track({
  module: 'FooComp',
})(FooComp);

Opt 2) decorator / @track()class

Wrapping it with the @track({ }) decorator (NOTE: the decorator must be passed an event object, the most common way to do this is by passing a module property - if you do not wish to pass anything please see Opt 3):

import { track, ITrackingProps } from '@kano/kbc-telemetry';

@track({ module: 'MyComponent' })
class MyComponent extends Component<any, ITrackingProps> {
	handleSomething() {
	    this.props.tracking.trackEvent({ event: 'i_handle_something' })
	}
}

Opt 3) HOC / withTracking

Wrapping your exported component using the withTracking higher order component:

import { withTracking, ITrackingProps } from '@kano/kbc-telemetry';

class MyComponent extends Component<any, ITrackingProps> {
	handleSomething() {
	    this.props.tracking.trackEvent({ event: 'i_handle_something' })
	}
}

export default withTracking(FooComp);

Hooks

You can also gain access to the tracking.trackEvent({}) using the useTracking react hook:

import { useTracking } from '@kano/kbc-telemetry';

const MyComp = () => {
    const tracking = useTracking();

    const handleTrackedClick = () => {
        tracking.trackEvent({ event: 'omg' });
    }

    return {
        <button onClick={handleTrackedClick}>Omg please track me</button>
    }
}

Tracking Errors

Currently trackError can only be used as a decorator. See below and see field options in the table above.

@trackError({ error: { name: 'handle_error', stack: 'stack', message: 'message' } })
handleError() {
    // I handle an error
}

If you want to track errors using props, you can follow the same principles as above (using trackEvent as the function) but just pass an error event:

handleSomething() {
        this.props.tracking.trackEvent({ error: { name: 'handle_error', stack: 'stack', message: 'message' } })
}

Offline Client

The TelemetryProvider is wrapped with the OfflineClientProvider, this will pass down the status of online when the application changes from online to offline and vice versa. If all apps are wrapped with the TelemetryProvider, a hoc withOfflineClient can be used on any component of the application, for example:

const Editor = withOfflineClient(EditorComponent);
export Editor;

You can either listen to changes in componentDidUpdate for the offlineClient.online or to check the current status you can call offlineClient.getOnlineStatus.

Alternatively, if the application is not wrapped in the TelemetryProvider, you can use the OfflineClientProvider as a standalone component:

<OfflineClientProvider>
    {({ offlineClient: { online } }: IOfflineClientAPI) => {
        <App {...offlineClient} />
    }}
</OfflineClientProvider>