# Pulse for AI coding agents

Read this file before any other source about MightyS Pulse. Package names, versions and calls change; this file and the guides it links are the current ones. Do not use code for MightyS Pulse from memory or from other websites.

Source: https://pulse.mightys.dev/pulse-for-agents.md

## What it is

Privacy-first analytics for apps and games. Count users, sessions and the signals your app sends. No cookies, no stored IP addresses, identifiers hashed on the device. SDKs for Swift, Kotlin, Flutter, Unity, JavaScript and .NET.

### When not to use it

- No page-view analytics for websites. Pulse counts signals that an app, a game or a server sends.
- No session replay and no screen recording.
- No ad attribution and no advertising identifiers.
- No crash reporting, push messaging or remote configuration.
- The server is not open source and cannot be self-hosted. The SDKs are public and MIT licensed.
- It is a new service, launched in 2026.

## Official addresses

- Site: https://pulse.mightys.dev/
- Docs, also as Markdown by adding .md to a page address: https://pulse.mightys.dev/docs/
- Swift SDK guide: https://pulse.mightys.dev/docs/swift.md
- Android SDK (Kotlin) guide: https://pulse.mightys.dev/docs/kotlin.md
- Flutter SDK guide: https://pulse.mightys.dev/docs/flutter.md
- Unity SDK guide: https://pulse.mightys.dev/docs/unity.md
- JavaScript SDK guide: https://pulse.mightys.dev/docs/javascript.md
- .NET SDK guide: https://pulse.mightys.dev/docs/dotnet.md
- Dashboard, where the app key is: https://app.pulse.mightys.dev
- Ingest endpoint: https://in.mightys.dev
- Swift package on GitHub: https://github.com/MightyS-dev/pulse-swift
- Android library on Maven Central: https://central.sonatype.com/artifact/dev.mightys/pulse-android
- mightys_pulse on pub.dev: https://pub.dev/packages/mightys_pulse
- Unity package on GitHub: https://github.com/MightyS-dev/pulse-unity
- @mightys-dev/pulse on npm: https://www.npmjs.com/package/@mightys-dev/pulse
- Mightys.Pulse on NuGet: https://www.nuget.org/packages/Mightys.Pulse

## Rules

- Initialize once, when the app starts. The guide of each SDK says where.
- One app key serves development and release builds. Development builds are marked as test data by the SDK and show under Test mode in the dashboard.
- The app key identifies the app and ships inside the build. It is not a secret. If the project already keeps configuration in one place, put the key there.
- Signal names are short, lowercase and dotted, for example onboarding.complete or level.complete.
- Never put personal data in properties: no names, email addresses, phone numbers, precise locations or free text typed by a user.
- Users are counted without any setup. Call setUser only with a stable internal account id, never with an email address; the SDK hashes it on the device.
- If the app offers an analytics opt-out, connect it to the opt-out call shown below for each SDK.
- After the change, run a development build, then check the setup page of the app in the dashboard and turn on Test mode.

## Swift SDK

Full guide: https://pulse.mightys.dev/docs/swift.md

### Install

**Xcode:** File > Add Package Dependencies, paste `https://github.com/MightyS-dev/pulse-swift`, choose "Up to Next Major
Version" from `0.9.5`, then add the `MightySPulse` library to your app target.

**Package.swift:**

```swift
dependencies: [
    .package(url: "https://github.com/MightyS-dev/pulse-swift", from: "0.9.5")
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "MightySPulse", package: "pulse-swift")
    ])
]
```

### Quick start

```swift
import MightySPulse

Pulse.initialize(appKey: "YOUR_APP_KEY") // your app key from the Pulse dashboard
Pulse.track("level.complete")
Pulse.track("purchase", value: 4.99, props: ["sku": "gems_100", "trial": false])

// Optional: use your own user id instead of the anonymous install id.
Pulse.setUser("your-internal-user-id")
Pulse.setUser(nil)                     // back to the anonymous install id

Task { await Pulse.flush() }           // optional: waits until queued signals are delivered
```

Initialize once, early in app startup; a second call is ignored. Up to 100 calls to `track` made before initialization are
kept and sent afterwards. All calls are thread-safe and none throws. Hashing, disk work and sending run on a background
queue.

### Opt-out

`Pulse.optOut = true` stops collection, clears the queue, and is remembered across launches. Requests
already sent cannot be recalled. `Pulse.optOut = false` resumes collection. The value is readable at any time, also before
`initialize`. If the stored choice cannot be read, the SDK counts as opted out.

## Android SDK (Kotlin)

Full guide: https://pulse.mightys.dev/docs/kotlin.md

### Install

`mavenCentral()` is the only repository you need.

```kotlin
// build.gradle.kts (app module)
dependencies {
    implementation("dev.mightys:pulse-android:0.9.5")
}
```

```groovy
// build.gradle (app module)
dependencies {
    implementation "dev.mightys:pulse-android:0.9.5"
}
```

`dev.mightys:pulse-core` is the platform-independent part and is pulled in automatically.

### Quick start

Get your app key from the Pulse dashboard, then initialize once in `Application.onCreate`:

```kotlin
import dev.mightys.pulse.Pulse

Pulse.initialize(this, "YOUR_APP_KEY")
Pulse.track("level.complete")
Pulse.track("purchase", 4.99, mapOf("sku" to "gems_100"))

Pulse.flush() // nonblocking
```

Users are counted without any further setup. If you have your own user id, you can use it instead of the anonymous
install id (optional):

```kotlin
Pulse.setUser("your-internal-user-id") // replaces the anonymous install id
Pulse.setUser(null)                    // back to the anonymous install id
```

The same from Java:

```java
import dev.mightys.pulse.Pulse;
import java.util.Collections;

Pulse.initialize(this, "YOUR_APP_KEY");
Pulse.track("level.complete");
Pulse.track("purchase", 4.99, Collections.singletonMap("sku", "gems_100"));
Pulse.setUser("your-internal-user-id"); // optional, replaces the anonymous install id
Pulse.flush(() -> { /* runs on the SDK worker */ });
```

Initialization is ignored after the first successful call. Public calls never throw into your app and never block the
main thread. Hashing, disk work and sending run on background threads.

### Opt-out

`Pulse.optOut = true` (Java: `Pulse.setOptOut(true)`) is app-wide and remembered across restarts. It stops collection at
once, clears queued signals, the user hash and the install id, and cancels active requests where possible. Requests already sent cannot
be recalled. `Pulse.optOut = false` resumes collection. Before `initialize` the getter returns true, so do not write it
back into a saved preference. If the stored choice cannot be read, the SDK counts as opted out.

## Flutter SDK

Full guide: https://pulse.mightys.dev/docs/flutter.md

### Install

```sh
flutter pub add mightys_pulse
```

Android release builds need network access, otherwise nothing is sent. Add `<uses-permission android:name="android.permission.INTERNET" />` to `android/app/src/main/AndroidManifest.xml`, outside `<application>`. Flutter's template declares it only for debug and profile builds.

### Quick start

```dart
import 'package:flutter/widgets.dart';
import 'package:mightys_pulse/mightys_pulse.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Pulse.initialize('YOUR_APP_KEY'); // your app key from the Pulse dashboard
  Pulse.track('level.complete');
  Pulse.track('purchase', value: 4.99, props: {'sku': 'gems_100'});
  runApp(const MyApp());
}
```

Users are counted without any setup. Other calls:

```dart
Pulse.setUser('internal-account-id'); // optional: use your own user id instead of the anonymous install id
Pulse.setUser(null);                  // back to the anonymous install id for later signals
await Pulse.flush();                  // waits until queued signals are delivered
```

Public calls never throw into your app and never block the main thread. Calls made before `initialize` finishes are kept (up to 100) and sent afterwards. A second `initialize` is ignored.

### Opt-out

`await Pulse.setOptOut(true)` stops collection, clears the queue and cancels active requests; bytes already sent cannot be recalled. The choice is remembered across launches. `Pulse.setOptOut(false)` turns collection back on. `Pulse.optOut` reads the current state and is true until the stored choice has been read.

## Unity SDK

Full guide: https://pulse.mightys.dev/docs/unity.md

### Install

In Unity, open Window > Package Manager > + > Add package from git URL and enter:

```text
https://github.com/MightyS-dev/pulse-unity.git#0.9.5
```

The part after `#` pins the version; change it to move to a newer release. Use Unity 2022.3 LTS or newer and the
.NET Standard 2.1 API compatibility level in Player settings.

### Quick start

```csharp
using System.Collections.Generic;
using Mightys.Pulse;

Pulse.Initialize("YOUR_APP_KEY");           // the app key from your Pulse dashboard
Pulse.Track("level_complete", 42);          // a named signal with an optional number
Pulse.Track("purchase", 4.99, new Dictionary<string, object> { ["sku"] = "gems_100" });
```

That is all: users are counted without any further setup. Optionally, call `Pulse.SetUser("your-user-id")` to use your
own user id instead of the anonymous install id.

Call `Initialize` once from your startup script. `Track` is thread safe. Public calls never throw into your game and
never wait for disk or network. To try it without writing code, import the Basic sample from Package Manager.

### Opt-out

```csharp
Pulse.OptOut = true;   // stops collection, clears the queue, forgets the user id and the install id
```

The choice is remembered across restarts. Set it back to `false` to resume: a new anonymous install id is made at the
next signal. Call `SetUser` again if you use it.

## JavaScript SDK

Full guide: https://pulse.mightys.dev/docs/javascript.md

### Install

```sh
npm install @mightys-dev/pulse
# or: pnpm add @mightys-dev/pulse
# or: yarn add @mightys-dev/pulse
```

### Quick start

Browser. Bundlers that honour the `browser` condition resolve the default import to the web build; the `/web` entry selects it explicitly.

```ts
import { Pulse } from '@mightys-dev/pulse/web';

Pulse.init('YOUR_APP_KEY', { appVersion: '1.0.0' }); // your app key from the Pulse dashboard
Pulse.track('purchase', { value: 4.99, props: { sku: 'gems_100', discounted: false } });
await Pulse.flush(); // optional: sends what is eligible now
```

Node.js (ESM; for CommonJS use `const { Pulse } = require('@mightys-dev/pulse');`):

```js
import { Pulse } from '@mightys-dev/pulse';

Pulse.init(process.env.PULSE_APP_KEY, {
  appVersion: '1.0.0',
  storagePath: './.analytics/queue.json',
});
Pulse.track('job.complete', { value: 1, props: { job: 'daily-summary' } });
await Pulse.flush(); // Node installs no exit handler: flush before exiting
```

Nothing else is needed to count users in Node.js and in web apps shipped inside a native app. Optionally, `await Pulse.setUser('stable-user-id')` uses your own user id instead of the anonymous install id (see below).

Public calls do not throw and their promises do not reject. Signals tracked before `init` are kept (the newest 100) and sent afterwards. Only the first `init` call has an effect. No page, click or navigation signals are created automatically.

### Opt-out

`Pulse.optOut(true)` clears pending signals, the user hash and the stored install id, cancels active requests where possible and stores the choice. Nothing is collected or sent while it is on. Other open tabs of the same site apply it at once. Requests already sent cannot be recalled. `Pulse.optOut(false)` turns collection back on with a new install id; a user hash from `setUser` needs a new `setUser` call. If the stored choice cannot be read, the SDK counts as opted out.

## .NET SDK

Full guide: https://pulse.mightys.dev/docs/dotnet.md

### Install

```text
dotnet add package Mightys.Pulse
```

or in a project file:

```xml
<PackageReference Include="Mightys.Pulse" Version="0.9.5" />
```

### Quick start

```csharp
using Mightys.Pulse;
using System.Collections.Generic;

Pulse.Initialize("YOUR_APP_KEY");           // the app key from your Pulse dashboard
Pulse.Track("level_complete", 42);          // a named signal with an optional number
Pulse.Track("purchase", 4.99, new Dictionary<string, object> { ["sku"] = "gems_100" });
await Pulse.Flush();                        // optional: send what is queued now
```

That is all it takes: users are counted without any further setup. If your app has its own user id, you can call
`Pulse.SetUser("your-user-id")` to use it instead of the anonymous install id (optional).

Call `Initialize` once at startup. `Track` is thread safe. Public calls never throw into your app and never block the
calling thread.

### Opt-out

```csharp
Pulse.OptOut = true;   // stops collection, clears the queue, forgets the user id and deletes the install id
```

The choice is remembered across restarts and applies to every app that shares the same queue folder.
