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 your JavaScript code.
4
4
5
-
It has no package dependencies and supports modern evergreen browsers which support [cryptography](https://caniuse.com/cryptography).
5
+
It has no package dependencies and supports **modern evergreen browsers** which support [cryptography](https://caniuse.com/cryptography).
6
6
7
7
Signals sent with this version of the SDK automatically send the following payload items:
8
8
9
-
- url
10
-
- useragent
11
-
- locale
12
-
- platform
9
+
-`url`
10
+
-`useragent`
11
+
-`locale`
12
+
-`platform`
13
13
14
14
You can filter and show these values in the TelemetryDeck dashboard.
15
15
16
16
Test Mode is currently not supported.
17
17
18
18
## Usage
19
19
20
-
### 📄 Usage via Script Tag
20
+
### 📄 Usage via Script tag
21
21
22
-
For regular websites and to try out the code quickly, you can use [UNPKG](https://unpkg.com), a free CDN which allows you to load files from any npm package.
22
+
For websites and to try out the code quickly, you can use [UNPKG](https://unpkg.com), a free CDN which allows you to load files from any npm package.
23
23
24
-
Include the following snippet in your page header:
24
+
Include the following snippet inside the `<head>` of your HTML page:
Please replace `YOUR_APP_ID` with the app ID you received from TelemetryDeck, and set a user identifier if possible.
39
+
Please replace `YOUR_APP_ID` with the app ID you received from TelemetryDeck, and `USER_IDENTIFIER` with a user identifier. If you have none, consider `anonymous`.
49
40
50
-
### 📦 Usage for applications that use a bundler (like Webpack, Rollup, …)
41
+
You can add as many signals as you need to track different interactions with your page. Once the page and script are fully loaded, signals will be sent immediatlty.
42
+
43
+
```js
44
+
// basic signal
45
+
td.push('signal');
46
+
47
+
// with custom data
48
+
td.push('signal', { route:'/' });
49
+
```
50
+
51
+
#### Alternative usage for more complex tracking needs
52
+
53
+
```html
54
+
<script>
55
+
// Required: queue setup
56
+
td =window.td|| [];
57
+
// Required: Set your application id
58
+
td.push(['app', YOUR_APP_ID]);
59
+
// Required: Set a user idenfitier. `anonymous` is a recommended default
60
+
td.push(['user', USER_IDENTIFIER??'anonymous']);
61
+
62
+
// Custom payload sent with the signal
63
+
td.push(['signal']);
64
+
td.push([
65
+
'signal',
66
+
{
67
+
route:'some/page/path',
68
+
},
69
+
]);
70
+
</script>
71
+
```
72
+
73
+
### 📦 Advanced usage for applications that use a bundler (like Webpack, Rollup, …)
51
74
52
75
After installing the package via NPM, use it like this:
53
76
54
77
```js
55
-
import { signal } from'telemetry-deck';
56
-
57
-
//
58
-
signal(
59
-
// required options to identify your app and the user
// Queued signals do not contain a client side timestamp and will be timestamped
84
+
// on the server at the time of arrival. Consider adding a timestamp value to
85
+
// your payloads if you need to be able to correlate them.
86
+
constqueuedEvents= [
87
+
['app', YOUR_APP_ID],
88
+
['user', YOUR_USER_IDENTIFIER],
89
+
['signal'],
90
+
['signal', { route:'some/page/path' }],
91
+
];
92
+
td.ingest(qeuedEvents);
93
+
94
+
// Basic signal
95
+
td.signal();
96
+
97
+
// Update app or user identifier
98
+
td.app(YOUR_NEW_APP_ID);
99
+
td.user(YOUR_NEW_USER_IDENTIFIER);
100
+
101
+
// Signal with custom payload
102
+
td.signal({
103
+
route:'some/page/path',
104
+
});
69
105
```
70
106
71
-
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, pass it into `userIdentifier` – it will be cryptographically anonymized with a hash function.
107
+
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.
72
108
73
-
If you want to pass optional parameters to the signal being sent, add them to the optional paylaod object.
109
+
If you want to pass optional parameters to the signal being sent, add them to the optional payload object.
74
110
75
111
## More Info
76
112
@@ -80,14 +116,14 @@ Every application and website registered to TelemetryDeck has its own unique ID
80
116
81
117
### 👤 Optional: User Identifiers
82
118
83
-
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.
119
+
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.
84
120
85
121
Feel free to use personally identifiable information as the user identifier: We use a cryptographically secure double-hasing 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 procesing or storing this data.
86
122
87
123
### 🚛 Optional: Payload
88
124
89
-
You can optionally attach an object with string values to the signal. This will allow you to filter and aggregate signal by these values in the dashboard.
125
+
You can optionally attach an object with string values to the signal. This will allow you to filter and aggregate signal by these values in the dashboard.
90
126
91
127
### 📚 Full Docs
92
128
93
-
Go to [docs.telemetrydeck.com](https://docs.telemetrydeck.com) to see all documentation articles
129
+
Go to [docs.telemetrydeck.com](https://docs.telemetrydeck.com) to see all documentation articles
0 commit comments