# Aptabase SDK reference

> Aptabase is an open-source, privacy-first analytics platform for mobile, desktop and web apps — an alternative to Google Firebase Analytics that collects no personal data, uses no cookies or device identifiers, and needs no consent banner.

Install, initialization and tracking code for all 17 SDKs. For product facts, pricing and the page index see https://aptabase.com/llms.txt.

## General notes

- Get your App Key from the Aptabase dashboard under the "Instructions" menu.
- App keys follow the format `A-EU-*` (European Union) or `A-US-*` (United States).
- Nothing is tracked automatically — you call the track function for each event.
- Every event is enriched automatically with OS name/version, app version and locale.
- Custom property values must be strings or numbers.
- Tracking calls are non-blocking and run in the background.
- Events are separated into Debug and Release build modes automatically (see https://aptabase.com/docs/build-modes).

## Swift (iOS, macOS, watchOS, tvOS)

Package: `Aptabase (Swift Package Manager)`
Install: `Add https://github.com/aptabase/aptabase-swift.git via SPM or Xcode`
Repo: https://github.com/aptabase/aptabase-swift

### Initialization

```swift
import SwiftUI
import Aptabase

@main
struct ExampleApp: App {
    init() {
        Aptabase.shared.initialize(appKey: "<YOUR_APP_KEY>")
    }

    var body: some Scene {
        WindowGroup {
            MainView()
        }
    }
}
```

### Track events

```swift
import Aptabase

Aptabase.shared.trackEvent("app_started")
Aptabase.shared.trackEvent("screen_view", with: ["name": "Settings"])
```

### Platform notes

- macOS: enable "Outgoing Connections (Client)" under App Sandbox.
- For App Store submission, see the Apple App Privacy guide: https://aptabase.com/docs/apple-app-privacy

Guide: https://aptabase.com/for-swift

## Kotlin (Android)

Package: `com.github.aptabase:aptabase-kotlin (JitPack)`
Install: `implementation("com.github.aptabase:aptabase-kotlin:0.0.8")`
Repo: https://github.com/aptabase/aptabase-kotlin

### Setup

Add the JitPack repository in `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://www.jitpack.io") }
    }
}
```

Then add the dependency in your module-level `build.gradle.kts`: `implementation("com.github.aptabase:aptabase-kotlin:0.0.8")`.

### Initialization

Initialize in your `Application` class:

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Aptabase.instance.initialize(applicationContext, "<YOUR_APP_KEY>")
    }
}
```

### Track events

```kotlin
Aptabase.instance.trackEvent("app_started")
Aptabase.instance.trackEvent("screen_view", mapOf("name" to "Settings"))
```

Guide: https://aptabase.com/for-android

## Flutter

Package: `aptabase_flutter (pub.dev)`
Install: `flutter pub add aptabase_flutter`
Repo: https://github.com/aptabase/aptabase_flutter
Platforms: Android, iOS, macOS, Web, Linux, Windows

### Initialization

In `main.dart`:

```dart
import 'package:aptabase_flutter/aptabase_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Aptabase.init("<YOUR_APP_KEY>");
  runApp(const MyApp());
}
```

The `main` function must be `async` and call `WidgetsFlutterBinding.ensureInitialized()` before init.

### Track events

```dart
import 'package:aptabase_flutter/aptabase_flutter.dart';

Aptabase.instance.trackEvent("app_started");
Aptabase.instance.trackEvent("screen_view", {"name": "Settings"});
```

### Platform notes

- Android: add `<uses-permission android:name="android.permission.INTERNET" />` to `AndroidManifest.xml`.

Guide: https://aptabase.com/for-flutter

## React Native

Package: `@aptabase/react-native`
Install: `npm add @aptabase/react-native`
Repo: https://github.com/aptabase/aptabase-react-native

### Initialization

```jsx
import Aptabase from "@aptabase/react-native";

Aptabase.init("<YOUR_APP_KEY>");

export default function App() {
  return <MyApp />;
}
```

### Track events

```js
import { trackEvent } from "@aptabase/react-native";

trackEvent("app_started");
trackEvent("screen_view", { name: "Settings" });
```

### Platform notes

- Android: add `<uses-permission android:name="android.permission.INTERNET" />` to `AndroidManifest.xml`.
- Expo: events sent from Expo Go will not have an App Version. Set `appVersion` in the `init()` options during development, or build a standalone app.
- To stop tracking: `Aptabase.dispose()`.

Guide: https://aptabase.com/for-react-native

## NativeScript

Package: `@nicogaldo/nativescript-aptabase`
Install: `npm add @nicogaldo/nativescript-aptabase`
Repo: https://github.com/nstudio/nativescript-plugins/tree/main/packages/nativescript-aptabase
Maintained by the community.

### Track events

Community-maintained plugin by nstudio; see the README for setup and initialization.

```typescript
Aptabase.track("play_music", {
  name: "Here comes the sun"
});
```

Guide: https://aptabase.com/for-nativescript

## Electron

Package: `@aptabase/electron`
Install: `npm add @aptabase/electron`
Repo: https://github.com/aptabase/aptabase-electron

### Initialization (main process)

```js
import { initialize } from "@aptabase/electron/main";

initialize("<YOUR_APP_KEY>");

app.whenReady().then(() => {
  // ... rest of app initialization
});
```

### Track events

The `trackEvent` function is available under separate import paths depending on the process: `@aptabase/electron/main` for the main process and `@aptabase/electron/renderer` for the renderer process.

```js
import { trackEvent } from "@aptabase/electron/renderer";

trackEvent("app_started");
trackEvent("screen_view", { name: "Settings" });
```

Guide: https://aptabase.com/for-electron

## Tauri

Package: `tauri-plugin-aptabase (Rust) + @aptabase/tauri (JavaScript)`
Install: `cargo add tauri-plugin-aptabase && npm add @aptabase/tauri`
Repo: https://github.com/aptabase/tauri-plugin-aptabase

### Initialization (Rust)

Register the plugin in your Tauri builder:

```rust
#[tokio::main]
async fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_aptabase::Builder::new("<YOUR_APP_KEY>").build())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

Add `aptabase:allow-track-event` to your Access Control List.

### Track events (Rust)

Import the `EventTracker` trait to call `track_event` on `App`, `AppHandle` or `Window`:

```rust
use tauri_plugin_aptabase::EventTracker;

app.track_event("app_started", None);
app.track_event("screen_view", Some(serde_json::json!({ "name": "Settings" })));
```

Call `flush_events_blocking()` before the app exits to make sure all events are sent.

### Track events (JavaScript)

```js
import { trackEvent } from "@aptabase/tauri";

trackEvent("save_settings");
trackEvent("screen_view", { name: "Settings" });
```

Guide: https://aptabase.com/for-tauri

## .NET MAUI

Package: `Aptabase.Maui (NuGet)`
Install: `dotnet add package Aptabase.Maui`
Repo: https://github.com/aptabase/aptabase-maui

### Initialization

In `MauiProgram.cs`:

```csharp
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseAptabase("<YOUR_APP_KEY>", new AptabaseOptions
        {
#if DEBUG
            IsDebugMode = true,
#else
            IsDebugMode = false,
#endif
        });
    // ...
}
```

### Track events

`UseAptabase` registers `IAptabaseClient` in the DI container. Inject it into your pages or view models:

```csharp
public partial class MainPage : ContentPage
{
    IAptabaseClient _aptabase;

    public MainPage(IAptabaseClient aptabase)
    {
        InitializeComponent();
        _aptabase = aptabase;
    }

    private void OnButtonClicked(object sender, EventArgs e)
    {
        _aptabase.TrackEvent("button_clicked");
        _aptabase.TrackEvent("screen_view", new() { { "name", "Settings" } });
    }
}
```

Guide: https://aptabase.com/for-maui

## Web apps (SPA)

Package: `@aptabase/web (~1 kB)`
Install: `npm add @aptabase/web`
Repo: https://github.com/aptabase/aptabase-js

Designed for Single-Page Applications. Each page reload starts a new session.

### Initialization

```js
import { init } from "@aptabase/web";

init("<YOUR_APP_KEY>");
```

Optional second parameter: `{ appVersion: "1.0.0" }`.

### Track events

```js
import { trackEvent } from "@aptabase/web";

trackEvent("app_started");
trackEvent("screen_view", { name: "Settings" });
```

Guide: https://aptabase.com/for-webapps

## React / Next.js

Package: `@aptabase/react (~1 kB)`
Install: `npm add @aptabase/react`
Repo: https://github.com/aptabase/aptabase-js

### Next.js App Router

Wrap your root layout:

```jsx
import { AptabaseProvider } from "@aptabase/react";

export default function RootLayout({ children }) {
  return (
    <AptabaseProvider appKey="<YOUR_APP_KEY>">
      <html lang="en">
        <body>{children}</body>
      </html>
    </AptabaseProvider>
  );
}
```

### Next.js Pages Router

Wrap in `_app`:

```jsx
import { AptabaseProvider } from "@aptabase/react";

export default function App({ Component, pageProps }) {
  return (
    <AptabaseProvider appKey="<YOUR_APP_KEY>">
      <Component {...pageProps} />
    </AptabaseProvider>
  );
}
```

### Track events

Use the `useAptabase` hook in any component:

```jsx
import { useAptabase } from "@aptabase/react";

function MyComponent() {
  const { trackEvent } = useAptabase();

  trackEvent("app_started");
  trackEvent("screen_view", { name: "Settings" });
}
```

Also works with Remix, CRA and Vite — wrap the root with `<AptabaseProvider>`.

Guide: https://aptabase.com/for-nextjs

## Angular

Package: `@aptabase/angular`
Install: `npm add @aptabase/angular`
Repo: https://github.com/aptabase/aptabase-js/blob/main/packages/angular/README.md

### Standalone API setup

```typescript
import { provideAptabaseAnalytics } from "@aptabase/angular";

export const appConfig: ApplicationConfig = {
  providers: [
    provideAptabaseAnalytics("<YOUR_APP_KEY>"),
  ],
};
```

### NgModules setup

```typescript
import { AptabaseAnalyticsModule } from "@aptabase/angular";

@NgModule({
  imports: [AptabaseAnalyticsModule.forRoot("<YOUR_APP_KEY>")],
})
export class AppModule {}
```

### Track events

Inject `AptabaseAnalyticsService` in your component:

```typescript
import { AptabaseAnalyticsService } from "@aptabase/angular";

@Component({ ... })
export class MyComponent {
  constructor(private _analyticsService: AptabaseAnalyticsService) {}

  onClick() {
    this._analyticsService.trackEvent("button_clicked");
    this._analyticsService.trackEvent("screen_view", { name: "Settings" });
  }
}
```

Guide: https://aptabase.com/for-angular

## Browser extensions

Package: `@aptabase/browser (~1 kB)`
Install: `npm add @aptabase/browser`
Repo: https://github.com/aptabase/aptabase-js

### Initialization

Initialize in your background script:

```js
import { init } from "@aptabase/browser";

init("<YOUR_APP_KEY>");
```

Optional second parameter: `{ isDebug: true }`. By default the SDK detects dev mode by checking whether the extension was installed from a store.

### Track events

```js
import { trackEvent } from "@aptabase/browser";

trackEvent("extension_installed");
trackEvent("popup_opened", { page: "settings" });
```

Guide: https://aptabase.com/for-browser-extensions

## Unity

Package: `Unity Package Manager (git URL)`
Install: `Package Manager → Add package from git URL: https://github.com/aptabase/aptabase-unity.git`
Repo: https://github.com/aptabase/aptabase-unity

### Configuration

Set your App Key in the settings asset at `Aptabase/Resources/AptabaseSettings.Asset`. Events are batched and sent every 60 seconds in production and every 2 seconds in development; override this via the `FlushInterval` field.

### Track events

```csharp
Aptabase.TrackEvent("app_started");
Aptabase.TrackEvent("screen_view", new Dictionary<string, object>
{
    { "name", "Settings" }
});
```

Manual flush: `Aptabase.Flush();`

Guide: https://aptabase.com/for-unity

## Unreal Engine

Package: `Plugin (C++ project)`
Install: `Clone https://github.com/aptabase/aptabase-unreal into your project's Plugins/ folder`
Repo: https://github.com/aptabase/aptabase-unreal

### Setup

Enable the plugin (Toolbar > Edit > Plugins > search "Aptabase" > Enable), then add to `Config/DefaultEngine.ini`:

```ini
[Analytics]
ProviderModuleName=Aptabase
```

Finally, set your App Key in Project Settings > Analytics > Aptabase.

### Track events (C++)

```cpp
TArray<FAnalyticsEventAttribute> Attributes;
Attributes.Emplace(TEXT("name"), TEXT("Settings"));

FAnalytics::Get().GetDefaultConfiguredProvider()->RecordEvent(TEXT("screen_view"), Attributes);
```

### Track events (Blueprints)

Use the "Record Event with Attributes" node. The Blueprint Analytics Plugin is recommended for provider-agnostic tracking.

Guide: https://aptabase.com/for-unreal

## Godot

Package: `addons/aptabase (autoload singleton)`
Install: `Copy addons/aptabase into your project and enable the plugin`
Repo: https://github.com/aptabase/aptabase-godot
Requires: Godot 4.2+

### Initialization and tracking

Copy the `addons/aptabase` folder into your project's `addons/` directory and enable the plugin under Project > Project Settings > Plugins. That registers an `Aptabase` autoload singleton:

```gdscript
func _ready() -> void:
    Aptabase.init("<YOUR_APP_KEY>", {"app_version": "1.2.3"})
    Aptabase.track("app_started")
    Aptabase.track("level_completed", {"level": 3, "score": 1200})
```

Options: `is_debug` (default: `OS.is_debug_build()`), `max_batch_size` (25), `flush_interval` (10s), `timeout` (30s). Events are batched and sent in the background; a failed request is logged and retried and never affects the game.

Guide: https://aptabase.com/for-godot

## Python

Package: `aptabase (PyPI)`
Install: `pip install aptabase`
Repo: https://github.com/aptabase/aptabase-python
Requires: Python 3.11+

### Initialization and tracking

The SDK is fully async, built with `httpx` and `asyncio`:

```python
import asyncio
from aptabase import Aptabase

async def main():
    async with Aptabase("<YOUR_APP_KEY>") as client:
        await client.track("app_started")
        await client.track("screen_view", {"name": "Settings"})

asyncio.run(main())
```

### Configuration options

```python
client = Aptabase(
    app_key="<YOUR_APP_KEY>",
    app_version="1.0.0",
    is_debug=False,
    max_batch_size=25,
    flush_interval=10.0,
    timeout=30.0
)
```

### Manual lifecycle

```python
client = Aptabase("<YOUR_APP_KEY>")
await client.start()
try:
    await client.track("event")
finally:
    await client.stop()
```

Guide: https://aptabase.com/for-python

## C++

Package: `CMake subdirectory`
Install: `add_subdirectory(path/to/aptabase-cpp)`
Repo: https://github.com/aptabase/aptabase-cpp

### CMake integration

Choose a networking backend:

```cmake
# Option A: cpp-httplib
set(CMAKE_APTABASE_USE_HTTPLIB ON)
add_subdirectory(path/to/aptabase-cpp)

# Option B: Boost.Asio
set(CMAKE_APTABASE_USE_BOOST ON)
add_subdirectory(path/to/aptabase-cpp)
```

### Initialization and tracking

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

int main() {
    Aptabase::Analytics aptabase(
        std::make_unique<Aptabase::HttplibHttpClient>(),
        "<YOUR_APP_KEY>",
        "https://your.aptabase.url",
        true // is_debug
    );

    aptabase.StartSession();
    aptabase.RecordEvent("app_started");
    aptabase.RecordEvent("screen_view", {{"name", "Settings"}});
    aptabase.EndSession();
}
```

Event attributes support `std::string`, `float` and `double`.

Guide: https://aptabase.com/for-cpp

## Optional

- [llms.txt](https://aptabase.com/llms.txt): Product facts, who it's for, full pricing table and the index of all SDKs
- [Documentation](https://aptabase.com/docs): Getting started, SDK catalogue, data collected (Markdown: https://aptabase.com/docs.md)
- [Pricing](https://aptabase.com/pricing): Free up to 20,000 events/month. Paid plans from $10/month for 200,000 events up to $450/month for 50,000,000 events. No overage fees. (Markdown: https://aptabase.com/pricing.md)
- [About](https://aptabase.com/about): What Aptabase is and who it's for (Markdown: https://aptabase.com/about.md)
- [MCP server](https://github.com/aptabase/aptabase-mcp): Query your Aptabase analytics from AI agents
- [Privacy Policy](https://aptabase.com/legal/privacy) · [Terms of Service](https://aptabase.com/legal/terms)