Skip to content

Commit 1d30fe8

Browse files
purnimaguptabooleanhunter
purnimagupta
authored and
booleanhunter
committed
docs(Instructions of usage): Add documentation
- Add tsdoc comments - USe Typedoc to generate API documentation
1 parent 4aed139 commit 1d30fe8

29 files changed

+6592
-39
lines changed

‎README.md

Lines changed: 250 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,270 @@
1-
# Getting Started with Create React App
1+
# User Analytics
22

3-
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
3+
This library enables tracking of UI events when a user interacts with a React or React Native application.
4+
5+
## Supported events
6+
- Form Events
7+
- `onChange`
8+
- Mouse Events
9+
- `onClick`
10+
- `onHover`
11+
12+
13+
## Work in Progress
14+
- Eventually, the library will have exhaustive coverage and support for many more events, such as:
15+
- Wheel Events
16+
- Touch Events
17+
- Keyboard Events
18+
- Mouse Events
19+
- and more.
20+
21+
- User Interaction journey mapping
22+
- Session Recording
23+
24+
25+
## Instructions of Usage
26+
1. First, import the library in your project.
27+
28+
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:
29+
30+
`export const ButtonWithTracking = withTracking(Button)`
31+
32+
`ButtonWithTracking` will have all the features and properties of the `Button` component, but with interaction-tracking superpowers!
33+
34+
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`.
35+
36+
```
37+
import Button, { ButtonWithTracking } from '../../elements/Button';
38+
39+
function Home() {
40+
41+
function handleClick(e: React.MouseEvent<HTMLElement, MouseEvent>) {
42+
// app logic goes here
43+
}
44+
45+
function logEvent(
46+
event: React.MouseEvent<HTMLElement, MouseEvent>,
47+
interactionResource: UserInteractionResource
48+
) {
49+
/*
50+
do whatever you want with the resource,
51+
like save it to IndexedDB, compress it, save it via API, etc
52+
*/
53+
console.log(interactionResource);
54+
}
55+
56+
return (
57+
<ButtonWithTracking
58+
type="text"
59+
onClick={handleClick}
60+
61+
trackers={[
62+
// track onClick event
63+
{
64+
action: "onClick", // event to track
65+
track: logEvent, // callback function that runs whenever the event occurs
66+
}
67+
]}
68+
>
69+
)
70+
}
71+
72+
export default Home;
73+
```
74+
75+
You can add multiple tracker objects within the `trackers` array if you need to track more than one event occurring within the component.
76+
77+
78+
## Advanced Usage
79+
80+
### Mapping a user's journey
81+
82+
**Use-case**:
83+
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.
84+
85+
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.
486

5-
## Available Scripts
87+
- #### Provide and capture contextual data using React Context Provider `<DataContext.Provider>`
88+
Using the `<DataContext.Provider>`, you can provide the global 'context' to your tracking components without having to pass them explicitly via props. Here's how:
689

7-
In the project directory, you can run:
90+
- Create a `DataContext` object.
91+
```
92+
const dataContext = {
93+
context: "Login Form",
94+
app: {
95+
version: "1",
96+
},
97+
} as UserInteraction.DataContext;
98+
```
899

9-
### `yarn start`
100+
- Next, wrap your template or container component within `DataContext.Provider` and provide it the `dataContext` value:
10101

11-
Runs the app in the development mode.\
12-
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
102+
```
103+
import { DataContext } from '../../../library/user-analytics/react/contexts/dataContext';
104+
import Button, { ButtonWithTracking } from '../../elements/Button';
13105
14-
The page will reload if you make edits.\
15-
You will also see any lint errors in the console.
106+
function LoginForm() {
16107
17-
### `yarn test`
108+
function logEvent(
109+
event: React.MouseEvent<HTMLElement, MouseEvent>,
110+
interactionResource: UserInteractionResource
111+
) {
112+
console.log(interactionResource.app.version) // Will print "1"
113+
console.log(interactionResource.source.context); // Will print "Login Form"
18114
19-
Launches the test runner in the interactive watch mode.\
20-
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
115+
}
21116
22-
### `yarn build`
117+
return (
118+
<DataContext.Provider value={dataContext}> // Pass the dataContext value
119+
<ButtonWithTracking
120+
type="text"
121+
onClick={handleClick}
23122
24-
Builds the app for production to the `build` folder.\
25-
It correctly bundles React in production mode and optimizes the build for the best performance.
123+
trackers={[
124+
// track onClick event
125+
{
126+
action: "onClick",
127+
track: logEvent,
128+
129+
data: { // pass optional custom data
130+
color: "blue",
131+
}
132+
}
133+
]}
134+
>
135+
</DataContext.Provider>
136+
)
137+
}
26138
27-
The build is minified and the filenames include the hashes.\
28-
Your app is ready to be deployed!
139+
export default LoginForm;
29140
30-
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
141+
```
31142

32-
### `yarn eject`
143+
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.
33144

34-
**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
35145

36-
If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
146+
- #### Providing Data Context as regular props
37147

38-
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
148+
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:
39149

40-
You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
150+
```
151+
function LoginForm() {
41152
42-
## Learn More
153+
function logEvent(
154+
event: React.MouseEvent<HTMLElement, MouseEvent>,
155+
interactionResource: UserInteractionResource
156+
) {
157+
console.log(interactionResource.app.version) // Will print "0"
158+
console.log(interactionResource.source.context); // Will print "Login Form"
43159
44-
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
160+
}
45161
46-
To learn React, check out the [React documentation](https://reactjs.org/).
162+
return (
163+
<ButtonWithTracking
164+
type="text"
165+
onClick={handleClick}
166+
167+
trackers={[
168+
// track onClick event
169+
{
170+
action: "onClick",
171+
track: logEvent,
172+
173+
data: { // pass optional custom data
174+
color: "blue",
175+
}
176+
}
177+
]}
178+
179+
dataContext={{ // Pass dataContext explicitly
180+
app: {
181+
version: "0",
182+
},
183+
context: "Login Form"
184+
}}
185+
>
186+
)
187+
}
188+
189+
export default LoginForm;
190+
191+
```
192+
193+
In-case you have both in your application, the data context passed via props will override the values from ` <DataContext.Provider>`
194+
195+
196+
## API
197+
198+
### React
199+
200+
- #### Tracking Component Props
201+
202+
The tracking-enabled component will accept all props required for the original component, along with the following:
203+
204+
| Props | Required | Description | Type |
205+
| :--- | :----: | :----: | ---: |
206+
| `trackers` |Yes |Each tracker object expects an `action` and `track` properties. Check the section below for the complete list of properties | `UserInteraction.Tracker[]` |
207+
| `origin` |Optional | To provide some contextual information for the event origin | `string` |
208+
| `dataContext` |Optional |an object property to provide context of the taken event | `UserInteraction.DataContext`|
209+
210+
211+
- #### `UserInteraction.Tracker` object properties
212+
213+
| Property | Required | Description | Type |
214+
| :--- | :----: | :----: | ---: |
215+
| `action` | Yes | Type of event that needs to be tracked (React Synthetic events). Can take values such as `onClick`, `onChange` | `string` |
216+
| `track` | Yes| Callback that runs when above event occurs | `(e, interactionResource: UserInteractionResource) => void` |
217+
| `data` | Optional | Can be used to provide some custom data. Accessible within `UserInteractionResource.data` | `Object<any>` |
218+
219+
220+
221+
### Interfaces
222+
223+
- #### `UserInteractionResource`
224+
The `UserInteractionResource` object contains all properties from `BaseResource`, along with the following:
225+
226+
```
227+
type: typeof UserInteraction.TYPE; // "UserInteraction"
228+
action: UserInteraction.Action; // Type of the event, such as "onClick", "onChange"
229+
source: {
230+
context: string; // To capture a "global" context of the event, such as "Landing page" or "Login form"
231+
origin?: string;
232+
component: string; // Name of the React component
233+
element: {
234+
currentTarget: string;
235+
target: string;
236+
innerHTML?: string;
237+
innerText?: string;
238+
value?: string;
239+
};
240+
};
241+
data?: Object<any>; // Additional custom data that needs to be captured
242+
```
243+
244+
- #### `BaseResource`
245+
246+
```
247+
app: {
248+
version: string,
249+
};
250+
date: Date;
251+
browser: {
252+
name: string,
253+
version: string,
254+
userAgent: string,
255+
platform: string,
256+
window: {
257+
width: number,
258+
height: number,
259+
}
260+
};
261+
os: {
262+
name: string,
263+
version: string,
264+
};
265+
266+
```
267+
268+
## Check out the [docs](./docs) folder for a complete list of API reference.
269+
270+
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

0 commit comments

Comments
 (0)