npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@telemetrydeck/sdk

v2.0.4

Published

Send analytics signals to TelemetryDeck

Downloads

3,199

Readme

Telemetry Deck JavaScript SDK

This package allows you to send signals to TelemetryDeck from JavaScript code.

TelemetryDeck allows you to capture and analyize users moving through your app and get help deciding how to grow, all without compromising privacy!

[!NOTE]
If you want to use TelemetryDeck for your blog or static website, we recommend the TelemetryDeck Web SDK instead of this JavaScript SDK.

Set Up

The TelemetryDeck SDK has no dependencies and supports modern evergreen browsers and modern versions of Node.js with support for cryptography.

Set up in Browser Based Applications that use a bundler (React, Vue, Angular, Svelte, Ember, …)

1. Installing the package

Please install the package using npm or the package manager of your choice

2. Initializing TelemetryDeck

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>'
  user: '<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

1. Installing the package

Please install the package using npm or the package manager of your choice

2. Initializing TelemetryDeck

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>'
  user: '<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.

[!NOTE]
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 to be a suitable polyfill. Please note that this is not an officially supported solution.

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,
});

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.

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.