TelemetryDeck Expo Plugin

An extension plugin for TelemetryDeck React SDK that automatically enriches every signal with rich Expo/React Native environment data and advanced session tracking — with just a few lines of code.

---

Features

• Plug-and-play extension for TelemetryDeck React SDK — just add to plugins array
• Zero native code: fully implemented in TypeScript, built on top of Expo SDK modules (expo-application, expo-device, expo-localization, etc.)
• 40+ automatic parameters added to every TelemetryDeck signal:
  • AppInfo: version, build number, version + build
  • Device: model, OS, architecture, brand, orientation, screen resolution/density, timezone, …
  • SDK: name, version, build type (debug / release)
  • RunContext: locale, target environment, marketplace source, side-loaded flag
  • Accessibility & UserPreferences: font scale, RTL / LTR, color scheme, bold text, reduce motion, …
  • Calendar: day/week/month/quarter/year breakdown, hour of day, weekend flag
  • Session & Retention: session tracking, distinct days used, retention metrics, acquisition analytics
• Advanced Session Tracking: automatic app lifecycle monitoring, persistent storage, 5-minute session timeout
• Retention Analytics: first session date, lifetime sessions, average duration, distinct days used, monthly retention
• Universal — works on iOS and Android (Expo*)
  *Device‐specific metrics gracefully degrade on unsupported platforms
• MIT-licensed, open-source

---

Installation

npm install telemetrydeck-expo-plugin
# or
yarn add telemetrydeck-expo-plugin

Required Dependencies

This plugin extends the TelemetryDeck React SDK and requires the following dependencies:

{
  "@typedigital/telemetrydeck-react": "^0.4.1",
  "@react-native-async-storage/async-storage": ">=1.0.0",
  "expo": ">=49.0.0",
  "expo-application": ">=5.0.0",
  "expo-device": ">=5.0.0",
  "expo-localization": ">=14.0.0",
  "react": ">=16.8.0",
  "react-native": ">=0.70.0"
}

Install them if not already present:

npm install @typedigital/telemetrydeck-react @react-native-async-storage/async-storage
npx expo install expo-application expo-device expo-localization

---

Usage

Basic Setup

This plugin extends the TelemetryDeck React SDK by automatically adding Expo/React Native environment data to every signal. Simply add it to the plugins array when creating your TelemetryDeck instance:

import { createTelemetryDeck } from "@typedigital/telemetrydeck-react";
import { expoPlugin } from "telemetrydeck-expo-plugin";

const td = createTelemetryDeck({
  app: "YOUR-APP-ID",
  user: "anonymous",
  plugins: [expoPlugin], // ← Add the Expo plugin here
});

// Use TelemetryDeck as usual - all signals now include rich Expo context
const { signal } = useTelemetryDeck();
signal("app_launched");

Session Tracking (Optional)

For advanced session tracking and retention analytics, add the session enhancement plugin and initialize session tracking:

import { createTelemetryDeck } from "@typedigital/telemetrydeck-react";
import {
  expoPlugin,
  sessionEnhancementPlugin,
  initSessionTracking,
} from "telemetrydeck-expo-plugin";

const td = createTelemetryDeck({
  app: "YOUR-APP-ID",
  user: "anonymous",
  plugins: [
    expoPlugin,
    sessionEnhancementPlugin, // ← Add session enhancement
  ],
});

// Initialize session tracking
initSessionTracking(td);

React Hook (Recommended)

Use the React hook for automatic session tracking setup:

import { useSessionTracking } from "telemetrydeck-expo-plugin";

function App() {
  useSessionTracking(); // ← Automatically handles session tracking

  return <YourApp />;
}

For complete TelemetryDeck React SDK documentation, see: https://github.com/typedigital/telemetrydeck-react

Every signal sent through TelemetryDeck will now automatically include rich context about the user's device, environment, preferences, and session metrics — no extra work required.

---

What Data is Collected

This plugin automatically enhances every TelemetryDeck signal with the following parameters:

App Information

• TelemetryDeck.AppInfo.version - App version (e.g., "1.0.0")
• TelemetryDeck.AppInfo.buildNumber - Build number (e.g., "123")
• TelemetryDeck.AppInfo.versionAndBuildNumber - Combined version and build

Device Information

• TelemetryDeck.Device.architecture - CPU architecture (e.g., "arm64")
• TelemetryDeck.Device.modelName - Device model (e.g., "iPhone 14 Pro")
• TelemetryDeck.Device.operatingSystem - OS name (e.g., "iOS")
• TelemetryDeck.Device.platform - Platform (e.g., "ios", "android")
• TelemetryDeck.Device.systemVersion - OS version (e.g., "17.0")
• TelemetryDeck.Device.brand - Device brand (e.g., "Apple")
• TelemetryDeck.Device.orientation - Screen orientation
• TelemetryDeck.Device.screenResolution* - Screen dimensions
• TelemetryDeck.Device.screenDensity - Pixel density
• TelemetryDeck.Device.timeZone - User's timezone

SDK Information

• TelemetryDeck.SDK.name - SDK name
• TelemetryDeck.SDK.version - SDK version
• TelemetryDeck.SDK.buildType - "debug" or "release"

Runtime Context

• TelemetryDeck.RunContext.locale - User's locale (e.g., "en-US")
• TelemetryDeck.RunContext.targetEnvironment - Target platform
• TelemetryDeck.RunContext.isSideLoaded - Whether app is side-loaded
• TelemetryDeck.RunContext.sourceMarketplace - App store source

User Preferences & Accessibility

• TelemetryDeck.UserPreference.colorScheme - "Light" or "Dark"
• TelemetryDeck.UserPreference.layoutDirection - "leftToRight" or "rightToLeft"
• TelemetryDeck.UserPreference.language - User's language
• TelemetryDeck.UserPreference.region - User's region
• TelemetryDeck.Accessibility.fontScale - Font scaling factor
• TelemetryDeck.Accessibility.isBoldTextEnabled - Bold text preference
• TelemetryDeck.Accessibility.isReduceMotionEnabled - Reduce motion preference
• And more accessibility settings...

Calendar Information

• TelemetryDeck.Calendar.dayOfMonth - Day of month (1-31)
• TelemetryDeck.Calendar.dayOfWeek - Day of week (1-7, Monday=1)
• TelemetryDeck.Calendar.monthOfYear - Month (1-12)
• TelemetryDeck.Calendar.quarterOfYear - Quarter (1-4)
• TelemetryDeck.Calendar.isWeekend - Weekend flag
• TelemetryDeck.Calendar.hourOfDay - Hour of day (0-23)

Session Information

• TelemetryDeck.Session.started - Session start timestamp

Session Tracking & Retention

• TelemetryDeck.Acquisition.FirstSessionDate - Date of first app usage
• TelemetryDeck.Retention.DistinctDaysUsed - Number of distinct days user used the app
• TelemetryDeck.Retention.DistinctDaysUsedLastMonth - Days used in last month
• TelemetryDeck.Retention.TotalSessionsCount - Lifetime number of sessions
• TelemetryDeck.Retention.AverageSessionSeconds - Average session duration
• TelemetryDeck.Retention.PreviousSessionSeconds - Duration of previous session

Automatic Session Signals:

• TelemetryDeck.Session.started - Sent when a new session begins
• TelemetryDeck.Acquisition.newInstallDetected - Sent on first app launch

---

Development

Build & Test

To build the TypeScript sources:

npm run build

To run tests:

npm test

To clean build artifacts:

npm run clean

Test files are located in src/__tests__/ and use Jest with babel-jest.

Making a Release

This project uses automated releases via GitHub Actions. To create a new release:

1. Update the version in package.json:

   npm version patch   # for bug fixes (1.0.0 → 1.0.1)
   npm version minor   # for new features (1.0.0 → 1.1.0)
   npm version major   # for breaking changes (1.0.0 → 2.0.0)

2. Push the version tag:

   git push origin v1.0.1  # replace with your version

3. Automated workflow will:

   • Run tests and build the project
   • Publish to npm with provenance
   • Auto-generate changelog from commits and merged PRs
   • Create a GitHub Release with release notes
   • Update package badges and links

Note: The changelog is automatically generated from:

• All commits since the last release (with author names)
• Merged pull requests (with PR numbers and titles)

Manual Publishing

If you need to publish manually (not recommended):

npm run build
npm test
npm publish

The prepublishOnly script will automatically run build and tests before publishing.

---

Why Use This Plugin?

Understanding who, where and how users run your app is crucial for actionable analytics. This plugin eliminates boilerplate and keeps your telemetry clean, consistent and privacy-respectful while giving you deep insights for product decisions.

---

Contributing

PRs and issues are welcome! Please follow conventional-commits and respect the project's code of conduct.

Development Setup

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test
4. Build: npm run build

---

License

MIT License - see LICENSE file for details.

---

Enjoy effortless telemetry! 🚀