@kano/kbc-telemetry

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> (this should be the top level wrapper) and pass config information.

const config = {
    app: app.name,
    appVersion: app.version
    url: app.url,
    env: app.env
    interval: 10000 // How frequently you want the telemetry data sent to your database
    sessionTimeout?: number in milliseconds; // Optional
    refreshInterval?: number in milliseconds; // Optional
}

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

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:

@Telemetry.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 userId?: String page?: 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 either exported by wrapping it in track(), as follows:

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

export default track({
  page: 'FooPage',
})(FooPage);

OR

Wrapped in a decorator:

@track({ page: 'MyComponent' })
class MyComponent extends Component {
	handleSomething() {
	    this.props.tracking.trackEvent({ event: 'i_handle_something' })
	}
}

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):

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