Onlo Mobile SDK for Android

Before you start

• Android API 24 or newer
• Compile SDK 35, Java 17, and a Kotlin 2.0-compatible project
• An Onlo workspace where you can open WebChat → Install

Quick start

Start anonymously even if your app has accounts. This proves the package, public key, network path, Messenger UI, and Inbox delivery before identity or push adds more moving parts.

1. Step 1

   Create an Android Mobile SDK key

   In Onlo, open WebChat → Install → Mobile app, choose Android, and select Generate key. Copy the public SDK key. It identifies this integration and is safe in app configuration; it is not the customer identity secret.

   Expected resultOnlo shows an active Android SDK key and the released package version.

2. Step 2

   Install the released package

   Add the package exactly once. Wrapper apps must not install the iOS or Android core separately.

   Install Android SDK 0.3.2kotlin

   Copy

   // app/build.gradle.kts
   dependencies {
       implementation("ai.onlo:onlo-android-sdk:0.3.2")
   }

   Expected resultThe Android project resolves the Onlo import and builds.

3. Step 3

   Initialize, start an anonymous session, and open Messenger

   Initialize once during app startup. Start the customer session before the Support control calls present. Replace the example key with the public key copied from Onlo.

   Android · first working integrationkotlin

   Copy

   import ai.onlo.sdk.Onlo // ai.onlo:onlo-android-sdk:0.3.2
   import ai.onlo.sdk.messenger.OnloMessenger
   import androidx.lifecycle.lifecycleScope
   import kotlinx.coroutines.launch
   
   val onlo = Onlo.initialize(
       applicationContext,
       sdkKey = "onlo_public_sdk_key_from_dashboard",
   )
   
   supportButton.isEnabled = false
   lifecycleScope.launch {
       onlo.loginUnidentifiedUser()
       supportButton.isEnabled = true
   }
   
   supportButton.setOnClickListener {
       OnloMessenger.present(this, onlo)
   }

   Expected resultTap Support and the native Onlo Messenger opens with a message composer.

4. Step 4

   Prove the complete message path

   On the phone, send “Where is order #5832?”. Open Onlo Inbox and reply “Your order shipped this morning.” Return to WebChat → Install → Mobile app and refresh the SDK status.

   Expected resultThe conversation appears in Inbox, the reply appears in Messenger, and the target shows Connected with a recent Last seen time.

Identity verification

Do this only if customers already sign in to your app. Identity keeps conversations attached to the same customer across devices and app reinstalls. Anonymous apps can skip this section.

1. Step 1

   Generate the identity secret in Onlo

   Open WebChat → Install → Mobile app → Android → Identity verification and select Generate secret. Copy it directly into your backend secret manager. Never put this secret in the app, source code, build configuration, logs, or analytics.

   Expected resultOnly your authenticated backend can read the identity secret.

2. Step 2

   Mint a short-lived customer JWT on your backend

   Authenticate the app request first. Sign HS256 with the Onlo identity secret, use onlo-messenger as the audience, use your stable customer ID as sub, and expire the token within five minutes.

   Node.js backend · create userJwttypescript

   Return userJwt to the authenticated customer. Never return ONLO_MOBILE_IDENTITY_SECRET.

   Copy

   import {SignJWT} from 'jose';
   
   // Run on your backend after authenticating the app customer.
   const secret = new TextEncoder().encode(
     process.env.ONLO_MOBILE_IDENTITY_SECRET,
   );
   
   const userJwt = await new SignJWT({
     name: 'Alex Morgan',
     email: 'alex@example.com',
     customAttributes: {plan: 'pro'},
   })
     .setProtectedHeader({alg: 'HS256'})
     .setSubject('customer_12345')
     .setAudience('onlo-messenger')
     .setIssuedAt()
     .setExpirationTime('5m')
     .sign(secret);

   Expected resultThe app receives a fresh userJwt for customer_12345, not the signing secret.

3. Step 3

   Identify the customer and clear Onlo on logout

   Pass the fresh JWT straight to Onlo after your app signs in. Before your app switches accounts or finishes logout, wait for Onlo logout to complete.

   Android · login and logoutkotlin

   Copy

   fun connectSignedInCustomer(userJwt: String) = lifecycleScope.launch {
       onlo.loginIdentifiedUser(userJwt)
   }
   
   fun disconnectCustomer() = lifecycleScope.launch {
       supportButton.isEnabled = false
       onlo.logout()
   }

   Expected resultOnlo Inbox shows Alex Morgan instead of an anonymous installation, and the next app account cannot inherit that conversation.

Push notifications

Push is optional. Add it after chat works so customers receive reply alerts while the app is in the background or terminated. Onlo should not show a system alert while the customer is already reading that conversation.

Before this section, you need a Google account, a Firebase project, permission to register an Android app and generate a service-account private key, and a physical Android device or Google Play-enabled emulator. Firebase Cloud Messaging is free. You do not need a signing certificate for FCM.

1. Step 1

   Create a Firebase project and register the Android app

   Sign in to Firebase Console. Select Add project if you do not have one. Open Project overview → Add app → Android. In app/build.gradle or app/build.gradle.kts, copy the applicationId, for example com.example.store, into Android package name, then select Register app.

   Open Firebase ConsoleCreate or select the project that will send Android notifications.Firebase: Add Firebase to your Android projectFollow Firebase’s official Android registration guide.

   Expected resultFirebase shows an Android app whose package name exactly matches the installed app applicationId.

2. Step 2

   Add Firebase Messaging to the app

   On the Firebase setup screen, download google-services.json and move it to app/google-services.json. Add the Google services plugin and Firebase Messaging below, then sync Gradle. The Firebase project, JSON file, and installed application ID must all match.

   Firebase · Gradle Kotlin DSLkotlin

   Keep environment-specific google-services.json files out of public source control.

   Copy

   // Root build.gradle.kts
   plugins {
       id("com.google.gms.google-services") version "4.5.0" apply false
   }
   
   // app/build.gradle.kts
   plugins {
       id("com.google.gms.google-services")
   }
   
   dependencies {
       implementation(platform("com.google.firebase:firebase-bom:34.16.0"))
       implementation("com.google.firebase:firebase-messaging")
   }

   AndroidManifest.xmlxml

   On Android 13+, request notification permission only after a clear customer action.

   Copy

   <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
   
   <application ...>
       <service
           android:name=".OnloFirebaseMessagingService"
           android:exported="false">
           <intent-filter>
               <action android:name="com.google.firebase.MESSAGING_EVENT" />
           </intent-filter>
       </service>
   </application>

   Expected resultGradle sync succeeds, FirebaseMessaging resolves, and the app can ask Firebase for an FCM registration token.

3. Step 3

   Give Onlo permission to send through FCM

   In Firebase, open Project settings → Service accounts and generate a private key. In Onlo, open WebChat → Install → Mobile app → Android → Push notifications, enter the application ID, upload the complete service-account JSON, and select Save FCM. Upload this file only to Onlo—never bundle it in the app or commit it to Git.

   Firebase: Generate a service-account keyUse Firebase’s official server-credential instructions.

   Expected resultOnlo shows FCM ready for com.example.store.

4. Step 4

   Tell Onlo where this device can receive notifications

   Ask for notification permission from a clear customer action. After the Onlo customer session is ready, forward the current provider token and every later token rotation. Forward Onlo payloads when the customer taps a notification.

   Android · token and notification tapkotlin

   Copy

   import android.app.Activity
   import ai.onlo.sdk.Onlo
   import ai.onlo.sdk.messenger.OnloMessenger
   import ai.onlo.sdk.protocol.PushProvider
   import ai.onlo.sdk.push.PushPayloadOutcome
   import androidx.lifecycle.lifecycleScope
   import com.google.firebase.messaging.FirebaseMessaging
   import com.google.firebase.messaging.FirebaseMessagingService
   import kotlinx.coroutines.CoroutineScope
   import kotlinx.coroutines.Dispatchers
   import kotlinx.coroutines.SupervisorJob
   import kotlinx.coroutines.launch
   
   class OnloFirebaseMessagingService : FirebaseMessagingService() {
       private val serviceScope =
           CoroutineScope(SupervisorJob() + Dispatchers.IO)
   
       override fun onNewToken(token: String) {
           serviceScope.launch {
               Onlo.instance().registerPushToken(PushProvider.FCM, token)
           }
       }
   }
   
   // Run from the Activity after anonymous or identified login succeeds.
   FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
       lifecycleScope.launch {
           Onlo.instance().registerPushToken(PushProvider.FCM, token)
       }
   }
   
   suspend fun handleOnloNotificationTap(
       activity: Activity,
       payload: Map<String, String>,
   ) {
       when (val result = Onlo.instance().handlePushPayload(payload)) {
           is PushPayloadOutcome.NavigationIntent ->
               OnloMessenger.openConversation(activity, result.conversationId)
           else -> Unit
       }
   }

   Expected resultThe current device appears under registered installations in the Onlo push status.

5. Step 5

   Test the provider, then test a real reply

   First use Send to selected installation. Then send a customer message, background or close the app, and reply from Inbox. Test the real reply path because the provider test and conversation delivery are separate server paths.

   Expected resultThe selected-device test arrives, the real Inbox reply arrives while the app is backgrounded or closed, and tapping it opens the intended conversation.

Error codes

Use the stable code to decide what the app should do. Show customers a plain Support-unavailable message; record only the code, SDK version, platform, time, and request ID. Never log customer JWTs, push tokens, messages, Firebase credentials, or APNs keys.

Versions

These snippets target the latest public release, 0.3.2. Upgrade the package before debugging a client-version error. Onlo publishes a migration guide only when a release changes an installation step or public API.

The 0.3.2 Android AAR is 875,450 bytes (about 855 KiB). Measure your release APK or AAB because shared dependencies and shrinking change the final increase.

• Android API 24+
• Compile SDK 35
• Java 17
• Kotlin 2.0-compatible host