Android SDK (Kotlin)
The same guide ships with the package, so what you read here matches what you install.
One app key is enough for development and release. Signals marked as debug are kept apart as test data. How Test mode works
Privacy-first analytics for Android apps and games. No advertising ID, no device IDs, offline queue.
Docs: https://pulse.mightys.dev/docs/kotlin/
MightyS Pulse lets an Android app or game send named signals (events) with an optional number and a few properties, and see them in a dashboard. The SDK never reads an advertising id or any device identifier, uses no cookies and does no fingerprinting. It is written in Kotlin and works from Kotlin and Java.
Install
mavenCentral() is the only repository you need.
// build.gradle.kts (app module)
dependencies {
implementation("dev.mightys:pulse-android:0.9.5")
}// 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:
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() // nonblockingUsers are counted without any further setup. If you have your own user id, you can use it instead of the anonymous install id (optional):
Pulse.setUser("your-internal-user-id") // replaces the anonymous install id
Pulse.setUser(null) // back to the anonymous install idThe same from 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.
What is sent and what is never sent
Sent with every signal (the system object), and only values the device can give; anything unknown is left out:
| Group | Fields |
|---|---|
| Device | platform (mobile), deviceType (phone, tablet, tv, watch, car), deviceBrand (Build.MANUFACTURER), deviceModel, architecture, osName, osVersion, osApiLevel, isSimulator |
| Screen | screenWidth, screenHeight (dp), screenScale, screenWidthPx, screenHeightPx, screenDpi, screenCount, orientation |
| Settings and accessibility | colorScheme, layoutDirection, timeZone, utcOffsetMinutes, language, preferredLanguage, region, locale, fontScale, fontWeightAdjustment, boldText, reduceMotion, reduceTransparency, invertColors, increaseContrast, differentiateWithoutColor, connectionType (wifi, cellular, ethernet, none, other), lowPowerMode |
| App and install | appName, appVersion, appBuildNumber, bundleId, installSource (playstore, galaxystore, amazon, sideload, debug, other), isDebugBuild, sdkName, sdkVersion |
| Usage statistics | firstSessionDate, totalSessionsCount, distinctDaysUsed, distinctDaysUsedLastMonth, previousSessionSeconds, averageSessionSeconds, sessionSeconds, isNewInstall (first session after install only) |
Besides these, every signal carries your event name, optional number and properties, a UTC capture time, the debug flag
and a random session id. The signing certificate hash is sent only if you set sendAppIdentity = true. Reading the
connection type needs the ACCESS_NETWORK_STATE permission, which the library declares (a normal permission with no
prompt). The statistics are kept in one small file in the app's own storage next to the install id and are deleted with
it on opt-out.
Automatic signals: pulse.session_started (each new session), pulse.new_install (first launch after install) and
pulse.app_updated (first launch after the app version or build changed, with previousVersion and previousBuild).
Each is sent at most once per session, so they are rare. They respect opt-out and the debug flag like any signal.
Sessions use a random id that changes after 30 minutes of inactivity.
Anonymous install id: random, created by the SDK on first launch, stored only in the app's own storage
(noBackupFilesDir/mightys-pulse), deleted with the app and replaced after opt-out. It is sent only as a SHA-256 hash,
is not derived from any device identifier and is not shared between apps.
User id: optional. If you call setUser, the id is hashed with SHA-256 on the device and replaces the install id hash.
The raw id is never stored or sent. The hash is pseudonymous and can link one user's signals.
Never sent or read: advertising id, Android id, IMEI, serial number, device name, account names, location, contacts, installed apps. There are no cookies.
IP address: the SDK does not read or send the device's IP address as data. As with any HTTP request, the server sees the connection address, uses it only to derive a two-letter country code and does not store it.
Do not put personal data in event names, properties or the app version override.
Screen views
The SDK sends pulse.screen_view by itself, with no code from you. It records the simple class name of each Activity
when it is resumed, and the class name of each visible AndroidX fragment when your app uses androidx.fragment (apps
without it are unaffected). Props: screen (at most 128 characters) and previousScreen when there is one. Showing the
same screen again with no other screen in between sends nothing. Never sent: titles, text on the screen, anything the
user typed, intent extras or URLs.
For Compose destinations or your own navigation, record a screen by hand (Java: Pulse.screen("Settings");):
Pulse.screen("Settings")A name with a query or fragment loses them, and number or uuid-like path segments become :id. Manual calls respect
opt-out like any signal. To switch off the automatic capture (the hooks stay quiet and send nothing):
Pulse.initialize(this, "YOUR_APP_KEY", PulseOptions(automaticScreenViews = false))Options
import dev.mightys.pulse.PulseOptions
Pulse.initialize(this, "YOUR_APP_KEY", PulseOptions(
appVersion = "1.2.3",
debug = false,
sendAppIdentity = false,
))| Option | Default | Behaviour |
|---|---|---|
host |
https://in.mightys.dev |
HTTP(S) base URL without user info, query or fragment. An invalid host ignores initialization so it can be retried. HTTP is subject to Android cleartext policy. |
flushIntervalSeconds |
20 | Seconds between batches after the first. Clamped to 0.05 through 3600. |
maxBatchSize |
100 | Signals per request. 1 through 1000. |
maxQueueSize |
1000 | Signals kept offline. 1 through 10000. The oldest are dropped first. |
maxQueueAgeDays |
7 | Days a queued signal is kept. Capped at 29. |
gzip |
true | Compresses bodies larger than 1024 bytes. |
debug |
follows the build, see Test mode | Marks signals as test data and logs short diagnostics to Logcat, never signal contents. |
sendAppIdentity |
false | Adds the first signing certificate SHA-256 (the package name is always sent as bundleId). |
appVersion |
package version name | Overrides the app version. |
automaticScreenViews |
true | Sends pulse.screen_view when an Activity or AndroidX fragment is shown. False sends no automatic screen views. |
automaticSignals |
true | Sends pulse.session_started, pulse.new_install and pulse.app_updated. False sends none of them. |
Test mode. Every signal carries a test flag. By default it follows the build: debuggable builds (what Android Studio
runs) send test signals, release builds send real ones, with the same app key. Set debug = true or debug = false to
decide yourself. In the dashboard, the test mode switch chooses which of the two you are looking at.
Settings from the portal
Once per launch, in the background, the SDK reads your app's settings from <host>/api/v1/config using your app key and
keeps them in its own storage. In the portal you can switch off screen views, the automatic signals, individual automatic
signal types and groups of device fields (device, screen, settings, network, app, usage). A change applies from the next
launch of the app, never in the middle of a run, and no package update is needed. The package name and the base fields
(platform, OS, app version, device model, locale) are never removed.
Everything is on when the settings cannot be read (offline, an error, nothing saved yet). A code option can only
switch things off: automaticScreenViews = false or automaticSignals = false turn them off whatever the portal says,
while true (the default) follows the portal and never turns on what the portal switched off. Opting out
deletes the saved settings with the rest of the SDK's data.
Delivery and offline behaviour
- The first batch after
initializeis sent at once. Later batches follow the interval, the batch size, an explicit flush, or the last started Activity stopping. - Signals are saved to a checksummed file under
noBackupFilesDir/mightys-pulseand survive restarts. One process must own that directory; multiprocess writers are not supported. - Network errors and server errors (408, 425, 429, 5xx) are retried with exponential backoff from 1 second to 5 minutes.
Retry-Afteris honoured up to one hour. When the server asks for a pause or a different interval, the SDK follows it. A 401 keeps the queue and stops sending until the process restarts. - Each batch carries an id, so a batch sent again after a lost answer is stored only once.
- Delivery is at least once: after a crash a batch can be sent again. If Android ends the process abruptly, the last signals may be lost.
Pulse.flush()is nonblocking.Pulse.flush(callback)calls back on the SDK worker when the queue has drained, on opt-out, or when a 401 halts sending; move UI work to the main thread.Pulse.flush(timeoutMillis)is for background threads only and returns false at once on the main thread.- The transport uses
HttpURLConnectionwith no redirects, no HTTP cache and a fixedpulse-android/<version>User-Agent. It never sets or reads cookies.
Requirements
| Support | |
|---|---|
| Android | minimum SDK 21 (Android 5.0), compile SDK 36 |
| Language | Kotlin and Java, Java 11 language level |
| Permissions | INTERNET, declared in the library manifest and merged into your app |
| R8 / ProGuard | no consumer rules needed |
| Dependencies | pulse-core and the Kotlin standard library |
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.
Licence
MIT. See LICENSE.md. Each published artifact carries the licence text under META-INF/LICENSE-<module>.md.
Reference
Signal rules. Names need non-whitespace content and at most 200 UTF-16 units. Values must be finite. Props accept
String, Boolean (sent as "true" or "false"), Int, Long and finite Float or Double; other values are
dropped. At most 32 props are kept, with keys up to 128 and strings up to 1024 UTF-16 units, within 8192 bytes
serialized. Only the first 256 entries of the input map are copied, so put the props you want directly in the map.
Building from source. JDK 17, Android SDK platform and build tools 36, and the Gradle wrapper. Put your SDK path in
the ignored local.properties as sdk.dir=/path/to/Android/sdk.
./gradlew --no-daemon :pulse-core:test :pulse-android:testReleaseUnitTest :pulse-android:lintReleasesample is a small app that shows initialize, track, setUser, flush and opt-out. Pass your app key at build time:
./gradlew :sample:assembleDebug -PpulseAppKey=YOUR_KEY.