Beacon C++ SDK

The Beacon C++ SDK provides native integration for Windows desktop applications, server processes, and cross-platform C++ projects.

Installation

CMake FetchContent (recommended)

Add Beacon to your CMakeLists.txt:

include(FetchContent)
FetchContent_Declare(
  beacon_sdk
  GIT_REPOSITORY https://github.com/softagility/beacon-sdk-cpp.git
  GIT_TAG        v1.0.0
)
FetchContent_MakeAvailable(beacon_sdk)

target_link_libraries(your_app PRIVATE beacon_sdk)

Build from Source

git clone https://github.com/softagility/beacon-sdk-cpp.git
cd beacon-sdk-cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Dependencies (libcurl, nlohmann_json, SQLite3) are fetched automatically via CMake FetchContent if not found on the system.

System Requirements

C++17 or later
Windows 10+, Linux (glibc 2.28+), or macOS 12+
CMake 3.25+
Dependencies resolved automatically (libcurl, nlohmann_json, SQLite3)

Configuration

#include <beacon/beacon.hpp>

int main()
{
    auto tracker = beacon::Tracker::configure([](beacon::Options& opts) {
        opts.api_key = "your-api-key";
        opts.api_base_url = "https://api.beacon.softagility.com";
        opts.app_name = "MyApp";
        opts.app_version = "1.2.0";
    });

    tracker->identify("user-123");
    tracker->startSession();

    // Your application code here...

    tracker->endSession();
    return 0;
}

You can also pass an Options struct directly:

beacon::Options opts;
opts.api_key = "your-api-key";
opts.api_base_url = "https://api.beacon.softagility.com";
opts.app_name = "MyApp";
opts.app_version = "1.2.0";

auto tracker = beacon::Tracker::configure(opts);

Configuration Options

Option	Type	Default	Description
`api_key`	`std::string`	—	Your Beacon API key (required)
`api_base_url`	`std::string`	—	Beacon API base URL (required)
`app_name`	`std::string`	—	Your application name (required)
`app_version`	`std::string`	—	Your application version (required)
`enabled`	`bool`	`true`	Enable or disable tracking globally
`flush_interval_seconds`	`int`	`60`	Batch send interval in seconds (1-3600)
`max_batch_size`	`int`	`25`	Events per batch, clamped to 1-1000
`max_queue_size_mb`	`int`	`10`	Maximum offline queue size in MB (1-1000)
`max_breadcrumbs`	`int`	`25`	Breadcrumb ring buffer size (0-200)
`logger`	`std::shared_ptr<ILogger>`	`nullptr`	Optional logger for SDK diagnostics

Identifying Users

Before tracking events or sessions, identify the current actor:

tracker->identify("user-123");

Once identified, all subsequent calls use this actor. You can also pass an explicit actor ID to tracking methods.

Tracking Events

Events are organized by category and name, with optional properties.

Basic Event

tracker->track("ui", "button_clicked", {
    {"button_name", "export"},
    {"screen", "dashboard"}
});

With Explicit Actor

tracker->track("reports", "report_exported", "user-456", {
    {"format", "pdf"},
    {"row_count", "1500"}
});

Session Management

// Start a session (uses the identified actor)
tracker->startSession();

// Or start with an explicit actor ID
tracker->startSession("user-123");

// End the current session
tracker->endSession();

Exception Tracking

Track exceptions with severity levels. Breadcrumbs from recent track() calls are attached automatically.

try
{
    process_order(order);
}
catch (const std::exception& ex)
{
    tracker->trackException(ex, beacon::ExceptionSeverity::NonFatal);
    throw;
}

Severity options: beacon::ExceptionSeverity::Fatal and beacon::ExceptionSeverity::NonFatal.

Flushing Events

Events are batched and sent on a timer or when the batch size is reached. To flush manually:

bool success = tracker->flush(); // Blocks up to 30 seconds

Check the last flush result:

beacon::FlushStatus status = tracker->last_flush_status();

Offline Persistence

Events are persisted to a local SQLite database when the network is unavailable. The queue syncs automatically when connectivity returns.

Persists across application restarts
Thread-safe queue with configurable size limit
Zero data loss during transient failures

Singleton Access

After calling configure(), retrieve the tracker instance anywhere with:

auto tracker = beacon::Tracker::instance();

Call beacon::Tracker::reset_for_testing() in test teardown to clear the singleton.

Thread Safety

beacon::Tracker is fully thread-safe. Share a single instance across threads.

RAII Lifetime Management

The SDK follows RAII conventions. When the Tracker shared_ptr reference count reaches zero, pending events are flushed and the active session is ended:

{
    auto tracker = beacon::Tracker::configure(configurator);
    tracker->identify("user-123");
    tracker->startSession();

    // Track events...

} // Session ended, events flushed, resources released

Next Steps

Getting Started for a general overview
API Reference for direct HTTP integration
Pricing for plan details

Beacon C++ SDK

All Documentation