Getting Started with Beacon

Beacon is a product analytics platform built for ISVs shipping desktop, web, server, and cloud applications. This guide walks you through going from zero to your first tracked event.

Prerequisites

  • A Beacon account (start your free trial)
  • Your API key and API base URL (found in your Beacon dashboard under Settings)
  • An application built with .NET, C++, or JavaScript/TypeScript

Quick Start

1. Choose Your SDK

Beacon provides native SDKs for three platforms:

PlatformPackageInstall Command
.NETSoftAgility.Beacondotnet add package SoftAgility.Beacon
C++beacon_sdkCMake FetchContent (see C++ SDK docs)
JavaScript/TypeScript@softagility/beacon-jsnpm install @softagility/beacon-js

2. Initialize the SDK

Add Beacon to your application startup. Here is a .NET example using dependency injection:

services.AddBeacon(options =>
{
    options.ApiKey = "your-api-key";
    options.ApiBaseUrl = "https://api.beacon.softagility.com";
    options.AppName = "MyApp";
    options.AppVersion = "1.2.0";
});

Or initialize directly without DI:

var tracker = BeaconTracker.Configure(options =>
{
    options.ApiKey = "your-api-key";
    options.ApiBaseUrl = "https://api.beacon.softagility.com";
    options.AppName = "MyApp";
    options.AppVersion = "1.2.0";
});

See the full setup guide for your platform:

3. Identify the User and Start a Session

Beacon uses actors to associate events with users or devices. Identify the current actor and start a session:

tracker.Identify("user-123");
tracker.StartSession();

4. Track Your First Event

Events are organized by category and name:

tracker.Track("reports", "report_exported", new
{
    format = "pdf",
    row_count = 1500
});

5. View Your Data

Log in to the Beacon dashboard. Events appear in real time in the Event Explorer. From there you can build funnels, analyze retention, and segment users.

Environment Collection

Each SDK automatically collects environment data and sends it as a header with each request. The data varies by platform:

.NET and C++ SDKs:

  • Operating system and version
  • Runtime version (.NET version, compiler)
  • Hardware (CPU, memory, display resolution)
  • Locale and timezone
  • Application version

JavaScript / TypeScript SDK:

  • Browser name and version
  • Screen and viewport dimensions
  • Language and platform
  • Device type (desktop, mobile, tablet)
  • Connection type (when available)

No PII is collected. All data is environment and session metadata.

Offline Behavior

The .NET and C++ SDKs include built-in offline persistence via a local SQLite database. If your application loses connectivity, events are queued locally and sync automatically when the connection returns. No data is lost, and the queue persists across application restarts.

The JavaScript SDK uses an in-memory queue with best-effort delivery via fetch with keepalive on page unload. Events are buffered while the tab is open but do not persist across page reloads.

Next Steps

.NET SDK

All Documentation