This guide describes how the MotiSig Android SDK fits into your app at runtime. For module setup and Firebase, see the Android overview. For keys and URLs, see Configuration.

Overview

Call MotiSig.initialize(...) once at process start, typically in your Application.onCreate().
Register MotiSigFirebaseMessagingService (or a subclass) in AndroidManifest.xml so FCM token refresh and incoming messages are forwarded to the SDK.
When you know the signed-in user, call MotiSig.getInstance().setUser(id). This registers the user with the MotiSig API and, when an FCM token is available, upserts the push subscription for that user.
Forward Activity intents that came from a notification tap to MotiSig.getInstance().handleNotificationIntent(intent) so click tracking fires.
Use MotiSig.getInstance() for profile updates, tags, attributes, events, and notification listeners as needed.

Lifecycle

flowchart LR
  init[MotiSig.initialize]
  setUser[setUser]
  mutations[tags / attrs / events / ping]
  push[push subscription upsert]
  init --> setUser
  setUser --> mutations
  setUser --> push

After initialize, the SDK installs an Application.ActivityLifecycleCallbacks to:

Patch permission on the push subscription when the user toggles notifications in OS settings and returns to the app.
Send a foreground heartbeat ping every pingIntervalSeconds (default 60 s, clamped to 1…86400).

If Firebase Messaging is on the classpath, the SDK also pulls the current FCM token at init time and registers it as soon as a user is set.

User-scoped HTTP mutations (setUser, tags, attributes, updateUser, ping, triggerEvent, push subscription upsert/patch/remove) run on an internal FIFO queue (FIFOMutationQueue). Each queued item captures the user id (and token where applicable) at enqueue time, so work is not dropped if logout() clears storage before a request runs. See User and profile for logout details.

Manifest snippet

<service
    android:name="ai.motisig.sdk.MotiSigFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

If you already have your own FirebaseMessagingService, subclass MotiSigFirebaseMessagingService and chain super.onNewToken / super.onMessageReceived.

Application initialization

class MotiSigExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        if (!MotiSig.initialize(
                context = this,
                sdkKey = BuildConfig.MOTISIG_SDK_KEY,
                projectId = BuildConfig.MOTISIG_PROJECT_ID,
                // baseURL = URL("https://api.motisig.ai/client"),
                logLevel = LogLevel.INFO,
            )
        ) {
            return
        }
    }
}

Activity intent forwarding

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    MotiSig.getInstance().handleNotificationIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    MotiSig.getInstance().handleNotificationIntent(intent)
}

handleNotificationIntent extracts title, body, and the rest of the FCM data extras and dispatches a tap event (openedFromTap = true), which triggers click tracking when messageId and a current user are present.

Next steps

Configuration — keys, base URL, log levels, ping interval
User and profile — setUser, updateUser, logout
Events, tags, attributes — events, tags, attributes, ping
Push notifications — listeners, payloads, delivered notifications
Rich notification images — banner image rendering

Getting started