https://github.com/booleanhunter/reactjs-user-analytics
User Analytics
https://github.com/booleanhunter/reactjs-user-analytics
Last synced: 16 days ago
JSON representation
User Analytics
- Host: GitHub
- URL: https://github.com/booleanhunter/reactjs-user-analytics
- Owner: booleanhunter
- Created: 2021-02-22T06:38:20.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-07T04:37:31.000Z (over 1 year ago)
- Last Synced: 2024-12-30T07:42:54.194Z (about 1 year ago)
- Language: HTML
- Homepage: https://booleanhunter.github.io/reactjs-user-analytics/
- Size: 1.62 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# User Analytics
This library enables tracking of UI events when a user interacts with a React or React Native application.
## Features
- **Progressive** - Uses latest JavaScript features and design patterns for a React codebase.
- **Extensible** - A modular architecture and usage of Dependency.Inversion patterns gives you flexibility and allows you to easily extend features.
- **TypeScript support**.
## Supported events
- Form Events
- `onChange`
- Mouse Events
- `onClick`
- `onHover`
## Work in Progress
- Eventually, the library will have exhaustive coverage and support for many more events, such as:
- Wheel Events
- Touch Events
- Keyboard Events
- Mouse Events
- and more.
- User Interaction journey mapping
- Session Recording
## Instructions of Usage
1. First, import the library in your project.
2. In-order to add user-tracking ability to your component or element, import the `withTracking` function (Higher-order component) and wrap the component. Here's an example using a simple `Button` component:
`export const ButtonWithTracking = withTracking(Button)`
`ButtonWithTracking` will have all the features and properties of the `Button` component, but with interaction-tracking superpowers!
3. Finally, use `ButtonWithTracking` inside your app anywhere where you'd like to track user-events occurring on this component, such as `onClick` or `onHover`.
```
import Button, { ButtonWithTracking } from '../../elements/Button';
function Home() {
function handleClick(e: React.MouseEvent) {
// app logic goes here
}
function logEvent(
event: React.MouseEvent,
interactionResource: UserInteractionResource
) {
/*
do whatever you want with the resource,
like save it to IndexedDB, compress it, save it via API, etc
*/
console.log(interactionResource);
}
return (
)
}
export default Home;
```
You can add multiple tracker objects within the `trackers` array if you need to track more than one event occurring within the component.
## Advanced Usage
### Mapping a user's journey
**Use-case**:
Say you have 2 react components - a `ButtonWithTracking` configured to track `onClick` events, and a `InputWithTracking` component configured to capture `onChange` events. These components are being used in 2 different pages or templates in your application - a login form, and a newsletter subscription form.
In this scenario, it is useful to capture a global 'context' within which the events occur - such as the page or the container component details, and the app version. This information is useful to plot out the user's journey, which will give you a more contextual understanding of how the user navigates through your app.
- #### Provide and capture contextual data using React Context Provider ``
Using the ``, you can provide the global 'context' to your tracking components without having to pass them explicitly via props. Here's how:
- Create a `DataContext` object.
```
const dataContext = {
context: "Login Form",
app: {
version: "1",
},
} as UserInteraction.DataContext;
```
- Next, wrap your template or container component within `DataContext.Provider` and provide it the `dataContext` value:
```
import { DataContext } from '../../../library/user-analytics/react/contexts/dataContext';
import Button, { ButtonWithTracking } from '../../elements/Button';
function LoginForm() {
function logEvent(
event: React.MouseEvent,
interactionResource: UserInteractionResource
) {
console.log(interactionResource.app.version) // Will print "1"
console.log(interactionResource.source.context); // Will print "Login Form"
}
return (
// Pass the dataContext value
)
}
export default LoginForm;
```
This way, your tracking components nested anywhere within the provider will receive the `dataContext` object and will return it as part of the `UserInteractionResource` object.
- #### Providing Data Context as regular props
If you don't want to provide data using `DataContext.Provider` or want to override it with a different value, you can pass them explicitly via props:
```
function LoginForm() {
function logEvent(
event: React.MouseEvent,
interactionResource: UserInteractionResource
) {
console.log(interactionResource.app.version) // Will print "0"
console.log(interactionResource.source.context); // Will print "Login Form"
}
return (
)
}
export default LoginForm;
```
In-case you have both in your application, the data context passed via props will override the values from ` `
## API
### React
- #### Tracking Component Props
The tracking-enabled component will accept all props required for the original component, along with the following:
| Props | Required | Description | Type |
| :--- | :----: | :----: | ---: |
| `trackers` |Yes |Each tracker object expects an `action` and `track` properties. Check the section below for the complete list of properties | `UserInteraction.Tracker[]` |
| `origin` |Optional | To provide some contextual information for the event origin | `string` |
| `dataContext` |Optional |an object property to provide context of the taken event | `UserInteraction.DataContext`|
- #### `UserInteraction.Tracker` object properties
| Property | Required | Description | Type |
| :--- | :----: | :----: | ---: |
| `action` | Yes | Type of event that needs to be tracked (React Synthetic events). Can take values such as `onClick`, `onChange` | `string` |
| `track` | Yes| Callback that runs when above event occurs | `(e, interactionResource: UserInteractionResource) => void` |
| `data` | Optional | Can be used to provide some custom data. Accessible within `UserInteractionResource.data` | `Object` |
### Interfaces
- #### `UserInteractionResource`
The `UserInteractionResource` object contains all properties from `BaseResource`, along with the following:
```
type: typeof UserInteraction.TYPE; // "UserInteraction"
action: UserInteraction.Action; // Type of the event, such as "onClick", "onChange"
source: {
context: string; // To capture a "global" context of the event, such as "Landing page" or "Login form"
origin?: string;
component: string; // Name of the React component
element: {
currentTarget: string;
target: string;
innerHTML?: string;
innerText?: string;
value?: string;
};
};
data?: Object; // Additional custom data that needs to be captured
```
- #### `BaseResource`
```
app: {
version: string,
};
date: Date;
browser: {
name: string,
version: string,
userAgent: string,
platform: string,
window: {
width: number,
height: number,
}
};
os: {
name: string,
version: string,
};
```
## Check out the [docs](./docs) folder for a complete list of API reference.
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).