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. Also to recieve the start of session event and to create your session_id
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
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}>
{(trackUser) => (
<App trackUser={(userId) => trackUser(userId)} />
)}
</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:
@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:
import { track, ITrackingProps } from '@kano/kbc-telemetry';
const FooPage = (props: ITrackingProps) => {
return <div onClick={() => props.tracking.trackEvent({ action: 'click' })} />;
}
export default track({
page: 'FooPage',
})(FooPage);
OR
Wrapped in a decorator:
import { track, ITrackingProps } from '@kano/kbc-telemetry';
@track({ page: 'MyComponent' })
class MyComponent extends Component<any, ITrackingProps> {
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' } })
}
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>