Getting started with Android

Live updates, chat, who is online and calls in an Android app written in Kotlin, through WordPlus Cloud. The app joins the same rooms as your web pages, so a customer in the app and an agent in a browser see each other, and a phone and a browser call each other. Your server stays the one your website has (Next.js, Laravel, Django, Express …): it declares the rooms, says who may join and call, and sends.

The SDK comes as three libraries, and an app takes only what it uses:

Library	What it gives	Needs
cloud.wordplus:realtime	rooms, events with acks, presence, counts, history, who is online, what your server sends the user, the directory	a plain Kotlin library: Android 7 (API 24) and later, or any JVM
cloud.wordplus:realtime-calls	calls between two people, group calls, ringing someone into a call	WebRTC and LiveKit, which it brings
cloud.wordplus:realtime-ui	The Better Messages call screen: the ring, the call, the group call grid and the controls	Android

The names are those of the browser: join, on, emit, emitWithAck, volatile, history, members, count, online, calls.start, calls.group. Events also come as flows. The example app is the shop of every other guide, in Jetpack Compose.

1. Your app in WordPlus Cloud

Use the app you made for your website (Apps in your WordPlus Cloud account), so the app and the site share rooms and users. A native app has no address to list: it is let in by itself.

2. Install

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")   // for calls: the LiveKit Android SDK takes a few artifacts from JitPack
    }
}

// app/build.gradle.kts
dependencies {
    implementation("cloud.wordplus:realtime:1.0.0")
    implementation("cloud.wordplus:realtime-calls:1.0.0")   // for calls
    implementation("cloud.wordplus:realtime-ui:1.0.0")      // for the Better Messages call screen
}

The libraries are built for Java 17, which the Android Gradle plugin 8 takes as it is.

3. Your server knows the app user

An app has no cookie of your site, so it sends its own sign-in with every request, such as a bearer token, and your server routes read the user from it. When the app signs in, send it the user realtime settings too, so it connects with no request first:

Node

// Express: the user of the session in a browser, that of the token in an app.
app.use( '/api/realtime', realtime.node( ( req ) => req.session.userId ?? userFromToken( req.get( 'authorization' ) ) ) );

app.post( '/api/token', express.json(), async ( req, res ) => {
    const user = await checkSignIn( req.body );
    res.json( { token: tokenFor( user ), realtime: await realtime.config( user.id ) } );
} );

PHP

// Laravel: the package routes take $request->user(). Add the middleware that signs in the tokens of your app to
// 'routes' => [ 'middleware' => [ … ] ] in config/wordplus-realtime.php. Then, at sign-in:
return [ 'token' => $user->createToken( 'app' )->plainTextToken, 'realtime' => Realtime::config( $user->id ) ];

// Plain PHP: the user of the token to respond()
$realtime->respond( $action, user_from_token( $_SERVER['HTTP_AUTHORIZATION'] ?? '' ) );

Python

# Django: who the user is, by your own function
path("api/realtime/", include(wr.urls(realtime, user=lambda request: user_from_token(request.headers.get("Authorization")))))

# FastAPI: current_user reads the token
app.include_router(wr.router(realtime, current_user), prefix="/api/realtime")

# At sign-in, in any of them
return {"token": token_for(user), "realtime": realtime.config(user.id)}

4. Connect

import cloud.wordplus.realtime.Realtime
import cloud.wordplus.realtime.RealtimeOptions
import cloud.wordplus.realtime.TextNodeStore

val server = "https://shop.example.com"
val (token, config) = signIn()   // your own sign-in, answering { token, realtime }
val prefs = context.getSharedPreferences("realtime", Context.MODE_PRIVATE)

val rt = Realtime(
    RealtimeOptions.fromConfig(
        config, server,
        headers = { mapOf("Authorization" to "Bearer $token") },
        callbackExecutor = ContextCompat.getMainExecutor(context),    // handlers on the main thread
        nodeStore = TextNodeStore({ prefs.getString(it, null) }, { key, value -> prefs.edit().putString(key, value).apply() }),
    ),
)
rt.connect()

val order = rt.join("order:1042")
order.on("updated") { data, _ -> status = data.jsonObject["status"]?.jsonPrimitive?.content ?: status }
order.on("error") { error, _ -> Log.w("shop", error.toString()) }   // forbidden, no_rule …

• RealtimeOptions.fromConfig takes your server config() as it came (a JsonElement), its routes resolved against your server address. Without one, give RealtimeOptions(app = …, endpoint = "https://shop.example.com/api/realtime", headers = { … }), and the app asks your keys route first.
• Handlers run on callbackExecutor, a thread of the SDK unless you give one: give the executor of the main thread to update your views from them.
• nodeStore keeps the realtime servers the app reached between launches, so it goes straight back to one.
• One Realtime an app, kept while the user is signed in (in a ViewModel or an object of your app). rt.close() at sign-out.
• The connection keeps itself: through a drop, from one realtime server to another without one, and back after the app was in the background, every room joined again with what it missed from its history.

5. Send

Your server sends to the room, and the app handler runs:

Node

await realtime.to( 'order:1042' ).emit( 'updated', { status: 'shipped' } );

PHP

$realtime->to( 'order:1042' )->emit( 'updated', [ 'status' => 'shipped' ] );   // Laravel: broadcast( new OrderUpdated( $order ) )

Python

realtime.to("order:1042").emit("updated", {"status": "shipped"})

Next

• Rooms, presence and online status, sending from your server and events from the app
• Calls, with the Better Messages call screen
• Encryption and your users
• Customizing the screens: the call screen look, a piece of your own, or its whole code
• Shipping, and the example app
• The API reference: realtime, realtime-calls and realtime-ui
• On your server side: rooms in depth, errors and limits