llms.txt

# Aptabase C++ SDK

> C++ SDK for Aptabase — privacy-first analytics for desktop, server, and game applications. Open source, GDPR compliant, no cookies. Requires C++17. Pluggable HTTP backends (cpp-httplib or Boost.Asio).

## Installation

Add as a CMake subdirectory. You must supply HTTP backend dependencies yourself.

**With cpp-httplib:**

```cmake
# Include cpp-httplib and OpenSSL in your project first

set(CMAKE_APTABASE_USE_HTTPLIB ON)
add_subdirectory(path/to/aptabase-cpp)
target_link_libraries(YourApp PRIVATE AptabaseCpp)
```

**With Boost.Asio:**

```cmake
# Include Boost and OpenSSL in your project first

set(CMAKE_APTABASE_USE_BOOST ON)
add_subdirectory(path/to/aptabase-cpp)
target_link_libraries(YourApp PRIVATE AptabaseCpp)
```

## Initialization

```cpp
#include <aptabase/analytics.hpp>
#include <aptabase/net/httplib.hpp> // or <aptabase/net/boost.hpp>

// Create the Analytics instance with an HTTP client, app key, API URL, and debug flag
Aptabase::Analytics aptabase(
    std::make_unique<Aptabase::HttplibHttpClient>(), // or BoostHttpClient
    "A-US-1234567890",       // your app key
    "https://us.aptabase.com", // API URL (eu/us/self-hosted)
    true                     // is_debug
);
```

## Session Management

Sessions must be explicitly started and ended. A unique session ID is generated per `StartSession` call, or you can provide a custom one.

```cpp
aptabase.StartSession();
// ... record events ...
aptabase.EndSession();

// Or with a custom session ID:
aptabase.StartSession("my-custom-session-id");
```

## Track Events

```cpp
aptabase.StartSession();
aptabase.RecordEvent("app_started");
aptabase.EndSession();
```

## Track Events with Properties

Event attributes support `std::string`, `float`, and `double` value types via `std::variant`.

```cpp
aptabase.RecordEvent("level_completed", {
    {"level", std::string("forest")},
    {"score", 9500.0},
    {"time_seconds", 42.5f}
});
```

## Providers (Event Dispatch Strategy)

The SDK uses a Provider abstraction to control when events are sent to the server.

**AutoProvider** (default): Sends events immediately on each `RecordEvent` call.

**ManualProvider**: Queues events and sends them only when you call `Flush()`. Max 25 events per request.

```cpp
#include <aptabase/provider/manual_provider.hpp>

Aptabase::Analytics aptabase(
    std::make_unique<Aptabase::ManualProvider>(
        std::make_unique<Aptabase::HttplibHttpClient>(),
        "A-US-1234567890",
        "https://us.aptabase.com"
    ),
    true // is_debug
);

aptabase.StartSession();
aptabase.RecordEvent("event1");
aptabase.RecordEvent("event2");
aptabase.Flush(); // sends queued events
aptabase.EndSession();
```

**WorkerProvider**: Runs a background thread that flushes events on a configurable interval.

```cpp
#include <aptabase/provider/worker_provider.hpp>

Aptabase::Analytics aptabase(
    std::make_unique<Aptabase::WorkerProvider>(
        std::make_unique<Aptabase::HttplibHttpClient>(),
        "A-US-1234567890",
        "https://us.aptabase.com"
    ),
    true // is_debug
);
```

## Configuration

System properties can be set at runtime:

```cpp
aptabase.SetAppVersion("1.2.0");
aptabase.SetLocale("en-US");
aptabase.SetOsName("Windows");
aptabase.SetOsVersion("11.0");
aptabase.SetDebug(false);
```

| Method | Description |
|---|---|
| `SetAppVersion` | Application version string (default: "1.0.0") |
| `SetLocale` | User locale (default: "en-US") |
| `SetOsName` | Operating system name (default: "Unknown") |
| `SetOsVersion` | OS version string (default: "0.0.0") |
| `SetDebug` | Toggle debug mode at runtime |
| `SetLog` | Custom log callback: `void(Verbosity, const std::string&)` |

## Platform Notes

- Requires **C++17** (`cxx_std_17`)
- No built-in platform detection — you must set OS name/version/locale yourself
- HTTP backend is pluggable: choose cpp-httplib or Boost.Asio, or implement `Aptabase::HttpClient` interface
- Max 25 events per API request (enforced by `HttpClient::MaxEventsPerRequest`)
- Namespace: `Aptabase::` (classes: `Analytics`, `Event`, `EventAttribute`, providers, HTTP clients)
- Event attribute values are `std::variant<std::string, float, double>` — no int or bool support

## Cross-Discovery

For all Aptabase SDKs (Swift, Kotlin, Flutter, React Native, Electron, Tauri, and more), see https://aptabase.com/llms.txt