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
This package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from your JavaScript code.
3
+
This package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from JavaScript code.
4
4
5
-
It has no dependencies and supports **modern evergreen browsers**and modern versions of Node.js with support for [cryptography](https://caniuse.com/cryptography).
5
+
TelemetryDeck allows you to capture and analyize users moving through your app and get help deciding how to grow, all without compromising privacy!
6
6
7
-
Signals sent with this SDK do not send any default values, besides signal `type`, `appID`, `user` and `sessionID`.
7
+
> [!NOTE]
8
+
> If you want to use TelemetryDeck for your blog or static website, we recommend the [TelemetryDeck Web SDK](https://github.com/TelemetryDeck/WebSDK) instead of this JavaScript SDK.
8
9
9
-
If you want to use this package in your web application, see recommended parameters below.
10
+
# Set Up
10
11
11
-
## Usage
12
+
The TelemetryDeck SDK has no dependencies and supports **modern evergreen browsers** and **modern versions of Node.js** with support for [cryptography](https://caniuse.com/cryptography).
12
13
13
-
### 📦 Advanced usage for applications that use a bundler (like Webpack, Rollup, …)
14
+
##Set up in Browser Based Applications that use a bundler (React, Vue, Angular, Svelte, Ember, …)
14
15
15
-
After installing the package via NPM, use it like this:
16
+
### 1. Installing the package
17
+
18
+
Please install the package using npm or the package manager of your choice
19
+
20
+
### 2. Initializing TelemetryDeck
21
+
22
+
Initialize the TelemetryDeck SDK with your app ID and your user's user identifer.
16
23
17
24
```javascript
18
25
importTelemetryDeckfrom'@telemetrydeck/sdk';
@@ -21,88 +28,89 @@ const td = new TelemetryDeck({
21
28
appID:'<YOUR_APP_ID>'
22
29
user:'<YOUR_USER_IDENTIFIER>',
23
30
});
31
+
```
24
32
25
-
// Basic signal
26
-
td.signal('<SIGNAL_TYPE>');
33
+
Please replace `<YOUR_APP_ID>` with the app ID in TelemetryDeck ([Dashboard](https://dashboard.telemetrydeck.com) -> App -> Set Up App).
27
34
28
-
// Adanced: Signal with custom payload
29
-
td.signal('<SIGNAL_TYPE>', {
30
-
volume:'11',
31
-
});
32
-
```
35
+
You also need to identify your logged in user. Instead of `<YOUR_USER_IDENTIFIER>`, pass in any string that uniquely identifies your user, such as an email address. It will be cryptographically anonymized with a hash function.
33
36
34
-
Please replace `YOUR_APP_ID` with the app ID you received from TelemetryDeck. If you have any string that identifies your user, such as an email address, use it as `YOUR_USER_IDENTIFIER` – it will be cryptographically anonymized with a hash function.
37
+
If can't specify a user identifer at initialization, you can set it later by setting `td.clientUser`.
35
38
36
-
If you want to pass optional parameters to the signal being sent, add them to the optional payload object.
37
39
38
-
## Usage with React Native
39
40
40
-
React Native does not support the `crypto` module, which is required for the SDK to work. We found [react-native-quick-crypto](https://github.com/margelo/react-native-quick-crypto) to be a suitable polyfill. Please note that this is not an officially supported solution.
41
+
Please note that `td.signal`is an async function that returns a promise.
41
42
42
-
## Queueing Signals
43
+
## Set up in Node.js Applications
43
44
44
-
The `TelemetryDeck` class comes with a built-in queuing mechanism for storing signals until they are flushed in a single request. Queued signals are sent with `receivedAt` prefilled with the time they were queued.
45
+
### 1. Installing the package
45
46
46
-
This uses an in-memory store by default. The store is not persisted between page reloads or app restarts. If you want to persist the store, you can pass a `store` object to the `TelemetryDeck` constructor. The store must implement the following interface:
47
+
Please install the package using npm or the package manager of your choice
48
+
49
+
### 2. Initializing TelemetryDeck
50
+
51
+
Initialize the TelemetryDeck SDK with your app ID and your user's user identifer. Since `globalThis.crypto.subtle.digest` does not exist in Node.js, you need to pass in an alternative implementation provided by Node.js.
47
52
48
53
```javascript
49
-
exportclassStore {
50
-
asyncpush() // signal bodys are async and need to be awaited before stored
51
-
clear() // called after flush
52
-
values() // returns an array of resolved signal bodys in the order they were pushed
53
-
}
54
+
importTelemetryDeckfrom'@telemetrydeck/sdk';
55
+
importcryptofrom'crypto';
56
+
57
+
consttd=newTelemetryDeck({
58
+
appID:'<YOUR_APP_ID>'
59
+
user:'<YOUR_USER_IDENTIFIER>',
60
+
cryptoDigest:crypto.webcrypto.subtle.digest,
61
+
});
54
62
```
55
63
56
-
The default implementation can be found in `src/utils/store.js` and uses a monotone counter to keep track of the order of signals.
64
+
Please replace `<YOUR_APP_ID>` with the app ID in TelemetryDeck ([Dashboard](https://dashboard.telemetrydeck.com) -> App -> Set Up App).
57
65
58
-
### 📱 You need an App ID
66
+
You also need to identify your logged in user. Instead of `<YOUR_USER_IDENTIFIER>`, pass in any string that uniquely identifies your user, such as an email address. It will be cryptographically anonymized with a hash function.
59
67
60
-
Every application and website registered to TelemetryDeck has a unique ID that we use to assign incoming signals to the correct app. To get started, create a new app in the TelemetryDeck UI and copy the ID from there.
68
+
If can't specify a user identifer at initialization, you can set it later by setting `td.clientUser`.
61
69
62
-
### 👤 Optional: User Identifiers
70
+
Please note that `td.signal` is an async function that returns a promise.
63
71
64
-
TelemetryDeck can count users if you assign it a unique identifier for each user that doesn't change. This identifier can be any string that is unique to the user, such as their email address, or a randomly generated UUID.
72
+
> [!NOTE]
73
+
> If you are using React Native, React Native does not support the `crypto` module, which is required for the SDK to work. We found [react-native-quick-crypto](https://github.com/margelo/react-native-quick-crypto) to be a suitable polyfill. Please note that this is not an officially supported solution.
65
74
66
-
Feel free to use personally identifiable information as the user identifier: We use a cryptographically secure double-hashing process on client and server to make sure the data that arrives at our servers is anonymized and can not be traced back to individual users via their identifiers. A user's identifier is hashed inside the library and then salted+hashed again on arrival at the server. This way the data is anonymized as defined by the GDPR and you don't have to ask for user consent for processing or storing this data.
67
75
68
-
### 🚛 Optional: Payload
76
+
##Advanced Initalization Options
69
77
70
-
You can optionally attach an object with values to the signal. This will allow you to filter and aggregate signals by these values in the dashboard.
78
+
See the [source code](./src/telemetrydeck.js#L6-L17) for a full list of availble options acepted by the `TelemetryDeck` constructor.
71
79
72
-
Values will be stringified through `JSON.stringify()`, with few exceptions:
73
80
74
-
- Dates will be converted to ISO strings using `.toISOString()`
75
-
- Strings are passed as is (this prevents the JSON stringification of strings, which would add quotes around the string)
76
-
-`floatValue` is the only key in the payload that may hold a float value. Any value passed to this will be converted to a float using `Number.parseFloat()`.
81
+
# Sending Signals
77
82
78
-
#### Payload Recommendations for Web Apps
83
+
Send a basic signal by calling `td.signal()` with a signal type:
79
84
80
-
In most web apps you probably want to see a few default values which you can read from the browser. We recommend sending the following values in your custom payload:
85
+
```javascript
86
+
td.signal('<SIGNAL_TYPE>');
87
+
```
88
+
89
+
Send a signal with a custom payload by passing an object as the second argument. The payload's values will be [converted to Strings](./src/tests/store.test.js.js#L278-L310), except for `floatValue`, which can be a Float.
81
90
82
91
```javascript
83
-
td.signal('navigation', {
84
-
referrer:globalThis.document?.referrer,
85
-
locale:globalThis.navigator?.language,
86
-
url:globalThis.location?.href,
87
-
// ...
92
+
td.signal('Volume.Set', {
93
+
band:'Spinal Tap',
94
+
floatValue:11.0,
88
95
});
89
96
```
90
97
91
-
#### Test Mode
98
+
#Advanced: Queueing Signals
92
99
93
-
You can enable test mode by setting `testMode` to `true` on your `TelemetryDeck` instance.
100
+
The `TelemetryDeck` class comes with a built-in queuing mechanism for storing signals until they are flushed in a single request. Queued signals are sent with `receivedAt` prefilled with the time they were queued.
101
+
102
+
This uses an in-memory store by default. The store is not persisted between page reloads or app restarts. If you want to persist the store, you can pass a `store` object to the `TelemetryDeck` constructor. The store must implement the following interface:
94
103
95
104
```javascript
96
-
td.testMode=true;
97
-
td.signal('navigation', {
98
-
/* ... */
99
-
}); // send with testMode enabled
100
-
td.testMode=false;
101
-
td.signal('navigation', {
102
-
/* ... */
103
-
}); // send with testMode disabled
105
+
exportclassStore {
106
+
asyncpush() // signal bodys are async and need to be awaited before stored
107
+
clear() // called after flush
108
+
values() // returns an array of resolved signal bodys in the order they were pushed
109
+
}
104
110
```
105
111
106
-
### 📚 Full Docs
112
+
The default implementation can be found in `src/utils/store.js`.
113
+
114
+
---
107
115
108
-
Go to [telemetrydeck.com/docs](https://telemetrydeck.com/docs) to see all documentation articles
116
+
[TelemetryDeck](https://telemetrydeck.com?source=github) helps you build better products with live usage data. Try it out for free.
Copy file name to clipboardExpand all lines: src/telemetrydeck.js
+28-7Lines changed: 28 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -9,10 +9,11 @@ import { version } from './utils/version.js';
9
9
* @property {string} appID the app ID to send telemetry data to
10
10
* @property {string} clientUser the clientUser ID to send telemetry data to
11
11
* @property {string} [target] the target URL to send telemetry data to
12
-
* @property {string} [sessionID]
13
-
* @property {string} [salt]
14
-
* @property {boolean} [testMode]
15
-
* @property {Store} [store]
12
+
* @property {string} [sessionID] An optional session ID to include in each signal
13
+
* @property {string} [salt] A salt to use when hashing the clientUser ID
14
+
* @property {boolean} [testMode] If "true", signals will be marked as test signals and only show up in Test Mode in the Dashbaord
15
+
* @property {Store} [store] A store to use for queueing signals
16
+
* @property {Function} [cryptoDigest] A function to use for calculating the SHA-256 hash of the clientUser ID. Null to use the browser's built-in crypto.subtle.digest function.
16
17
*/
17
18
18
19
exportdefaultclassTelemetryDeck{
@@ -27,7 +28,7 @@ export default class TelemetryDeck {
27
28
* @param {TelemetryDeckOptions} options
28
29
*/
29
30
constructor(options={}){
30
-
const{ target, appID, clientUser, sessionID, salt, testMode, store }=options;
0 commit comments