How to Use TelemetryDeck: The Beginner's Guide (First Project, the Signal Lesson, Test Mode, and the Dashboard Arc)

CodexFuse Team · 2026-11-02T03:13:16.655Z · 18 min read

Learn how to use TelemetryDeck, the privacy-first mobile app analytics platform: send signals with on-device anonymization, master test mode, and read your first dashboard.

What Is TelemetryDeck, Exactly?

TelemetryDeck is a privacy-first mobile app analytics platform built specifically for app developers — and if you are learning how to use TelemetryDeck, start with the mental model its makers use: you send SIGNALS at significant moments in your code, the SDK performs anonymization on device before anything leaves the phone, and you read the results on a dashboard. Say it once and keep it: no personal data, no user profiles, just signals about what happened in your app.

One terminology note, because the docs use both: signals were renamed to events in a later SDK generation because that made more semantic sense. In current documentation and the API reference the two words describe the same thing — a signal (or event) is an indication that something happened in your app, consisting of a Signal Name, a User Identifier, and Optional Parameters. This telemetrydeck tutorial will use the word signals, matching the guides most beginners start with.

If you know website analytics, TelemetryDeck is the app-side cousin of the privacy-analytics lane the Umami beginner guide workflows describe — Umami and Plausible measure websites without cookies, TelemetryDeck measures apps without personal data. Different surface, same privacy-first instinct. The line is drawn once: this page covers the mobile-app-analytics lane; it never replaces a web-analytics guide.

Why Do Developers Choose Privacy-First Mobile Analytics?

They choose it because the old analytics deal was toxic: every event tied to an advertising ID, an IP address, and a cross-app identity graph, all shipped to a server for profile building. TelemetryDeck inverts the deal — anonymization happens ON DEVICE, which means the server never receives anything it could tie to a person.

The maker's privacy FAQ states the position plainly, and this article states it in their words rather than paraphrasing: TelemetryDeck "is privacy friendly and will never collect personally identifiable information." It "does not collect any data governed by privacy laws such as GDPR or CCPA," which is why the FAQ says no opt-out, cookie banner, or privacy-policy mention is legally required — though it recommends one anyway as best practice. IP addresses are never stored, "neither in the database nor in log files or anywhere else," timestamps are rounded to the nearest hour, and the anonymized user ID is constant per app install but cannot be traced back to personal information.

The privacy FAQ also answers the data-residency question: servers are distributed across Microsoft Azure (Amsterdam), AWS (Frankfurt), and Hetzner (Falkenstein and Nürnberg, Germany). And one honesty point the makers keep repeating: even with all of this, you still must fill out App Store Connect privacy details for your app — the Swift SDK ships a privacy manifest to make that possible. Privacy-first does not mean paperwork-free.

How Do You Set Up Your First Project?

You set up your first project in the dashboard, and the whole flow takes about five minutes. Every account belongs to an organization, so register at the dashboard, enter an organization name, click Create your Account, and log in with email and password.

From there, follow this arc — the App ID at the end is the value every SDK snippet needs:

1. Open the dashboard and click the top-left dropdown next to the logo, then Create New App.
2. Give the app a name your future self will recognize — this name appears on every chart you build later. If you are following this as a telemetrydeck for beginners walkthrough, the canonical arc is account → App ID → one SDK → test signals → first dashboard, and this section is step one.
3. Open the app's settings from the left sidebar, then the Set Up App page under SETTINGS.
4. Copy the unique identifier — your App ID — from that page. Say it once: this one string is what connects every SDK in your apps to this dashboard project.
5. Store it somewhere your build can read it (an Info.plist entry, a build-config value, a dotenv file). It is not a secret in the cryptographic sense, but it belongs in configuration, not hardcoded where it cannot change.

That is the first-project arc complete. Everything after this — SDKs, signals, test mode, dashboards — hangs off the App ID you just copied.

What Is the Signal Lesson?

The signal lesson is the single most important idea in this guide, so say it once: a signal is not a pageview, not a session, and not a click — it is a statement that something meaningful happened, fired from exactly the place in your code where it happened. TelemetryDeck.signal("Oven.Bake.startBaking") in the maker's own Swift example fires when a pizza oven starts baking, with parameters describing the state of the app at that moment.

The docs define a signal's anatomy precisely: a Signal Name (a string), a User Identifier (a string — one is auto-generated for you), and Optional Parameters (a dictionary of extra data). The naming convention matters more than it looks: signal types should be "short, camel-cased half-sentences" like App.launchedRegularly, App.enteredBackground, or Settings.opened, because the dashboard's Insights filter by Event Type. Sloppy naming on day one becomes an unfilterable mess by day ninety.

Two privacy mechanics ride along with every signal, and both get one mention. First, the clientUser identifier — a UUID by default, often from identifierForVendor — is hashed ON DEVICE before sending and hashed AGAIN on the server. Pass an empty string and user counting is disabled entirely while sessions and events still work. Second, the Swift privacy note most beginners miss: the value passed to customUserID is hashed automatically, but PARAMETER values are NOT hashed — they travel verbatim. Hash parameter values yourself where needed, and never put personal data in parameters. Say it once; violations of this rule are the one privacy mistake this SDK cannot fix for you.

How Do You Install the Swift SDK?

You install the Swift SDK through Swift Package Manager, and the current stable line as of this writing is 2.14.2, with a 3.0.0-beta.5 pre-release in progress per the GitHub releases page. Add the package in Xcode via File > Add Package Dependencies with the rule "Up to Next Major Version" using the package URL https://github.com/TelemetryDeck/SwiftSDK, then link the TelemetryDeck product — note the product named TelemetryClient is deprecated, link the new one.

Initialization is two lines, done once at launch before any signal fires:

let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")
TelemetryDeck.initialize(config: config)

After that, send signals from anywhere — no instance to hold, no singleton to pass around:

TelemetryDeck.signal("Oven.Bake.startBaking")
TelemetryDeck.signal("Oven.Bake.startBaking", parameters: ["numberOfTimesPizzaModeHasActivated": "3"])

Parameter values are [String: String], so cast numbers and booleans to strings. Two conveniences come free: the SDK auto-sends TelemetryDeck.Session.started on launch, so initialization alone gives you session, launch, and device tracking "without any additional code." And for timing things, duration signals exist on Swift and Kotlin — TelemetryDeck.startDurationSignal("...") and TelemetryDeck.stopAndSendDurationSignal("...") — with the measured duration arriving as TelemetryDeck.Signal.durationInSeconds at millisecond precision, thread-safe.

Two config knobs worth knowing on day one: config.defaultSignalPrefix and config.defaultParameterPrefix namespace your signals, and config.defaultParameters takes a closure whose values get merged into every signal you send. The guide is tested on Xcode 16 and Swift 5.9. And because this integration lives in your repo like any other SDK, the Git beginner guide workflows apply — commit the integration, keep the App ID in build configuration, and treat signal names as a contract your whole team can read.

How Do You Use TelemetryDeck on Android?

You use the Kotlin SDK from Maven Central, currently 6.0.1 per the official Android setup guide — note this supersedes older platform pages that mention jitpack; follow the setup guide. Add the dependency to app/build.gradle.kts:

implementation("com.telemetrydeck:kotlin-sdk:6.0.1")

Add the internet permission to AndroidManifest.xml, then declare the App ID once inside the <application> block:

<meta-data android:name="com.telemetrydeck.sdk.appID" android:value="YOUR-APP-ID"/>

Send signals with one import and one call:

import com.telemetrydeck.sdk.TelemetryDeck
TelemetryDeck.signal("pizzaOrderConfirmed")

Requirements are modest: Android SDK 21 or newer, and the same initialization-before-sending rule as Swift — you cannot send events before TelemetryDeck is initialized. Duration signals work on Kotlin too, and the signal-type naming convention (short camel-cased half-sentences) applies identically, so a team shipping on both platforms can share one signal-name glossary.

How Do You Use TelemetryDeck with React Native?

You use the community React SDK, installed with one command: npm install -S @typedigital/telemetrydeck-react. Say it once: the package is developed by Augsburg-based web development agency typedigital, and the official React setup guide points to it.

The pattern is a provider high in your component tree plus a hook for sending:

import { TelemetryDeckProvider, useTelemetryDeck } from "@typedigital/telemetrydeck-react";

<TelemetryDeckProvider appID="YOUR-APP-ID">
  <App />
</TelemetryDeckProvider>

const { send } = useTelemetryDeck();
send("Cart.checkoutCompleted");

Expo users get one extra step: Expo needs expo-crypto and text-encoding plus a globals.js that patches globalThis.crypto and TextEncoder, because the SDK expects those globals and Expo does not provide them by default. This is the telemetrydeck react native path fully covered — alongside telemetrydeck swift and telemetrydeck android, all three SDK lanes live on this one page, one page per intent cluster.

What Is Test Mode?

Test Mode is the one section where Test Mode and production must never be confused, so here it is once: test signals go to a SEPARATE dataset, and they never pollute your live data. The maker's start-here page says it plainly — "Before submitting your app to the App Store, we recommend testing your analytics locally... It sends test signals to a separate dataset, so you can safely experiment, validate your setup, and try out features — without affecting your real data."

Most SDKs enable Test Mode automatically in development, or you can toggle it manually. On Swift, DEBUG builds running from Xcode are automatically tagged as Test Signals — if you panic that your dashboard is empty after a debug run, you are looking at the production dataset: open Explore, then Recent Signals, and turn the Test Mode toggle ON. The homepage's guarantee is the one to remember: "All data in test mode will be marked as test data and will not pollute your live data later."

The practical habit: develop and validate against Test Mode all day, flip to the production dataset only to confirm the first real release is flowing, and never ship a build with a debug-only Test Mode toggle burned in. Test Mode is for the lab; the dashboard's real charts start counting when your release build is in the wild.

How Do You Read Your First Dashboard?

You read your first dashboard by knowing which of the six areas answers which question. The maker's dashboard guide names them: Overview (daily active users, total users, retention, app version and system version distribution), Customers (the user journey from discovery to monetization), Metrics (technical: devices and platforms), Explore (raw signal data — signal types, parameters, Recent Signals, and a query playground), Dashboards (custom insights built with a visual editor or TQL), and Notebooks (live charts mixed with markdown).

The start-here page frames the built-in charts around the AARRR pirate metrics, and this is where privacy-first mobile analytics earns its keep — acquisition, activation, retention, and revenue charts that never needed a personal identifier to compute. Beyond those four: error and crash tracking, where TelemetryDeck "will automatically categorize errors and crashes sent by your application"; localization and accessibility insights; and revenue, which works standalone (send purchase events directly) or through the RevenueCat integration, where you pass your TelemetryDeck App ID and user ID as RevenueCat attributes.

Start with Overview for the first week. Graduate to Explore when a number surprises you — Recent Signals shows you exactly which signals fired, with their parameters, in real time. Notebooks are where teams keep their living write-ups: charts that stay current with markdown that explains what the chart meant when it was written.

How Do Funnels and Custom Queries Work?

Funnels and custom queries work through TQL — the TelemetryDeck Query Language — plus a visual editor for the days you do not want to write a query. A funnel answers "how many users who did step one went on to do step two?" Create an Insight, pick the funnel chart and the funnel query, and define each step with the visual filter editor; previous conditions automatically apply to the following steps, so each stage of the funnel is a subset of the one before.

TQL itself is a JSON-based query language derived from the industry-standard Druid Query Language — correction for anyone who expected a GraphQL API: there is no TelemetryDeck GraphQL endpoint; the custom-query surface is TQL plus the Visual Query Editor. TQL also accepts default SQL queries and converts them automatically, and there is a query Playground for trying things out. The documented query types are:

A funnel query has one required property — steps, a list of FilterStep objects (each with a filter and a name) — compiled at runtime into a groupBy query "with a vastly simpler syntax." You will almost never write one by hand: the visual filter editor generates it. The lesson for beginners is which type matches which question, not the syntax.

TelemetryDeck vs PostHog: What Is the Difference?

The difference is the lane, and the lane line gets one paragraph. TelemetryDeck is mobile-app signal analytics with on-device anonymization — signals at significant moments, no personal data, no user profiles. PostHog is web product analytics built on per-user event tracking. They are not rivals: if you ship an app and need privacy-first answers about that app, TelemetryDeck; if you run a website and want deep per-user product analytics, PostHog's lane.

The PostHog beginner guide covers the web-analytics side in full, so this page will not. Two practical notes for teams that use both: keep your naming conventions consistent across the two tools (a camel-cased signal glossary survives the boundary), and remember that TelemetryDeck's anonymized identifiers cannot be joined to a web identity — that is a feature, not a limitation, and it is exactly why the privacy FAQ can make the claims it makes.

How Much Does TelemetryDeck Cost?

TelemetryDeck costs nothing until you outgrow 50,000 events per month, and paid plans start at €9 per month. The free tier stores your data but stops showing it past the first 50,000 events each month — so a side project and a small indie app live comfortably on free, while a breakout app hits the paid tier the way it should: because people are actually using it.

One freshness note for 2026: older official pages (the 2023 spring update, an April 2026 partner post) cite 100,000 signals per month on the free tier. That figure is superseded — use the current 50,000 figure. No discount is cited or promised in this guide.

What Is the Testflight and App-Store Checklist?

The checklist is what stands between a working Test Mode and a compliant release. First, run the whole flow on a TestFlight build — DEBUG-only test signals stop arriving once you ship a release configuration, so confirm real signals land in the production dataset from at least one external tester. Second, complete your App Store Connect privacy details: TelemetryDeck's SDK ships a privacy manifest, and the makers' own privacy FAQ reminds you that this step is still yours.

Third, audit your parameters once before the first release build — grep for any personal data a hurried developer might have slipped into a parameter dictionary, remembering that parameter values travel verbatim while only customUserID is hashed. Fourth, automate the boring part: the GitHub Actions beginner guide workflows show how to run your release pipeline from CI, which is where TestFlight uploads and pre-release checks belong — including a step that fails the build if a forbidden DEBUG flag is present.

When the release build is in the wild, your Test Mode dataset stays where it belongs: in the lab, behind the toggle. The production dataset is your real product from here on.

7 Beginner Mistakes to Avoid

Every mistake in this table comes from the maker's own docs — these are the ones beginners actually make, sourced, not invented:

Sources

Facts in this TelemetryDeck tutorial were verified from sources fetched on 2026-11-02: the TelemetryDeck homepage (telemetrydeck.com — "Send signals at significant moments in your code with custom metadata," anonymization "on device," "All data in test mode will be marked as test data and will not pollute your live data later"); the start-here page (telemetrydeck.com/start-here — account setup, Test Mode, AARRR built-in charts); the Swift setup guide (telemetrydeck.com/docs/guides/swift-setup — package URL, TelemetryDeck.Config init, signal() syntax, Test Signals in DEBUG builds, the parameter-values-are-not-hashed privacy note, Xcode 16 / Swift 5.9); the signals API reference (telemetrydeck.com/docs/api/signals-reference — signal anatomy, camel-cased half-sentence naming, clientUser double hashing, signal-to-event rename); the Android setup guide (telemetrydeck.com/docs/guides/android-setup — Maven Central com.telemetrydeck:kotlin-sdk:6.0.1, App ID meta-data, SDK 21+, INTERNET permission); the React setup guide (telemetrydeck.com/docs/guides/react-setup — @typedigital/telemetrydeck-react, developed by typedigital, TelemetryDeckProvider, Expo expo-crypto/text-encoding patch); the making-account guide (telemetrydeck.com/docs/articles/making-account — organization, Create New App, App ID on Set Up App); the dashboard guide (telemetrydeck.com/docs/basics — Overview/Customers/Metrics/Explore/Dashboards/Notebooks); the TQL docs (telemetrydeck.com/feature/tql and telemetrydeck.com/docs/tql — JSON-based language derived from the Druid Query Language, SQL accepted, visual editor, timeseries/topN/groupBy/funnel/retention/scan); the funnel feature guide (per the maker's funnel guide — visual filter editor, FilterStep steps); the duration-tracking blog post (telemetrydeck.com/blog/introducing-duration-tracking — startDurationSignal/stopAndSendDurationSignal, durationInSeconds, millisecond precision); the RevenueCat integration post (telemetrydeck.com/blog/revenuecat-integration — revenue dashboard, $telemetryDeckAppId attributes); the privacy FAQ (telemetrydeck.com/docs/guides/privacy-faq — "will never collect personally identifiable information," IP addresses never stored, Azure/AWS/Hetzner regions); the Mixpanel and Matomo comparison pages (telemetrydeck.com/comparison — free tier 50,000 events/month, paid from €9/month, GDPR/DPA/TADPF/DPF/CCPA/PECR); the GitHub SwiftSDK releases page (2.14.2 stable, 3.0.0-beta.5 pre-release); and the web-setup docs (Web SDK 3.0, released 2026-09-23). The 2023-era 100,000-signal free-tier figure is superseded by the current 50,000 figure and is cited only as superseded.

Frequently Asked Questions

Is TelemetryDeck really privacy-friendly?

In the maker's own stated terms: it performs anonymization on device before anything is sent, never collects personally identifiable information, never stores IP addresses, rounds timestamps to the nearest hour, and does not process data governed by GDPR or CCPA. You still fill out App Store Connect privacy details, and the SDK ships a privacy manifest for that.

What is the difference between a signal and an event in TelemetryDeck?

Nothing anymore — they are the same thing. Signals were renamed to events in a later SDK generation because the new name made more semantic sense, and both words appear in current docs. This guide uses "signals" to match the setup guides most beginners start with.

Can I test TelemetryDeck without polluting my real analytics?

Yes — that is exactly what Test Mode is for. Test signals go to a separate dataset that never touches your production data; DEBUG builds running from Xcode are automatically tagged as Test Signals, and you view them in Explore → Recent Signals with the Test Mode toggle on.

How much does TelemetryDeck cost?

The free tier covers up to 50,000 events per month — the dashboard stops showing data past that limit until you upgrade — and paid plans start at €9 per month. Older pages citing 100,000 free signals are out of date; 50,000 is the current figure.

Should I use TelemetryDeck or PostHog?

Different lanes: TelemetryDeck for privacy-first mobile app analytics with on-device anonymization and no user profiles; PostHog for web product analytics built on per-user event tracking. Teams with both an app and a website can use both — TelemetryDeck's identifiers just cannot be joined to a web identity, by design.