React-spy NPM | npm.io

React Spy

A set of utilities for collecting UX-analytics of your React-application (ex: clicks, shows, errors and etc.)

npm i --save react-spy

Features

Easy integration with any ui-library (ex: Ant-Design)
Full control over the events

API

spy — decorator of react-components
- spy.send — send stats from the component and not only
- spy.error — send an error from the component and not only
addSpyObserver — add observer of events
addSpyErrorObserver — add observer of errors
intercept — intercepting a chain of events
Components
- Spy
- SpyStep
Low Level
- broadcast — broadcast any chain of events
- broadcastError — broadcast any error

Usage

For example with Google Analytics

// Btn.js
import {spy} from 'react-spy';

const Btn = ({name, value}) => (<button name={name}>{value}</button>);
export default spy({
	id: ({name}) => name, // Computed `id` on based component properties
	listen: ['click'],    // DOM-events list
})(Btn);


// LoginForm.js
import {spy} from 'react-spy';

class LoginForm extends React.Component {
	// ...
	handleSubmit(evt) {
		evt.preventDefault();
		try {
			await api.login(this.getFormData());
			spy.send(this, 'success');
		} catch (err) {
			spy.send(this, 'failed', err);
		}
	}

	render() {
		return (
			<form onSubmit={this.handleEvent}>
				{/* ... */}
				<Btn name="login" value="Sign In"/>
				<Btn name="forgot" value="Forgot password"/>
			</form>
		);
	}
}

export default spy({
	id: "login-form",
	host: true,
	listen: ['mount', 'unmount'],
})(LoginForm);


// boot.js
import {addSpyObserver, addSpyErrorObserver} from 'react-spy';

addSpyObserver(chain => {
	// Send to GA
	ga('send', {
		hitType: 'event',
		eventCategory: chain[0], // ex: "login-form"
		eventAction: chain.slice(1).join('_'), // ex: "forgot_click"
	});
});

// Component Errors
addSpyErrorObserver(({error}) => {
	ga('send', 'exception', {
		exDescription: error.message,
		exFatal: false,
	});
});

ReactDOM.render(<App/>, document.body);

`spy<Props>(options)`

Decorate the component to collect analytics

options
- id: string | (props, context?) => string — default @see propName description
- propName: string — prop-name for id, by default spyId
- listen: string[] — DOM-events to listen + error, mount and unmount
- callbacks — list of observed callbacks that are passed to it via props
- propName: string — name of the property responsible for the spy's id, by defaultspyId
- host: boolean

import {spy} from 'react-spy';

export default spy({
	id: ({name}) => name,
	listen: ['click'],
})(function Btn({value}) {
	return <button>{value}</button>;
})

// Somewhere in the code
<Btn
	name="login"
	value="Sign in"
/>
// *click* -> ["login", "click"]

`spy.send(cmp: React.Component, chain: string | string [], detail?: object): void`

Send stats from the component and not only

cmp: React.Component — instance of React.Component
chain: string | string[] — name of metric
detail: object

import {spy} from 'react-spy';

export default spy({id: 'parent'})(class Box extends React.Component {
	render() {
		return (
			<button onClick={() => {spy.send(this, 'foo');}}>First</button>
			<button onClick={() => {spy.send(this, ['bar', 'baz'], {val: 123});}}>Second</button>
		);
	}
});

// Somewhere in a code
//   click on <First>:
//     - ["parent", "foo"] {}
//   click on <Second>:
//     - ["parent", "bar", "baz"] {val: 123}
//
// Somewhere in an another place:
//    spy.send(['global', 'label'], {time: 321}):
//      - ["global", "label"] {time: 321}

`spy.error(cmp: React.Component, chain: string | string [], error: Error): void`

send an error from the component and not only

cmp: React.Component — instance of React.Component
chain: string | string[] — name of metric
error: Error — any an error

`addSpyObserver(fn: (chain: string[], detail: object) => void): UnsubsriberFn`

Add observer of events for sending to the accounting system of analytics

import {addSpyObserver} from 'react-spy';

const unsubscribe = addSpyObserver(chain => {
	// Send to GA
	ga('send', {
		hitType: 'event',
		eventCategory: chain[0], // ex: "login-form"
		eventAction: chain.slice(1).join('_'), // ex: "forgot_click"
	});
});

// Somewhere (if you need to)
unsubscribe();

`addSpyErrorObserver(fn: (detail: ErrorDetail) => void): UnsubsriberFn`

Add observer of component errors

detail
- error: Error — JavaScript error
- info: object — React error info
- chain string[] — spy id chain

import {addSpyErrorObserver} from 'react-spy';

addSpyErrorObserver(({error, chain}) => {
	// Send to GA
	ga('send', 'exception', {
		exDescription: error.message,
		exFatal: false,
	});

	// For dev
	console.error('[react-spy]', chain.join(' -> '));
	console.error(error);
});

`intercept(rules: InterceptRules)`

Intercepting a chain of events

import {intercept, UNCAUGHT} from 'react-spy';

intercept({
	'login-form': {
		// Interception of all chains, ex:
		//  - ["login-form", "forgot", "mount"]
		//  - ["login-form", "forgot", "click"]
		//  - etc
		'forgot'(send, chain, detail) {
			send(chain.concat('additional-id'));
		},

		// Processing of non-intercepted chains, ex:
		//  - ["login-form", "login", "click"]
		[UNCAUGHT](send, chain) {
			send(chain.concat('UNCAUGHT'));
			return false; // continue;
		}
	},
});

`<Spy>...</Spy>`

import {Spy} from 'react-spy';

const SomeFragment = ({condition, onShowDetail}) => (
	<div>
		<Spy id="top">
			<Button name="detail" value="Show detail" onClick={onShowDetail}/>
		</Spy>

		{condition &&
			<Spy id="bottom" listen={['mount', 'unmount'}>
				Detail
			</Spy>
		}
	</div>
);

// 1. *click on button* -> ["top", "detail", "click"]
// 2. *mounting* -> ["bottom", "mount"]

`<SpyStep name="..."/>`

The hidden spy element for steps monitoring

name: string — a step name
enter: string | string[] — the enter phase (optional)
leave: string | string[] — the leave phase (optional)

`broadcast(chain: string[], detail?: object)`

import {broadcast} from 'react-spy';

broadcast(['custom', 'event', 'chain'], {value: 'Wow'});
// or just
//   spy.send(['custom', 'event', 'chain'], {value: 'Wow'})

`broadcastError(detail: ErrorDetail)`

detail
- error: Error — JavaScript error
- chain string[] — spy id chain
- info: object — React error info (optional)

import {broadcastError} from 'react-spy';

broadcastError({
	chain: ['login', 'submit', 'failed'],
	error: new Error('Internal Error'),
});
// or just
//   spy.error('localStorage', new Error('Read'));
//   spy.error(thisReactCmp, 'localStorage', new Error('save'));