Android Native

1. Prerequisites

Before starting the integration, ensure you have:

• A Streamoji Developer Account: Register at Streamoji Dashboard.
• Android Example App (Kotlin): Reference implementation at ready-player-me-archives/Example-Android-Kotlin.
• API Credentials: You will need a Client ID and Client Secret to fetch authentication tokens.
• Android Studio: The SDK is compatible with Android API level 21 (Lollipop) and higher.

2. Project Setup

Android Permissions

Add the following permissions to your AndroidManifest.xml to enable network access, camera usage (for photo-based avatars), and file storage:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

3. The Identity Bridge (userid)

Attaching a userid to your avatar creator session is critical for mapping avatars to specific users in your backend database. It enables:

• User Identification: Know exactly who is creating the avatar.
• Persistence: Automatic saving and loading of user-specific assets.
• Re-editing: Fetching the same avatar state when the user returns.

Constructing the URL

Always use Uri.Builder to ensure the userid and other parameters are correctly URL-encoded.

val baseUrl = "https://avatars.streamoji.com/createAvatar"
val finalUrl = Uri.parse(baseUrl)
    .buildUpon()
    .appendQueryParameter("userid", currentUserId)  // REQUIRED: The unique user identifier
    .appendQueryParameter("token", authToken)       // REQUIRED: Your session token 
    .appendQueryParameter("iframe", "true")        // REQUIRED: Optimized for WebView
    .appendQueryParameter("source", "android-sdk")
    .appendQueryParameter("themeColor", "B8B8FC")  // OPTIONAL: Custom hex color
    .build()
    .toString()

webView.loadUrl(finalUrl)

4. WebView Configuration

To correctly process the avatar creator events, your WebView must be configured with JavaScript enabled and a bridge interface:

webView.settings.apply {
    javaScriptEnabled = true
    domStorageEnabled = true
    databaseEnabled = true
    allowFileAccess = true
}

// Injects 'WebView' object into the JavaScript context
webView.addJavascriptInterface(StreamojiWebBridge(this), "WebView")

5. Event Handling (JavaScript Bridge)

The Avatar Creator communicates with your Android app via postMessage events. You must listen for these events to retrieve the final avatar URL.

Key Events:

Handling the Export Event:

@JavascriptInterface
fun receiveData(json: String) {
    val message = Gson().fromJson(json, WebMessage::class.java)
    
    if (message.eventName == "v1.avatar.exported") {
        val avatarUrl = message.data["url"]
        val associatedUserId = message.data["userid"]
        
        Log.d("Streamoji", "Avatar Exported for User: $associatedUserId")
        // Proceed with loading the .glb or .png avatar
    }
}

6. Best Practices

1. Security: Never hardcode your Client Secret in the Android app. Always fetch the authToken through your own secure backend API.
2. Encoding: Always use Uri.Builder for the userid. If a user ID is an email (e.g., user@example.com), standard string concatenation will fail to load the creator correctly.
3. Loading States: Display a ProgressBar until the v1.frame.ready event is received to ensure a premium user experience.