Electron Installation

TrackFox supports Electron desktop apps through the trackfox-electron SDK. It tracks screen views, custom events, and revenue — and automatically captures platform metadata like OS, architecture, and app version. Events flow into the same TrackFox dashboard you use for your web properties.

Automatic Setup (Recommended)

The fastest way to add TrackFox to an Electron project is with the CLI. Run this from your project root:

npx trackfox add

The CLI will:

1. Authenticate you via your TrackFox account
2. Create a website entry in your dashboard
3. Install trackfox-electron via npm
4. Detect your main process file (main.ts / main.js and common variants)
5. Inject TrackFox.init() and an initial trackView('Home') call automatically
6. Create a .trackfox.backup of the original file before any changes

After the command completes, review the diff with git diff, then run your app to verify events appear in the dashboard.

---

Manual Setup

Follow these steps if you prefer to configure the SDK yourself, or if the CLI could not locate your main process file.

Step 1: Install the SDK

npm install trackfox-electron

Step 2: Get Your Website ID

1. Log in to your TrackFox dashboard
2. Click the website dropdown in the top navigation
3. Select "Site Settings"
4. Copy your Website ID from the General tab

Step 3: Initialize in the Main Process

Call TrackFox.init() as early as possible in your main process — before the app window opens:

// main.ts
import { app, BrowserWindow, screen, ipcMain } from "electron";
import { TrackFox } from "trackfox-electron";

app.whenReady().then(() => {
  TrackFox.init(
    {
      websiteId: "your-website-id-here",
      domain: "your-app-name", // used as an identifier in the dashboard
    },
    app,
    screen,
    ipcMain // optional — enables renderer-process tracking via the preload bridge
  );

  const win = new BrowserWindow({ ... });
  win.loadFile("index.html");

  // Track the initial screen
  TrackFox.trackView("Home");
});

TrackFox.init() automatically records app launch as the first session event and collects platform metadata — no extra configuration needed.

Step 4: Expose Tracking to the Renderer (Optional)

If you want to track events from your renderer process (HTML/React/Vue pages), add the TrackFox bridge to your preload script:

// preload.ts
import { exposeToRenderer } from "trackfox-electron/preload";

exposeToRenderer();

Register the preload in your BrowserWindow:

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, "preload.js"),
    contextIsolation: true,
  },
});

After this, window.trackfox() is available in your renderer — identical to the web SDK API.

Tracking Screen Views

Call trackView() whenever the user navigates to a new screen. This is the Electron equivalent of a page view.

import TrackFox from "trackfox-electron";

// In your main process navigation logic
TrackFox.trackView("Dashboard");
TrackFox.trackView("Settings");
TrackFox.trackView("Editor");

If you manage navigation in the renderer, use the bridge:

// In renderer (after preload setup)
window.trackfox("navigate", { screen: "Dashboard" });

Tracking Custom Events

Track any user action with trackEvent():

// Main process
TrackFox.trackEvent("export_clicked", {
  format: "csv",
  rowCount: 1500,
});

TrackFox.trackEvent("feature_used", {
  feature: "dark_mode",
  userPlan: "pro",
});

From the renderer after preload setup:

// Renderer process
window.trackfox("button_clicked", {
  buttonId: "upgrade-cta",
  page: "settings",
});

Tracking Signups

TrackFox.trackEvent("signup", {
  email: "user@example.com",
});

Tracking Revenue

Use trackRevenue() for in-app purchases, subscriptions, and license activations:

TrackFox.trackRevenue({
  email: "customer@example.com", // required
  amnt: 4999, // amount in cents ($49.99)
  currency: "USD", // USD, EUR, GBP, CAD, AUD, JPY
  orderId: "order_abc123",
  productId: "pro-license",
  category: "license",
});

What Gets Tracked Automatically

When the SDK is initialized, it captures the following metadata with every event:

Field	Source	Example
appVersion	app.getVersion()	"2.4.1"
electronVersion	process.versions.electron	"28.1.0"
nodeVersion	process.versions.node	"18.18.2"
platform	process.platform	"win32", "darwin", "linux"
arch	process.arch	"x64", "arm64"
osRelease	os.release()	"10.0.26200"
screenResolution	screen.getPrimaryDisplay()	{ width: 1920, height: 1080 }
locale	app.getLocale()	"en-US"
isPackaged	app.isPackaged	true / false

This data appears in your dashboard and lets you filter analytics by OS, platform, and app version.

Offline Support

The SDK buffers events when the user is offline and flushes them automatically when connectivity is restored.

Visitor & Session Identity

Unlike the web SDK (which uses cookies), trackfox-electron persists the visitor ID in your app's user data directory:

%APPDATA%/<your-app>/trackfox.json   (Windows)
~/Library/<your-app>/trackfox.json   (macOS)
~/.config/<your-app>/trackfox.json   (Linux)

• Visitor ID — derived from a stable, OS-level machine identifier (Windows MachineGuid, macOS IOPlatformUUID, Linux /etc/machine-id), one-way hashed (SHA-256) before use — never the raw hardware ID.
• Session ID — resets after 30 minutes of inactivity

TypeScript Support

The SDK ships with full TypeScript types:

import { TrackFox } from "trackfox-electron";
import type { TrackFoxOptions, ElectronInfo } from "trackfox-electron";

Excluding Dev Mode

By default, TrackFox does not send events when your app is running unpacked (i.e. during development). This prevents development noise from polluting your production analytics.

The check is automatic — it uses Electron's app.isPackaged flag, which is false whenever the app is launched via electron . or your dev script, and true only for a distributed build.

If you want to track events during development (useful for testing your integration), set trackInDev: true:

TrackFox.init(
  {
    websiteId: "your-website-id",
    domain: "your-app-name",
    trackInDev: true, // send events even when app.isPackaged is false
  },
  app,
  screen,
  ipcMain,
);

With debug: true, a console message is logged each time an event is suppressed:

[TrackFox] skipping event in dev mode (app.isPackaged=false). Set trackInDev:true to override.

Configuration Reference

TrackFox.init(
  {
    websiteId: string;      // required — from Site Settings in the dashboard
    domain: string;         // required — your app identifier
    apiUrl?: string;        // optional — override for self-hosted TrackFox
    debug?: boolean;        // optional — log events to console
    trackInDev?: boolean;   // optional — track events in dev/unpacked mode (default: false)
  },
  app,       // Electron App instance
  screen,    // Electron Screen instance (for resolution)
  ipcMain?   // optional — pass to enable renderer-process tracking
);

Verification

After setup:

1. Run your Electron app in development
2. Trigger a screen view or custom event
3. Open your TrackFox dashboard
4. Events should appear within a few seconds under the correct website

If debug: true is set in init(), events are also logged to the Electron main process console for easier development-time verification.

Troubleshooting

No events appearing in dashboard

• Confirm the websiteId matches what's shown in Site Settings
• Check that TrackFox.init() is called before trackView() or trackEvent()
• Enable debug: true and check the main process console for errors

Renderer events not working

• Confirm exposeToRenderer() is called in your preload script
• Confirm contextIsolation: true is set in webPreferences
• Check DevTools console for window.trackfox is not defined

Events appearing after a delay

• The SDK may be flushing a queued batch — this is normal after the app reconnects to the internet

Next Steps

• Track custom events
• Set up revenue tracking
• Configure Discord notifications
• Explore the API reference