You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor(major): Upgrade to Vite, add demo, remove optional libs
- Migrate from Create-React-App to Vite
- Add demo playground with examples
- Add prettier for code formatting
- Remove dev-dependencies: styled-components and AntD
Copy file name to clipboardExpand all lines: README.md
+42-44
Original file line number
Diff line number
Diff line change
@@ -1,33 +1,36 @@
1
-
# User Analytics
1
+
# React User Analytics
2
2
3
3
This library enables tracking of UI events when a user interacts with a React or React Native application.
4
4
5
5
## Features
6
+
6
7
-**Progressive** - Uses latest JavaScript features and design patterns for a React codebase.
7
8
-**Extensible** - A modular architecture and usage of Dependency.Inversion patterns gives you flexibility and allows you to easily extend features.
8
9
-**TypeScript support**.
9
10
10
11
## Supported events
12
+
11
13
- Form Events
12
-
-`onChange`
14
+
-`onChange`
13
15
- Mouse Events
14
-
-`onClick`
15
-
-`onHover`
16
-
16
+
-`onClick`
17
+
-`onHover`
17
18
18
19
## Work in Progress
20
+
19
21
- Eventually, the library will have exhaustive coverage and support for many more events, such as:
20
-
- Wheel Events
21
-
- Touch Events
22
-
- Keyboard Events
23
-
- Mouse Events
24
-
- and more.
22
+
23
+
- Wheel Events
24
+
- Touch Events
25
+
- Keyboard Events
26
+
- Mouse Events
27
+
- and more.
25
28
26
29
- User Interaction journey mapping
27
30
- Session Recording
28
31
29
-
30
32
## Instructions of Usage
33
+
31
34
1. First, import the library in your project.
32
35
33
36
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:
@@ -38,7 +41,7 @@ This library enables tracking of UI events when a user interacts with a React or
38
41
39
42
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`.
40
43
41
-
```
44
+
```react
42
45
import Button, { ButtonWithTracking } from '../../elements/Button';
43
46
44
47
function Home() {
@@ -70,7 +73,7 @@ function Home() {
70
73
track: logEvent, // callback function that runs whenever the event occurs
71
74
}
72
75
]}
73
-
>
76
+
>
74
77
)
75
78
}
76
79
@@ -79,7 +82,6 @@ export default Home;
79
82
80
83
You can add multiple tracker objects within the `trackers` array if you need to track more than one event occurring within the component.
81
84
82
-
83
85
## Advanced Usage
84
86
85
87
### Mapping a user's journey
@@ -90,9 +92,11 @@ Say you have 2 react components - a `ButtonWithTracking` configured to track `on
90
92
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.
91
93
92
94
-#### Provide and capture contextual data using React Context Provider `<DataContext.Provider>`
93
-
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:
94
95
95
-
- Create a `DataContext` object.
96
+
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:
97
+
98
+
- Create a `DataContext` object.
99
+
96
100
```
97
101
const dataContext = {
98
102
context: "Login Form",
@@ -102,9 +106,9 @@ const dataContext = {
102
106
} as UserInteraction.DataContext;
103
107
```
104
108
105
-
- Next, wrap your template or container component within `DataContext.Provider` and provide it the `dataContext` value:
109
+
- Next, wrap your template or container component within `DataContext.Provider` and provide it the `dataContext` value:
106
110
107
-
```
111
+
```react
108
112
import { DataContext } from '../../../library/user-analytics/react/contexts/dataContext';
109
113
import Button, { ButtonWithTracking } from '../../elements/Button';
110
114
@@ -130,14 +134,14 @@ function LoginForm() {
130
134
{
131
135
action: "onClick",
132
136
track: logEvent,
133
-
137
+
134
138
data: { // pass optional custom data
135
139
color: "blue",
136
140
}
137
141
}
138
142
]}
139
-
>
140
-
</DataContext.Provider>
143
+
>
144
+
</DataContext.Provider>
141
145
)
142
146
}
143
147
@@ -147,12 +151,11 @@ export default LoginForm;
147
151
148
152
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.
149
153
150
-
151
154
-#### Providing Data Context as regular props
152
155
153
156
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:
154
157
155
-
```
158
+
```react
156
159
function LoginForm() {
157
160
158
161
function logEvent(
@@ -174,20 +177,20 @@ function LoginForm() {
174
177
{
175
178
action: "onClick",
176
179
track: logEvent,
177
-
180
+
178
181
data: { // pass optional custom data
179
182
color: "blue",
180
183
}
181
184
}
182
185
]}
183
-
186
+
184
187
dataContext={{ // Pass dataContext explicitly
185
188
app: {
186
189
version: "0",
187
190
},
188
191
context: "Login Form"
189
192
}}
190
-
>
193
+
>
191
194
)
192
195
}
193
196
@@ -197,7 +200,6 @@ export default LoginForm;
197
200
198
201
In-case you have both in your application, the data context passed via props will override the values from ` <DataContext.Provider>`
199
202
200
-
201
203
## API
202
204
203
205
### React
@@ -206,29 +208,26 @@ In-case you have both in your application, the data context passed via props wil
206
208
207
209
The tracking-enabled component will accept all props required for the original component, along with the following:
208
210
209
-
| Props | Required | Description | Type |
210
-
| :--- | :----: | :----: | ---: |
211
-
|`trackers`|Yes |Each tracker object expects an `action` and `track` properties. Check the section below for the complete list of properties |`UserInteraction.Tracker[]`|
212
-
|`origin`|Optional | To provide some contextual information for the event origin |`string`|
213
-
|`dataContext`|Optional |an object property to provide context of the taken event |`UserInteraction.DataContext`|
|`trackers`| Yes | Each tracker object expects an `action` and `track` properties. Check the section below for the complete list of properties |`UserInteraction.Tracker[]`|
214
+
|`origin`| Optional | To provide some contextual information for the event origin |`string`|
215
+
|`dataContext`| Optional | an object property to provide context of the taken event |`UserInteraction.DataContext`|
215
216
216
217
-#### `UserInteraction.Tracker` object properties
217
218
218
-
| Property | Required | Description | Type |
219
-
| :--- | :----: | :----: | ---: |
220
-
|`action`| Yes | Type of event that needs to be tracked (React Synthetic events). Can take values such as `onClick`, `onChange`|`string`|
221
-
|`track`| Yes| Callback that runs when above event occurs |`(e, interactionResource: UserInteractionResource) => void`|
222
-
|`data`| Optional | Can be used to provide some custom data. Accessible within `UserInteractionResource.data`|`Object<any>`|
0 commit comments