Git Product home page Git Product logo

javascriptsdk's Introduction

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.

javascriptsdk's People

Contributors

mslepko avatar pichfl avatar timidak avatar winsmith avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

javascriptsdk's Issues

Error loading script

Hi ๐Ÿ‘‹ ,

While following the guide at https://telemetrydeck.com/docs/guides/javascript-setup/ I added the TD script to the head section as instructed, however the script throws an error when loading:

In Safari 16.5:
Screenshot 2023-06-01 at 11 55 17

In Firefox 113.0.2:
Screenshot 2023-06-01 at 11 59 16

...
 <script src="https://unpkg.com/@telemetrydeck/sdk/dist/telemetrydeck.min.js" defer></script>

The error occurs before calling any of the setup functions (like adding app key and user identifier).

Could you help me spot what I'm doing wrong?

Refactor into poly form cross-compatible module

We're splitting up the JavaScript SDK into two parts:

  1. This repo will contain a module that can be imported into node based projects and will also be used by an upcoming React SDK
  2. A new repo, "WebSDK" will contain code that can be run directly from a website such as Wordpress

Refactor this repository into a package that is used in proper node projects.

Undefined behavior when loading TD and then pushing multiple items at once

STR

  • When you include the SDK
  • wait for it to load
  • and then call td.push(...) with multiple entries

only the first element of the pushed elements is called.

Example that will not send a signal:

// assume window.td is already loaded at this point
window.td.push(["app", "LOLOLOL"], ["user", "anon"], ["signal"]);

Update README

  • The readme links to docs.telemetrydeck.com but it should link to telemetrydeck.com/docs
  • double hasing ๐Ÿฐ

Send payload as dict

Since the Ingest v2 API now supports payloads as dictionaries, we should no longer convert the payload into a colon-separated array.

USER_IDENTIFIER should be optional

I used the JavascriptSDK on a website where I don't have a user identifier (and don't want to have one). When reading the documentation at https://telemetrydeck.com/docs/guides/javascript-setup/ , I saw the section Optional: User Identifiers and the sentence If you have none, consider anonymous.

I assumed that I could avoid to give a user and simply use something like:

td.push(["app", YOUR_APP_ID], ["signal"]);

This resulted in an error:

Error

See corresponding documentation:

Documentation

I would expect not to have an error if you pass no user. The backend should automatically assign a signal with no user to an anonymous user.

javascript sdk not working at all

tried both ways exactly as described in the docs: importing the sdk via a script tag in the header of a site and importing the npm package and then building the site.

header script tag: no errors come up and the network tab shows:

Request URL: https://unpkg.com/@telemetrydeck/sdk/dist/telemetrydeck.min.js
Request Method: GET
Status Code: 302 
Remote Address: [2606:4700::6810:7aaf]:443
Referrer Policy: strict-origin-when-cross-origin

no payload is sent

npm import:

import { TelemetryDeck } from 'telemetry-deck';

throws an error "dependency not found"

System: node 14.17.0, npm 7.24.0, vue with nuxt 2.15.7

Error when running in non-secure mode

I am trying to integrate TelementryDeck into a simple static website (statushook.cool) and I get an error in the console of my developer tools and TelemetryDeck does not log any signals.

In Chrome the message is:
TypeError: Cannot read properties of undefined (reading 'digest')

In Safari 15.5 the message is:
TypeError: undefined is not an object (evaluating 'crypto.subtle.digest')

Is there a way t fix this? Feel free to poke into the website code to see how it's set up in the <head>

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.