Flutter integration guide

How to embed the Aarambh SDK in a Flutter app via flutter-plugin/ (aarambh_sdk). The package is a thin pass-through — every Dart method forwards to com.aarambh.sdk.AarambhSDK over a single MethodChannel. No business logic lives in the Flutter or Kotlin layers.

Acquiring a session

Before your app calls login(), your own backend registers the agent and acquires a session token by calling two endpoints on the LSP DMS Gateway. These are server-to-server calls, made from your backend and never from the mobile app. The full request / response reference, including authentication, lives in the API integration guide:

POST /v1/agent/create — registers the agent against your subscriber account and returns its userCode. Run it once per agent.
POST /v1/agent/acquireSession — returns a session token for that userCode. Call it whenever your app needs a fresh authToken for the SDK (e.g. on each login, not just once at registration).

Map the acquireSession response straight onto AarambhSdk.login(): data.token → authToken, data.currentUser → userDetails, data.agentDetails → agentDetails (agentDetails needs aarambh_sdk v0.1.6+ — see API reference below). Call login() and wait for it to complete before calling launch() — see the call-order warning below the API reference table.

Installation

The Flutter package is mirrored, read-only, to a dedicated repo (aarambh-cloud/aarambh-sdk-flutter) on every release — not published to pub.dev, since pub.dev has no private-package option. Add it as a git dependency in your pubspec.yaml:

pubspec.yaml

dependencies:
  aarambh_sdk:
    git:
      url: https://github.com/aarambh-cloud/aarambh-sdk-flutter.git
      ref: v0.1.9 # tag, branch, or commit SHA — ask your integration contact for the latest

Then flutter pub get. The consuming machine needs its own git credentials for this repo (SSH key or HTTPS PAT with read access), since it's private.

Authenticating the native dependency

The native Android module also depends on com.aarambh.external:sdk, published to GitHub Packages (Maven) — GitHub Packages requires authentication for reads too, even though the repo itself is source-visible to the org. Add a Maven repository with a GitHub PAT (read:packages scope) to your Flutter app's top-level android/build.gradle(.kts):

android/build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.pkg.github.com/aarambh-cloud/aarambh-sdk-android'
            credentials {
                username = <your-github-username>
                password = <PAT-with-read:packages-scope>
            }
        }
    }
}

Prefer pulling the username/password from ~/.gradle/gradle.properties or environment variables rather than hardcoding the PAT in the file.

API reference — `AarambhSdk`

flutter-plugin exposes the same full surface as the native dummy app's MainActivity.kt — every public method on native AarambhSDK has a matching MethodChannel case and Dart method, split into two groups.

Pass-through / dispatch methods

Return Future<void>, resolve with null on success, throw PlatformException on failure (e.g. launch() called with no attached Activity throws code NO_ACTIVITY).

Dart method	Native call	Notes
`initialize(config)`	`AarambhSDK.initialize()`	Call once at startup, before any other call. See config keys below.
`login({authToken, userDetails, agentDetails})`	`AarambhSDK.login()`	Hands over an existing session instead of driving the SDK's own OTP flow. Only `authToken` is required. `agentDetails` (v0.1.6+) is optional and distinct from `userDetails` — omitting it falls back to `agentDetails = userDetails`. Must be called before `launch()` for the initial handoff — see the call-order warning below.
`launch()`	`AarambhSDK.launch(activity)`	Starts `SDKActivity`. Throws `NO_ACTIVITY` with no attached Flutter `Activity`.
`close()`	`AarambhSDK.close()`	Finishes the currently active `SDKActivity`, if any.
`requestPermissions()` (optional)	`AarambhSDK.requestPermissions()`	Not required — only call this if you'd rather not build your own runtime permission flow (location, battery optimisation, notifications, camera). Triggers the SDK's own step-by-step permission UI instead. Starts `SDKActivity` if it isn't already running.

`initialize()` config keys

dart

await AarambhSdk.initialize({
  'environment': 'sandbox',   // 'sandbox' | 'live' — defaults to 'live' if omitted
  'subscriberId': 'my-subscriber-id',
  'appname': 'My Flutter Host App',
  // optional branding:
  // 'vendorCode': '...',
  // 'clientLogo': '...',
  // 'privacy': 'https://...',
  // 'terms': 'https://...',
  // 'overlayIconUrl': 'https://.../icon.png',
});

clientUri/sseUri are not accepted from the host app — resolved internally from environment, always overwriting anything passed under those keys. environment defaults to live if omitted, so a forgetful integration fails safe to production rather than silently landing on sandbox.
overlayIconUrl needs more than just being present in this config to actually show up — it only reaches the native overlay bubble once the SDK's UI reaches its home screen with a backend-accepted session (a fake/expired token that gets rejected never gets there). It's then fetched and cached lazily the first time the bubble is shown.

login() call order for an initial handoff

login() always stashes the token/details into native's in-memory config synchronously — but that only reaches the WebView reliably one way: main.ts reads it once via SdkBridge.getConfig(), before Angular bootstraps inside a freshly started SDKActivity. Call login() and await it, then call launch(), and this happens automatically with no race.

Calling login() after launch() instead falls into the live-dispatch path above — silently dropped unless SDKActivity's bridge has already attached, which is unlikely if there's no human-scale delay between the two calls. The symptom looks exactly like the token was never set: the app finds no usable session and falls back to its own OTP login screen. (Calling login() again after SDKActivity is already visible is the supported way to switch sessions live, without a launch()/close() round-trip — that's what live dispatch is actually for.)

Usage example

main.dart

import 'package:aarambh_sdk/aarambh_sdk.dart';
import 'package:flutter/services.dart';

Future<void> setupAarambhSdk() async {
  // Call once at startup — BEFORE login()/launch()/any other call.
  // Values are only read when SDKActivity starts up.
  await AarambhSdk.initialize({
    'environment': 'sandbox',
    'subscriberId': 'my-subscriber-id',
    'appname': 'My Flutter Host App',
  });
}

Future<void> loginAndOpenSdkUi(String authToken, Map<String, dynamic>? userDetails, Map<String, dynamic>? agentDetails) async {
  // Your own backend already returned this authToken (e.g. from acquire_session -
  // see "Acquiring a session" above). login() MUST complete before launch() - calling
  // them the other way round routes through live dispatch instead, which silently
  // drops the call unless SDKActivity's bridge has already attached. userDetails and
  // agentDetails are both optional; only authToken is required.
  await AarambhSdk.login(authToken: authToken, userDetails: userDetails, agentDetails: agentDetails);

  try {
    await AarambhSdk.launch(); // starts the visible SDKActivity
  } on PlatformException catch (e) {
    if (e.code == 'NO_ACTIVITY') {
      // launch() needs a widget/screen context, not a background isolate.
    }
    rethrow;
  }
}

React Native integration guide

How to embed the Aarambh SDK in a React Native app via react-native-plugin/ (@aarambh-cloud/react-native-sdk). The package is a thin pass-through — every JS method forwards to com.aarambh.sdk.AarambhSDK over React Native's own Android bridge. No business logic lives in the JS or Java layers.

Acquiring a session

Before your app calls login(), your own backend registers the agent and acquires a session token by calling two endpoints on the LSP DMS Gateway. These are server-to-server calls, made from your backend and never from the mobile app. The full request / response reference, including authentication, lives in the API integration guide:

POST /v1/agent/create — registers the agent against your subscriber account and returns its userCode. Run it once per agent.
POST /v1/agent/acquireSession — returns a session token for that userCode. Call it whenever your app needs a fresh authToken for the SDK (e.g. on each login, not just once at registration).

Map the acquireSession response straight onto AarambhSdk.login(): data.token → authToken, data.currentUser → userDetails, data.agentDetails → agentDetails (agentDetails needs @aarambh-cloud/react-native-sdk 0.1.6+ — see API reference below). Call login() and await it before calling launch() — see the call-order warning below the API reference table.

Installation

The React Native package is mirrored, read-only, to a dedicated repo (aarambh-cloud/aarambh-sdk-react-native) on every release — clients are given access to that repo only, not the internal monorepo the SDK is built from. Add it as a git dependency in your package.json:

package.json

"dependencies": {
  "@aarambh-cloud/react-native-sdk": "github:aarambh-cloud/aarambh-sdk-react-native#v0.1.7"
}

Then npm install. The consuming machine needs its own git credentials for this repo (SSH key or HTTPS PAT with read access — ask your integration contact for the latest tag), since it's private.

Register the native package explicitly in your app's MainApplication — this package ships no react-native.config.js, so autolinking won't discover it:

MainApplication.java

import com.aarambh.sdk.reactnative.AarambhSdkPackage;

// inside getPackages():
List<ReactPackage> packages = new PackageList(this).getPackages();
packages.add(new AarambhSdkPackage());
return packages;

Authenticating the native dependency

The native Android module also depends on com.aarambh.external:sdk, published to the same GitHub Packages Maven registry. Add a Maven repository with a GitHub PAT (read:packages scope) to your app's top-level android/build.gradle(.kts):

android/build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.pkg.github.com/aarambh-cloud/aarambh-sdk-android'
            credentials {
                username = <your-github-username>
                password = <PAT-with-read:packages-scope>
            }
        }
    }
}

Prefer pulling the username/password from ~/.gradle/gradle.properties or environment variables rather than hardcoding the PAT in the file.

API reference — `AarambhSdk`

Every method returns a Promise, resolves with null on success, and rejects on failure (e.g. launch() called with no attached Activity rejects with code NO_ACTIVITY).

JS method	Native call	Notes
`initialize(config)`	`AarambhSDK.initialize()`	Call once at startup, before any other call. See config keys below.
`login({ authToken, userDetails, agentDetails })`	`AarambhSDK.login()`	Hands over a session your app already has — the SDK skips its own OTP UI and routes straight to home. Only `authToken` is required. `agentDetails` (0.1.6+) is optional and distinct from `userDetails` — omitting it falls back to `agentDetails = userDetails`. Must be called before `launch()` for the initial handoff — see the call-order warning below.
`launch()`	`AarambhSDK.launch(activity)`	Starts `SDKActivity`. Rejects with `NO_ACTIVITY` if there's no current Activity.
`close()`	`AarambhSDK.close()`	Finishes the currently active `SDKActivity`, if any.

`initialize()` config keys

Same config shape as every other platform — see the Flutter tab's config-keys section for the full key list and behavior notes (environment, subscriberId, clientLogo, overlayIconUrl, and so on all apply here unchanged).

javascript

await AarambhSdk.initialize({
  environment: 'sandbox',   // 'sandbox' | 'live' — defaults to 'live' if omitted
  subscriberId: 'my-subscriber-id',
  appname: 'My React Native Host App',
});

login() call order for an initial handoff

login() always stashes the token/details into native's in-memory config synchronously — but that only reaches the WebView reliably one way: main.ts reads it once via SdkBridge.getConfig(), before Angular bootstraps inside a freshly started SDKActivity. Call login() and await it, then call launch(), and this happens automatically with no race.

Calling login() after launch() instead falls into the live-dispatch path above — silently dropped unless SDKActivity's bridge has already attached, which is unlikely if there's no human-scale delay between the two calls. The symptom looks exactly like the token was never set: the app finds no usable session and falls back to its own OTP login screen. (Calling login() again after SDKActivity is already visible is the supported way to switch sessions live, without a launch()/close() round-trip — that's what live dispatch is actually for.)

Usage example

App.js

import { AarambhSdk } from '@aarambh-cloud/react-native-sdk';

async function setupAarambhSdk() {
  // Call once at startup — BEFORE login()/launch()/any other call.
  await AarambhSdk.initialize({
    environment: 'sandbox',
    subscriberId: 'my-subscriber-id',
    appname: 'My React Native Host App',
  });
}

async function loginAndOpenSdkUi(authToken, userDetails, agentDetails) {
  // Your own backend already returned this authToken (e.g. from acquire_session -
  // see "Acquiring a session" above). login() MUST complete before launch() - calling
  // them the other way round routes through live dispatch instead, which silently
  // drops the call unless SDKActivity's bridge has already attached. userDetails and
  // agentDetails are both optional; only authToken is required.
  await AarambhSdk.login({ authToken, userDetails, agentDetails });

  try {
    await AarambhSdk.launch(); // starts the visible SDKActivity
  } catch (e) {
    if (e.code === 'NO_ACTIVITY') {
      // launch() needs a current Activity - make sure this runs from a
      // screen that's actually mounted, not a background task.
    }
    throw e;
  }
}

async function closeSdkUi() {
  await AarambhSdk.close();
}

Native Android integration guide

How to embed the Aarambh SDK in a native Android app (Kotlin or Java) using the com.aarambh.external:sdk AAR directly. There's no wrapper layer here: your app calls com.aarambh.sdk.AarambhSDK itself, which is the same class the Flutter and React Native packages forward to.

Acquiring a session

Before your app calls login(), your own backend registers the agent and acquires a session token by calling two endpoints on the LSP DMS Gateway. These are server-to-server calls, made from your backend and never from the mobile app. The full request / response reference, including authentication, lives in the API integration guide:

POST /v1/agent/create — registers the agent against your subscriber account and returns its userCode. Run it once per agent.
POST /v1/agent/acquireSession — returns a session token for that userCode. Call it whenever your app needs a fresh authToken for the SDK (e.g. on each login, not just once at registration).

Map the acquireSession response straight onto AarambhSDK.login(): data.token → authToken, data.currentUser → userDetails, data.agentDetails → agentDetails. Call login() before launch() — see the call-order warning below the API reference table.

Installation

Requirements: minSdk 26 or higher, compileSdk 36, and JDK 21 for the build (the SDK's Capacitor dependencies are compiled to Java 21 bytecode).

1. Add the GitHub Packages repository

The AAR is published to a private GitHub Packages Maven registry, which requires authentication even for reads. Add the repository with a GitHub PAT (read:packages scope) to your settings.gradle(.kts):

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/aarambh-cloud/aarambh-sdk-android")
            credentials {
                username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
                password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

Put gpr.user/gpr.key in ~/.gradle/gradle.properties (or set the environment variables on CI) rather than hardcoding the PAT. If your project still declares repositories in the top-level build.gradle under allprojects { repositories { … } }, add the same maven { … } block there instead.

2. Add the dependency

app/build.gradle.kts

dependencies {
    implementation("com.aarambh.external:sdk:0.1.12") // ask your integration contact for the latest version
}

The SDK brings in its own transitive dependencies (Capacitor runtime and plugins, all published under com.aarambh.external in the same registry), so nothing else needs to be added by hand.

3. What gets merged into your manifest

You don't need to declare any SDK components yourself. Manifest merging adds SDKActivity, the overlay/location foreground services, the SDK's FirebaseMessagingService, and the location, foreground-service and notification permissions. Check your app's merged manifest after the first build to confirm they're there.

FileProvider: the SDK registers ${applicationId}.fileprovider (the authority Capacitor's camera plugin requires). If your app already declares a provider with that exact authority, rename yours to avoid a merge conflict.
Firebase: add your own google-services.json and apply the com.google.gms.google-services plugin if you want order push notifications. Also see Push notifications if your app has its own FirebaseMessagingService.
Runtime permissions: manifest entries alone aren't enough on Android 6+. Either ask for location, notification and camera permission in your own UI, or call requestPermissions() and let the SDK's permission screens handle it.
Kotlin version: the SDK brings in kotlin-stdlib 2.2. If your project's Kotlin Gradle Plugin is older and the build fails with "Module was compiled with an incompatible version of Kotlin", upgrade the plugin, or add -Xskip-metadata-version-check to kotlinOptions.freeCompilerArgs.

API reference — `AarambhSDK`

A singleton: use AarambhSDK.getInstance(). Config values are com.getcapacitor.JSObject (a JSONObject subclass, available transitively). Every method below returns immediately and runs on the calling thread; call them from the main thread.

Method	Notes
`initialize(JSObject config)`	Call once at startup (in `Application.onCreate()` is best), before any other call. See config keys below.
`login(String authToken, JSObject userDetails, JSObject agentDetails)`	Hands over a session your app already has, so the SDK skips its own OTP screen and goes straight to home. Only `authToken` is required; pass `null` for either details object to omit it (`agentDetails` then falls back to `userDetails`). A two-argument `login(authToken, userDetails)` overload also exists. Call it before `launch()` for the first handoff (see the call-order warning below).
`launch(Context context)`	Starts `SDKActivity`. Pass an `Activity`; a non-Activity `Context` also works (the SDK adds `FLAG_ACTIVITY_NEW_TASK`).
`close()`	Finishes the active `SDKActivity`, if there is one, and returns to your app.
`logout()`	Clears the session held by the SDK and signs the agent out of the open SDK screen.
`requestPermissions(Context context)` (optional)	Use this only if you don't want to build your own runtime permission flow (location, battery optimisation, notifications, camera). It shows the SDK's step-by-step permission screens instead, and starts `SDKActivity` if it isn't already running.
`handleNotification(Context context, Map<String, String> data)` (optional)	Only needed if your app has its own `FirebaseMessagingService`. Pass Aarambh pushes to the SDK from there; see Push notifications.

`initialize()` config keys

kotlin

AarambhSDK.getInstance().initialize(JSObject().apply {
    put("environment", "sandbox")   // "sandbox" | "live" — defaults to "live" if omitted
    put("subscriberId", "my-subscriber-id")
    put("appname", "My Android Host App")
    // optional branding:
    // put("vendorCode", "...")
    // put("clientLogo", "...")
    // put("privacy", "https://...")
    // put("terms", "https://...")
    // put("overlayIconUrl", "https://.../icon.png")
})

The host app can't set clientUri/sseUri. The SDK picks them from environment and overwrites anything passed under those keys. If environment is left out it defaults to live, so a missing key points at production, never sandbox.
overlayIconUrl only shows up on the floating bubble after the SDK has reached its home screen with a session the backend accepts (a fake or expired token never gets that far). The image is downloaded and cached the first time the bubble appears.
Call initialize() at app startup, not inside the button that opens the SDK. The SDK reads this config when its screen starts, and if initialize() hasn't run by then it falls back to built-in defaults that point at the wrong backend.

login() call order for an initial handoff

login() saves the token and details in the SDK's memory straight away, but the SDK's screen only reads them once, when SDKActivity starts. Call login() then launch(), and the session is picked up every time.

If you call login() after launch(), the session has to be pushed to a screen that's still starting up, and it's silently dropped if the screen isn't ready yet. That's almost certain when the two calls run back to back. It looks as if the token was never set: the SDK finds no session and shows its own OTP login screen. (Calling login() while SDKActivity is already on screen is the supported way to switch sessions without a close()/launch() round-trip.)

Push notifications

Order broadcasts reach the agent as FCM data messages. Android delivers each push to only one FirebaseMessagingService. If your app doesn't declare its own, the SDK's service receives them and there's nothing to do.

If your app does have its own FirebaseMessagingService, it will usually receive the push instead of the SDK, and the order card won't appear. Pass the message's data payload on to the SDK after handling your own message types:

MyMessagingService.kt

class MyMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        if (isMyOwnPush(message)) {
            // handle your app's own notification
            return
        }
        AarambhSDK.getInstance().handleNotification(applicationContext, message.data)
    }
}

The SDK switches on the payload's type field (order_broadcast, offer_closed, order_broadcast_dismiss, location_wakeup, order_update), so make sure your own pushes don't use those values. Send the device's FCM token as notifyToken in acquireSession so the backend can reach it.

Usage example

MyApplication.kt

import android.app.Application
import com.aarambh.sdk.AarambhSDK
import com.getcapacitor.JSObject

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Once at startup, before login()/launch()/any other call.
        AarambhSDK.getInstance().initialize(JSObject().apply {
            put("environment", "sandbox")
            put("subscriberId", "my-subscriber-id")
            put("appname", "My Android Host App")
        })
    }
}

MainActivity.kt

import com.aarambh.sdk.AarambhSDK
import com.getcapacitor.JSObject
import org.json.JSONObject

// session = the "data" object your backend got back from acquireSession.
fun openAarambh(session: JSONObject) {
    val sdk = AarambhSDK.getInstance()

    // login() BEFORE launch(), otherwise the session can be silently dropped.
    sdk.login(
        session.getString("token"),
        session.optJSONObject("currentUser")?.let { JSObject(it.toString()) },
        session.optJSONObject("agentDetails")?.let { JSObject(it.toString()) },
    )

    sdk.launch(this) // starts the visible SDKActivity
}

fun closeAarambh() {
    AarambhSDK.getInstance().close()
}

fun signOut() {
    AarambhSDK.getInstance().logout()
}

Java works the same way: AarambhSDK.getInstance().login(token, userDetails, agentDetails); then AarambhSDK.getInstance().launch(this);.

Aarambh SDK docs

Flutter integration guide

Acquiring a session

Installation

Authenticating the native dependency

API reference — AarambhSdk

Pass-through / dispatch methods

initialize() config keys

Usage example

React Native integration guide

Acquiring a session

Installation

Authenticating the native dependency

API reference — AarambhSdk

initialize() config keys

Usage example

Native Android integration guide

Acquiring a session

Installation

1. Add the GitHub Packages repository

2. Add the dependency

3. What gets merged into your manifest

API reference — AarambhSDK

initialize() config keys

Push notifications

Usage example

API reference — `AarambhSdk`

`initialize()` config keys

API reference — `AarambhSdk`

`initialize()` config keys

API reference — `AarambhSDK`

`initialize()` config keys