#docs #guides #Setup #JavaScript #Node #NPM #TypeScript
JavaScript App Setup Guide
You have an account, and you have an app ID. Now let's include the TelemetryClient Package in your JS application or web app
The TelemetryDeck SDK has no dependencies and supports modern evergreen browsers and modern versions of Node.js with support for cryptography.
Set Up
When setting up, you need to check wether the platform you’re working on has the SubtleCrytpo API available.
Anytime you’re in a browser context, your code will have access to the default SubtleCrypto implementation. If you’re in Node.js on a server, or in a React Native app, you need to pass in an alternative implementation of the SubtleCrypto API.
The next two sections explain these two cases in detail. Either way, please install the package using npm or the package manager of your choice, such as NPM.
Set up in Browser Based Applications
This is the correct setup procedure for JavaScript code that runs in a browser and can install an NPM package. For example:
- React
- Vue
- Angular
- Svelte
- Ember
- Probably your favorite framework
Initialize the TelemetryDeck SDK with your app ID and your user’s user identifer.
import TelemetryDeck from '@telemetrydeck/sdk';
const td = new TelemetryDeck({
appID: '<YOUR_APP_ID>'
clientUser: '<YOUR_USER_IDENTIFIER>',
});
Please replace <YOUR_APP_ID>
with the app ID in TelemetryDeck (Dashboard -> App -> Set Up App).
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.
If can’t specify a user identifer at initialization, you can set it later by setting td.clientUser
.
Please note that td.signal
is an async function that returns a promise.
Set up in Node.js Applications
Initialize the TelemetryDeck SDK with your app ID and your user’s user identifer. Since globalThis.crypto.subtle
does not exist in Node.js, you need to pass in an alternative implementation provided by Node.js.
import TelemetryDeck from '@telemetrydeck/sdk';
import crypto from 'crypto';
const td = new TelemetryDeck({
appID: '<YOUR_APP_ID>'
clientUser: '<YOUR_USER_IDENTIFIER>',
subtleCrypto: crypto.webcrypto.subtle,
});
Please replace <YOUR_APP_ID>
with the app ID in TelemetryDeck (Dashboard -> App -> Set Up App).
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.
If can’t specify a user identifer at initialization, you can set it later by setting td.clientUser
.
Please note that td.signal
is an async function that returns a promise.
Advanced Initalization Options
See the source code for a full list of availble options acepted by the TelemetryDeck
constructor.
Sending Signals
Send a basic signal by calling td.signal()
with a signal type:
td.signal("<SIGNAL_TYPE>");
Send a signal with a custom payload by passing an object as the second argument. The payload’s values will be converted to Strings, except for floatValue
, which can be a Float.
td.signal("Volume.Set", {
band: "Spinal Tap",
floatValue: 11.0,
});
Privacy Policy and Opt-Out
You don’t need to update your privacy policy, but we recommend you do it anyway.
Advanced: Queueing Signals
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.
Queueing signals can be helpful in situations where you’re battery- or network-constrained and want to be mindful of the user’s available resources. For example, a mobile app might want to queue signals while the user is offline and flush them when the user is back online.
To queue signals instead of sending them immediately, please use td.queue()
instead of td.signal()
, with the same arguments.
td.queue("Band.Setup", {
band: "Spinal Tap",
});
td.queue("Volume.Set", {
band: "Spinal Tap",
floatValue: 11.0,
});
td.queue("Concert.Begin");
// Send all queued signals in a single request
td.flush();
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:
export class Store {
async push() // signal bodys are async and need to be awaited before stored
clear() // called after flush
values() // returns an array of resolved signal bodys in the order they were pushed
}
The default implementation can be found in src/utils/store.js
.
TelemetryDeck helps you build better products with live usage data. Try it out for free.