rudder-sdk-js 1.0.19 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -157
- package/index.d.ts +374 -24
- package/index.js +10287 -10187
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,23 +1,15 @@
|
|
|
1
|
-
#
|
|
1
|
+
# RudderStack JavaScript SDK
|
|
2
2
|
|
|
3
|
-
[RudderStack](https://rudderstack.com/)
|
|
3
|
+
The [**RudderStack**](https://rudderstack.com/) JavaScript SDK leverages the `rudder-analytics.js` library to track and send user events from your website to RudderStack. You can then further transform and route this event data to the destination platform of your choice.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> For detailed documentation on the RudderStack JavaScript SDK, click [**here**](https://docs.rudderstack.com/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk).
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
The RudderStack JavaScript SDK (released under [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)) allows you to utilize our npm module `rudder-sdk-js` or `rudder-analytics.js` library to start sending event data from your website to RudderStack.
|
|
10
|
-
|
|
11
|
-
After integrating this SDK, you will also be able to connect to multiple destinations such as Amplitude, Google Analytics, etc. to send your data.
|
|
12
|
-
|
|
13
|
-
# [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#how-to-use-the-rudderstack-javascript-sdk)How to Use the RudderStack JavaScript SDK?
|
|
14
|
-
|
|
15
|
-
This Quick Start Guide will help you get up and running with using the RudderStack JavaScript SDK in no time. You just need to follow the steps below:
|
|
7
|
+
| **IMPORTANT**: We have deprecated the Autotrack feature for the RudderStack JavaScript SDK. If you still wish to use it for your project, refer to [**this repository**](https://github.com/rudderlabs/rudder-sdk-js-autotrack#autotrack). |
|
|
8
|
+
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
16
9
|
|
|
17
|
-
##
|
|
10
|
+
## Installing the JavaScript SDK
|
|
18
11
|
|
|
19
|
-
To integrate the SDK
|
|
20
|
-
You can use this [NPM module](https://www.npmjs.com/package/rudder-js) to package Rudder directly into your project.
|
|
12
|
+
To integrate the JavaScript SDK with your website, you can use this [**NPM module**](https://www.npmjs.com/package/rudder-js) to package RudderStack directly into your project.
|
|
21
13
|
|
|
22
14
|
To install, run:
|
|
23
15
|
|
|
@@ -25,47 +17,90 @@ To install, run:
|
|
|
25
17
|
npm install rudder-sdk-js --save
|
|
26
18
|
```
|
|
27
19
|
|
|
28
|
-
|
|
20
|
+
**Note that this NPM module is only meant to be used for a browser installation**. If you want to integrate RudderStack with your Node.js application, refer to the [**RudderStack Node.js repository**](https://github.com/rudderlabs/rudder-sdk-node).
|
|
21
|
+
<br><br>
|
|
22
|
+
|
|
23
|
+
**IMPORTANT**: Since the module exports the [**related APIs**](#exported-apis) on an already-defined object combined with the Node.js module caching, you should run the following code snippet only once and use the exported object throughout your project:
|
|
29
24
|
|
|
30
|
-
```
|
|
31
|
-
import * as rudderanalytics from "rudder-sdk-js"
|
|
32
|
-
rudderanalytics.
|
|
33
|
-
|
|
34
|
-
|
|
25
|
+
```javascript
|
|
26
|
+
import * as rudderanalytics from "rudder-sdk-js";
|
|
27
|
+
rudderanalytics.ready(() => {
|
|
28
|
+
console.log("we are all set!!!");
|
|
29
|
+
});
|
|
30
|
+
rudderanalytics.load(<WRITE_KEY>, <DATA_PLANE_URL>);
|
|
31
|
+
export { rudderanalytics };
|
|
35
32
|
```
|
|
36
33
|
|
|
37
|
-
|
|
34
|
+
You can also do this with **ES5** using the `require` method, as shown:
|
|
38
35
|
|
|
39
|
-
```
|
|
40
|
-
var rudderanalytics = require("rudder-sdk-js")
|
|
41
|
-
rudderanalytics.load(<
|
|
42
|
-
exports.rudderanalytics = rudderanalytics
|
|
36
|
+
```javascript
|
|
37
|
+
var rudderanalytics = require("rudder-sdk-js");
|
|
38
|
+
rudderanalytics.load(<WRITE_KEY>, <DATA_PLANE_URL>);
|
|
39
|
+
exports.rudderanalytics = rudderanalytics;
|
|
43
40
|
```
|
|
44
41
|
|
|
45
|
-
For destinations where you don't want the SDK to load the third-party scripts separately, modify the load call:
|
|
42
|
+
For destinations where you don't want the SDK to load the third-party scripts separately, modify the `load` call as shown:
|
|
46
43
|
|
|
47
|
-
```
|
|
44
|
+
```javascript
|
|
48
45
|
rudderanalytics.load(<YOUR_WRITE_KEY>, <DATA_PLANE_URL>, {loadIntegration: false})
|
|
49
|
-
// the SDK expects that the destination global queue or function for pushing events is
|
|
50
|
-
// already present for the destinations.
|
|
51
|
-
// Currently, the loadIntegration flag is supported for Amplitude and
|
|
52
|
-
// Google Analytics destinations. The SDK expects window.amplitude and window.ga to be already
|
|
53
|
-
// defined by the user separately for sending events to these destinations.
|
|
54
46
|
```
|
|
55
47
|
|
|
56
|
-
|
|
48
|
+
> For more information on the `load()` method, refer to the detailed [**JavaScript SDK documentation**](https://docs.rudderstack.com/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk).
|
|
49
|
+
|
|
50
|
+
A few important things to note:
|
|
51
|
+
|
|
52
|
+
- The SDK expects the destination global queue or function for pushing the events is already present for the particular destination/s.
|
|
53
|
+
- Currently, `loadIntegration` is supported only for Amplitude and Google Analytics.
|
|
54
|
+
- The JavaScript SDK expects `window.amplitude` and `window.ga` to be already defined by the user separately for the sending the events to these destinations.
|
|
55
|
+
|
|
56
|
+
### Exported APIs
|
|
57
|
+
|
|
58
|
+
The APIs exported by the module are:
|
|
59
|
+
|
|
60
|
+
- `load`
|
|
61
|
+
- `ready`
|
|
62
|
+
- `identify`
|
|
63
|
+
- `alias`
|
|
64
|
+
- `page`
|
|
65
|
+
- `track`
|
|
66
|
+
- `group`
|
|
67
|
+
- `reset`
|
|
68
|
+
- `getAnonymousId`
|
|
69
|
+
- `setAnonymousId`
|
|
70
|
+
|
|
57
71
|
|
|
58
|
-
|
|
72
|
+
### Sample implementations
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Refer to the following projects for a detailed walk-through of the above steps:
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
- [**Sample Angular project**](https://github.com/rudderlabs/rudder-analytics-angular)
|
|
77
|
+
- [**Sample React project**](https://github.com/rudderlabs/rudder-analytics-react)
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
### Supported browser versions
|
|
80
|
+
|
|
81
|
+
| **Browser** | **Supported Versions** |
|
|
82
|
+
| :------------------ | :--------------------- |
|
|
83
|
+
| Safari | v7 or later |
|
|
84
|
+
| IE | v10 or later |
|
|
85
|
+
| Edge | v15 or later |
|
|
86
|
+
| Mozilla Firefox | v40 or later |
|
|
87
|
+
| Chrome | v37 or later |
|
|
88
|
+
| Opera | v23 or later |
|
|
89
|
+
| Yandex | v14.12 or later |
|
|
90
|
+
|
|
91
|
+
> If the SDK does not work on the browser versions that you are targeting, verify if adding the browser polyfills to your application solves the issue.
|
|
92
|
+
|
|
93
|
+
## Identifying users
|
|
94
|
+
|
|
95
|
+
The `identify` call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.
|
|
96
|
+
|
|
97
|
+
A sample `identify()` call is shown below:
|
|
98
|
+
|
|
99
|
+
```javascript
|
|
65
100
|
rudderanalytics.identify(
|
|
66
|
-
"12345",
|
|
67
|
-
|
|
68
|
-
{
|
|
101
|
+
"12345", {
|
|
102
|
+
email: "name@domain.com"
|
|
103
|
+
}, {
|
|
69
104
|
page: {
|
|
70
105
|
path: "",
|
|
71
106
|
referrer: "",
|
|
@@ -80,20 +115,22 @@ rudderanalytics.identify(
|
|
|
80
115
|
);
|
|
81
116
|
```
|
|
82
117
|
|
|
83
|
-
In the above example, information
|
|
118
|
+
In the above example, the user-related information like the `userId` and `email` along with the [**contextual information**](https://docs.rudderstack.com/rudderstack-api/api-specification/rudderstack-spec/common-fields#javascript-sdk) is captured.
|
|
119
|
+
|
|
84
120
|
|
|
85
121
|
> There is no need to call `identify()` for anonymous visitors to your website. Such visitors are automatically assigned an `anonymousId`.
|
|
86
122
|
|
|
87
|
-
|
|
123
|
+
For more information on how to use the `identify` call, refer to the [**JavaScript SDK documentation**](https://docs.rudderstack.com/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk).
|
|
124
|
+
|
|
125
|
+
## Tracking user actions
|
|
88
126
|
|
|
89
|
-
The `track
|
|
127
|
+
The `track` call lets you record the customer events, i.e. the actions that they perform, along with any associated properties.
|
|
90
128
|
|
|
91
|
-
A sample
|
|
129
|
+
A sample `track` call is shown below:
|
|
92
130
|
|
|
93
|
-
```
|
|
131
|
+
```javascript
|
|
94
132
|
rudderanalytics.track(
|
|
95
|
-
"test track event GA3",
|
|
96
|
-
{
|
|
133
|
+
"test track event GA3", {
|
|
97
134
|
revenue: 30,
|
|
98
135
|
currency: "USD",
|
|
99
136
|
user_actual_id: 12345,
|
|
@@ -104,133 +141,42 @@ rudderanalytics.track(
|
|
|
104
141
|
);
|
|
105
142
|
```
|
|
106
143
|
|
|
107
|
-
In the above example, the method tracks the event ‘**test track event GA3
|
|
144
|
+
In the above example, the `track` method tracks the user event ‘**test track event GA3**’ and information such as the `revenue`, `currency`, `anonymousId`.
|
|
108
145
|
|
|
109
|
-
You can use
|
|
146
|
+
> You can use the `track` method to track various success metrics for your website like user signups, item purchases, article bookmarks, and more.
|
|
110
147
|
|
|
111
|
-
|
|
148
|
+
## The `ready` API
|
|
112
149
|
|
|
113
|
-
|
|
114
|
-
rudderanalytics.track(
|
|
115
|
-
"test track event GA3",
|
|
116
|
-
{
|
|
117
|
-
revenue: 30,
|
|
118
|
-
currency: 'USD' ,
|
|
119
|
-
user_actual_id: 12345
|
|
120
|
-
},
|
|
121
|
-
{
|
|
122
|
-
page: {
|
|
123
|
-
path: "",
|
|
124
|
-
referrer: "",
|
|
125
|
-
search: "",
|
|
126
|
-
title: "",
|
|
127
|
-
url: ""
|
|
128
|
-
},
|
|
129
|
-
context: {
|
|
130
|
-
ip: "0.0.0.0"
|
|
131
|
-
},
|
|
132
|
-
anonymousId: "00000000000000000000000000"
|
|
133
|
-
},
|
|
134
|
-
() => {console.log("in track call");}
|
|
135
|
-
);
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
You’ve now successfully installed RudderStack's JavaScript SDK tracking. You can enable and use any event destination to send your event data via RudderStack, in no time at all.
|
|
139
|
-
|
|
140
|
-
## [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#step-4-check-ready-state)Step 4: Check Ready State
|
|
150
|
+
There are cases when you may want to tap into the features provided by the end-destination SDKs to enhance tracking and other functionalities. The JavaScript SDK exposes a `ready` API with a `callback` parameter that fires when the SDK is done initializing itself and the other third-party native SDK destinations.
|
|
141
151
|
|
|
142
|
-
|
|
152
|
+
An example is shown in the following snippet:
|
|
143
153
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
```jsx
|
|
154
|
+
```javascript
|
|
147
155
|
rudderanalytics.ready(() => {
|
|
148
156
|
console.log("we are all set!!!");
|
|
149
157
|
});
|
|
150
158
|
```
|
|
151
159
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
You can also define callbacks to the common methods of the `rudderanalytics` object.
|
|
160
|
+
> For more information on the other supported methods, refer to the [**JavaScript SDK APIs**](https://docs.rudderstack.com/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk#supported-apis).
|
|
155
161
|
|
|
156
|
-
> For now, the functionality is supported for `syncPixel` method which is called in the SDK when making sync calls in integrations for relevant destinations.
|
|
157
162
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
```jsx
|
|
161
|
-
rudderanalytics.syncPixelCallback = (obj) => {
|
|
162
|
-
rudderanalytics.track(
|
|
163
|
-
"sync lotame",
|
|
164
|
-
{ destination: obj.destination },
|
|
165
|
-
{ integrations: { All: false, S3: true } }
|
|
166
|
-
);
|
|
167
|
-
};
|
|
168
|
-
```
|
|
163
|
+
## Self-Hosted control plane
|
|
169
164
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
The callback can be supplied in options parameter like below as well:
|
|
173
|
-
|
|
174
|
-
```jsx
|
|
175
|
-
// define the callbacks directly on the load method like:
|
|
176
|
-
rudderanalytics.load(<YOUR_WRITE_KEY>, <DATA_PLANE_URL>,
|
|
177
|
-
{ clientSuppliedCallbacks: {
|
|
178
|
-
"syncPixelCallback": () => {console.log('sync done!')}
|
|
179
|
-
}
|
|
180
|
-
}
|
|
181
|
-
)
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
We will be adding similar callbacks for APIs such as `track`, `page`, `identify`, etc.
|
|
185
|
-
|
|
186
|
-
# [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#autotrack)Autotrack
|
|
187
|
-
|
|
188
|
-
| **IMPORTANT**: We have deprecated the Autotrack feature for the RudderStack JavaScript SDK. If you still wish to use it for your project, refer to [this repository](https://github.com/rudderlabs/rudder-sdk-js-autotrack#autotrack). |
|
|
189
|
-
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
165
|
+
If you are using a device mode destination like Heap, FullStory, etc., the JavaScript SDK needs to fetch the required configuration from the [**control plane**](https://docs.rudderstack.com/get-started/rudderstack-architecture#control-plane).
|
|
190
166
|
|
|
191
|
-
|
|
167
|
+
If you are self-hosting the control plane using the [**RudderStack Control Plane Lite**](https://docs.rudderstack.com/get-started/control-plane-lite#what-is-the-control-plane-url) utility, your `load` call will look like the following:
|
|
192
168
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
rudderanalytics.load(<YOUR_WRITE_KEY>, <DATA_PLANE_URL>, {
|
|
197
|
-
useAutoTracking: true,
|
|
169
|
+
```javascript
|
|
170
|
+
rudderanalytics.load(<WRITE_KEY>, <DATA_PLANE_URL>, {
|
|
171
|
+
configUrl: <CONTROL_PLANE_URL>,
|
|
198
172
|
});
|
|
199
173
|
```
|
|
200
174
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
```jsx
|
|
204
|
-
rudderanalytics.load(<YOUR_WRITE_KEY>, <DATA_PLANE_URL>, {
|
|
205
|
-
useAutoTracking: true,
|
|
206
|
-
valTrackingList: ["CLASS_ATTR_NAME"],
|
|
207
|
-
});
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
# [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#self-hosted-config-plane)Self-hosted Config Plane
|
|
211
|
-
|
|
212
|
-
If you are using a device mode destination like Heap, FullStory, etc., the JavaScript SDK needs to fetch the required configuration from the Control Plane. If you are using the RudderStack Config Generator to host your own Control Plane, then follow [this guide](https://docs.rudderstack.com/how-to-guides/rudderstack-config-generator) and make a `load` call as shown:
|
|
213
|
-
|
|
214
|
-
```jsx
|
|
215
|
-
rudderanalytics.load(<YOUR_WRITE_KEY>, <DATA_PLANE_URL>, {configUrl: CONTROL_PLANE_URL});
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
# [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#contribute)Contribute
|
|
219
|
-
|
|
220
|
-
You can start adding integrations of your choice for sending data through their JavaScript SDKs.
|
|
221
|
-
|
|
222
|
-
## [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#how-to-build-the-sdk)How To Build the SDK
|
|
223
|
-
|
|
224
|
-
- Look for run scripts in the `package.json` file for getting browser minified and non-minified builds. The builds are updated in the `dist` folder of the directory. Among the others, the important ones are:
|
|
225
|
-
|
|
226
|
-
- `npm run buildProdBrowser`: This outputs **rudder-analytics.min.js**.
|
|
227
|
-
- `npm run buildProdBrowserBrotli`: This outputs two files, **rudder-analytics.min.br.js** (the original minified file, same as above) and **rudder-analytics.min.br.js.br** (the brotli compressed file).
|
|
228
|
-
- `npm run buildProdBrowserGzip`: This outputs two files, **rudder-analytics.min.gzip.js** (the original minified file, same as above) and **rudder-analytics.min.gzip.js.gz** (the gzipped compressed file).
|
|
229
|
-
|
|
230
|
-
We are using **rollup** to build our SDKs, configuration for it is present in `rollup.config.js` in the repo directory.
|
|
175
|
+
> More information on how to get the `CONTROL_PLANE_URL` can be found [**here**](https://docs.rudderstack.com/get-started/control-plane-lite#what-is-the-control-plane-url).
|
|
231
176
|
|
|
232
|
-
|
|
177
|
+
| **For detailed technical documentation and troubleshooting guide on the RudderStack’s JavaScript SDK, check out our [docs](https://docs.rudderstack.com/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk).** |
|
|
178
|
+
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
233
179
|
|
|
234
|
-
|
|
180
|
+
## Contact us
|
|
235
181
|
|
|
236
|
-
For more
|
|
182
|
+
For more information on any of the sections covered in this readme, you can [**contact us**](mailto:%20docs@rudderstack.com) or start a conversation on our [**Slack**](https://resources.rudderstack.com/join-rudderstack-slack) channel.
|