Install the Userorbit SDK in an Android app

Add the Userorbit SDK to your Android app from JitPack, call setup in your Application class, and identify people after they sign in. When you're done, Userorbit receives your app's events and screens, and surveys created in Userorbit can appear in the app.

Before you begin

You need:

an app with minSdk 23 or higher
Jetpack Compose and activities that extend ComponentActivity, if you want the built-in surveys, announcements, feedback and messenger screens
the public Account ID from the install snippet in Settings → Channels → Widget
a stable user ID from your own system for signed-in people

The Account ID is safe to ship in your app. Keep API keys and signing secrets on your server.

1. Add the dependency

Add the JitPack repository in settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}
kotlin

Then add the SDK to your app module's build.gradle.kts:

dependencies {
    implementation("com.github.userorbit.userorbit-android:userorbit-android:0.1.0")
    implementation("com.github.userorbit.userorbit-android:userorbit-android-ui:0.1.0")
}
kotlin

Artifact	Contains
`userorbit-android`	Analytics, identity, sessions, the offline queue and the data methods for every feature. It includes the core module, so you don't add that separately.
`userorbit-android-ui`	The built-in Compose screens for surveys, announcements, feedback and the messenger. Leave it out if you'll build your own interface.

The SDK ships consumer ProGuard rules, so you don't need to add keep rules for release builds.

2. Set up the SDK in your Application class

import android.app.Application
import com.userorbit.UserorbitConfig
import com.userorbit.android.UserorbitAndroid
import com.userorbit.android.ui.UserorbitUI

class AcmeApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        UserorbitAndroid.setup(this, UserorbitConfig(accountId = "YOUR_ACCOUNT_ID"))
        UserorbitUI.install(this)
    }
}
kotlin

Register the class in AndroidManifest.xml with android:name=".AcmeApplication" if your app doesn't already have one. Replace YOUR_ACCOUNT_ID with the Account ID from your workspace.

UserorbitUI.install lets surveys appear over your activities. Skip it if you didn't add userorbit-android-ui.

Setup starts session tracking and records Application Installed, Application Updated, Application Opened and Application Backgrounded. To turn lifecycle events off, pass captureApplicationLifecycleEvents = false.

3. Track screens and events

Call screen when a screen appears. Screen views send $uo_screen_view, which is also the event Userorbit uses to confirm your installation.

@Composable
fun ProjectsScreen() {
    LaunchedEffect(Unit) { Userorbit.shared.screen("Projects") }
    // ...
}
kotlin

Track product events after the action succeeds:

Userorbit.shared.track("Project Created", mapOf("template" to "blank"))
kotlin

Event names are case-sensitive. A survey that triggers on Project Created won't respond to project_created.

4. Identify signed-in people

Call identify after your app knows who is signed in. Use an immutable ID from your system, not an email address.

Userorbit.shared.identify(
    user.id,
    email = user.email,
    name = user.name,
    attributes = mapOf("plan" to user.plan, "role" to user.role),
)
kotlin

Identifying links the person's earlier anonymous events to their profile and creates or updates their contact in Userorbit. Send email and name only when your privacy basis allows it.

To update attributes later, call setUserProperties or unsetUserProperties. These only work after identify. To attach a property to every event from this device, call register, and remove it with unregister.

5. Reset on sign-out

Userorbit.shared.reset()
kotlin

Reset starts a new anonymous identity, ends the session, clears registered properties and forgets the person's support conversations on this device. Without it, the next person who signs in on the same device inherits the previous person's identity.

6. Verify the installation

Run the app and open a screen that calls screen.
Send the app to the background, or call Userorbit.shared.flush(). Events are otherwise sent every 30 seconds or once 20 are queued.
In Userorbit, open Settings → Channels → Widget. Select Check again if needed. The verification step shows SDK activity detected and the time of the last SDK activity.
Open Live Events and confirm the $uo_screen_view event shows the expected screen name and user.

If nothing arrives, set debug = true in UserorbitConfig and filter Logcat for [Userorbit]. To send SDK logs to your own logger, assign UserorbitLog.writer. See Troubleshoot the Userorbit mobile SDKs for common causes.

Configuration options

Option	Default	Purpose
`accountId`	Required	Your workspace's public Account ID.
`apiHost`	`https://api.userorbit.com`	Change only if your workspace uses a different API host.
`flushAt`	20	Number of queued events that triggers a send.
`flushIntervalSeconds`	30	How often queued events are sent.
`maxBatchSize`	50	Maximum events per request.
`maxQueueSize`	1000	Maximum stored events. The oldest are dropped beyond this.
`captureApplicationLifecycleEvents`	`true`	Records install, update, open and background events.
`surveys`	`true`	Set to `false` to stop surveys from loading.
`optOut`	`false`	Start opted out until the person gives consent.
`debug`	`false`	Logs SDK activity.
`beforeSend`	None	Edit an event, or return `null` to drop it, before it's queued.