{"id":22122952,"url":"https://github.com/telemetrydeck/javascriptsdk","last_synced_at":"2025-07-25T14:31:20.577Z","repository":{"id":39705149,"uuid":"446406688","full_name":"TelemetryDeck/JavaScriptSDK","owner":"TelemetryDeck","description":"JavaScript Package for TelemetryDeck, a privacy-conscious analytics service for apps and websites.","archived":false,"fork":false,"pushed_at":"2023-11-30T12:42:09.000Z","size":124,"stargazers_count":11,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-30T17:18:08.462Z","etag":null,"topics":["analytics","analytics-tracking","gdpr","javascript","privacy","privacy-protection"],"latest_commit_sha":null,"homepage":"https://telemetrydeck.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TelemetryDeck.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-10T12:05:54.000Z","updated_at":"2024-10-01T13:32:15.000Z","dependencies_parsed_at":"2023-02-15T02:50:37.410Z","dependency_job_id":"7423da82-13c3-404f-bd32-66edb7819b79","html_url":"https://github.com/TelemetryDeck/JavaScriptSDK","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FJavaScriptSDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FJavaScriptSDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FJavaScriptSDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FJavaScriptSDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TelemetryDeck","download_url":"https://codeload.github.com/TelemetryDeck/JavaScriptSDK/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227584812,"owners_count":17789758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","analytics-tracking","gdpr","javascript","privacy","privacy-protection"],"created_at":"2024-12-01T15:28:31.183Z","updated_at":"2024-12-01T15:28:32.017Z","avatar_url":"https://github.com/TelemetryDeck.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telemetry Deck JavaScript SDK\n\nThis package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from JavaScript code.\n\nTelemetryDeck allows you to capture and analyize users moving through your app and get help deciding how to grow, all without compromising privacy!\n\n\u003e [!NOTE]  \n\u003e 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.\n\n# Set Up\n\nThe TelemetryDeck SDK has no dependencies and supports **modern evergreen browsers** and **modern versions of Node.js** with support for [cryptography](https://caniuse.com/cryptography).\n\n## Set up in Browser Based Applications that use a bundler (React, Vue, Angular, Svelte, Ember, …)\n\n### 1. Installing the package\n\nPlease install the package using npm or the package manager of your choice\n\n### 2. Initializing TelemetryDeck\n\nInitialize the TelemetryDeck SDK with your app ID and your user's user identifer.\n\n```javascript\nimport TelemetryDeck from '@telemetrydeck/sdk';\n\nconst td = new TelemetryDeck({\n  appID: '\u003cYOUR_APP_ID\u003e'\n  user: '\u003cYOUR_USER_IDENTIFIER\u003e',\n});\n```\n\nPlease replace `\u003cYOUR_APP_ID\u003e` with the app ID in TelemetryDeck ([Dashboard](https://dashboard.telemetrydeck.com) -\u003e App -\u003e Set Up App).\n\nYou also need to identify your logged in user. Instead of `\u003cYOUR_USER_IDENTIFIER\u003e`, pass in any string that uniquely identifies your user, such as an email address. It will be cryptographically anonymized with a hash function.\n\nIf can't specify a user identifer at initialization, you can set it later by setting `td.clientUser`.\n\nPlease note that `td.signal` is an async function that returns a promise.\n\n## Set up in Node.js Applications\n\n### 1. Installing the package\n\nPlease install the package using npm or the package manager of your choice\n\n### 2. Initializing TelemetryDeck\n\nInitialize 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.\n\n```javascript\nimport TelemetryDeck from '@telemetrydeck/sdk';\nimport crypto from 'crypto';\n\nconst td = new TelemetryDeck({\n  appID: '\u003cYOUR_APP_ID\u003e'\n  user: '\u003cYOUR_USER_IDENTIFIER\u003e',\n  subtleCrypto: crypto.webcrypto.subtle,\n});\n```\n\nPlease replace `\u003cYOUR_APP_ID\u003e` with the app ID in TelemetryDeck ([Dashboard](https://dashboard.telemetrydeck.com) -\u003e App -\u003e Set Up App).\n\nYou also need to identify your logged in user. Instead of `\u003cYOUR_USER_IDENTIFIER\u003e`, pass in any string that uniquely identifies your user, such as an email address. It will be cryptographically anonymized with a hash function.\n\nIf can't specify a user identifer at initialization, you can set it later by setting `td.clientUser`.\n\nPlease note that `td.signal` is an async function that returns a promise.\n\n\u003e [!NOTE]  \n\u003e 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.\n\n## Advanced Initalization Options\n\nSee the [source code](./src/telemetrydeck.js#L6-L17) for a full list of availble options acepted by the `TelemetryDeck` constructor.\n\n# Sending Signals\n\nSend a basic signal by calling `td.signal()` with a signal type:\n\n```javascript\ntd.signal('\u003cSIGNAL_TYPE\u003e');\n```\n\nSend 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.\n\n```javascript\ntd.signal('Volume.Set', {\n  band: 'Spinal Tap',\n  floatValue: 11.0,\n});\n```\n\n# Advanced: Queueing Signals\n\nThe `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.\n\nThis 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:\n\n```javascript\nexport class Store {\n  async push() // signal bodys are async and need to be awaited before stored\n  clear() // called after flush\n  values() // returns an array of resolved signal bodys in the order they were pushed\n}\n```\n\nThe default implementation can be found in `src/utils/store.js`.\n\n---\n\n[TelemetryDeck](https://telemetrydeck.com?source=github) helps you build better products with live usage data. Try it out for free.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetrydeck%2Fjavascriptsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelemetrydeck%2Fjavascriptsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetrydeck%2Fjavascriptsdk/lists"}