# @kano/kbc-telemetry

> Telemetry module for boilerplate apps, using react-tracking

Latest version **5.0.14** (published 2023-02-17) · ISC license · 0 weekly downloads

## Install

```sh
npm install @kano/kbc-telemetry
pnpm add @kano/kbc-telemetry
yarn add @kano/kbc-telemetry
bun add @kano/kbc-telemetry
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.14 |
| Published | 2023-02-17 |
| First published | 2020-02-13 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 14 |
| Unpacked size | 54.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Kano Computing |
| Maintainers | petarsimonovic, aetheern, kimonsatan, sophioski, hediho, ellenw3lsh, melissakano, camuskano, jacobmorgan99, alexfiennes, kanocomputing, rpazdera, hicksatkano, holographicleah, tomkano, alexb-kano, jamie_old_plantain |

## Links

- npm: https://www.npmjs.com/package/@kano/kbc-telemetry
- npm.io page: https://npm.io/package/@kano/kbc-telemetry

## Dependencies (14)

- [@types/react](https://npm.io/package/@types/react.md) ^16.14.2
- [@kano/kbc-intl](https://npm.io/package/@kano/kbc-intl.md) ^2.0.13
- [fingerprintjs2](https://npm.io/package/fingerprintjs2.md) ^2.1.2
- [react-tracking](https://npm.io/package/react-tracking.md) ^7.3.0
- [@kano/kbc-icons](https://npm.io/package/@kano/kbc-icons.md) ^2.2.24
- [@kano/kbc-toast](https://npm.io/package/@kano/kbc-toast.md) ^2.0.61
- [@kano/kbc-utils](https://npm.io/package/@kano/kbc-utils.md) ^2.2.4
- [@kano/kbc-button](https://npm.io/package/@kano/kbc-button.md) ^3.0.48
- [@types/react-dom](https://npm.io/package/@types/react-dom.md) ^16.9.10
- [react-router-dom](https://npm.io/package/react-router-dom.md) ^5.2.0
- [react-detect-offline](https://npm.io/package/react-detect-offline.md) ^2.4.0
- [@types/fingerprintjs2](https://npm.io/package/@types/fingerprintjs2.md) ^2.0.0
- [@types/react-tracking](https://npm.io/package/@types/react-tracking.md) ^7.0.2
- [@types/react-router-dom](https://npm.io/package/@types/react-router-dom.md) ^5.1.6

## Recent versions

- 5.0.14 (latest) — 2023-02-17
- 5.0.13 — 2023-02-14
- 5.0.12 — 2023-01-30
- 5.0.11 — 2023-01-27
- 5.0.10 — 2023-01-26
- 5.0.9 — 2023-01-10
- 5.0.8 — 2022-12-05
- 5.0.7 — 2021-11-26
- 5.0.6 — 2021-11-26
- 5.0.5 — 2021-11-25
- 5.0.4 — 2021-11-25
- 5.0.3 — 2021-11-08
- 5.0.2 — 2021-10-05
- 5.0.1 — 2021-10-01
- 5.0.0 — 2021-09-30
- … 150 more at https://npm.io/package/@kano/kbc-telemetry/versions

## README

# kbc-telemetry

Telemetry module for boilerplate apps, using `react-tracking`. For more information, see [NYTimes React Tracking](https://github.com/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` <br/> `data?: Any` <br/> `action?: String` <br/> `module?: String` |
| `@trackError()`             | `error: ` <br/> `{ 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>
```

---
_Source: https://npm.io/package/@kano/kbc-telemetry · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._