Step‑by‑Step Android (Kotlin) Guide to Integrate OpenClaw Rating API Edge Explainability

1. Introduction

The OpenClaw Rating API provides AI‑driven content rating with an edge explainability feature that returns human‑readable reasons for each rating. This capability is especially valuable for Android developers who need to comply with transparency regulations or simply want to show users why a piece of content received a particular score.

In this step‑by‑step guide we will walk through everything an Android developer with Kotlin experience needs: from setting up the SDK to delivering a fully functional sample app. By the end of the tutorial you will have a runnable project that can rate text, images, or video snippets and display the explainability data directly in the UI.

If you are looking for a broader AI platform that can host OpenClaw alongside other models, check out the UBOS platform overview for a unified experience.

2. Prerequisites

• Android Studio Flamingo (or newer) with Kotlin support.
• Minimum SDK version 21 (Android 5.0 Lollipop).
• An active OpenClaw account – you will receive client_id and client_secret after registration.
• Gradle 8.0+ for dependency management.
• Internet permission declared in AndroidManifest.xml.

Optional but recommended: a AI marketing agent to automatically generate promotional copy for your app based on the rating results.

3. Installing the OpenClaw SDK

OpenClaw distributes its Android SDK via Maven Central. Add the repository and dependency to your build.gradle.kts (Kotlin DSL) file:

// Project-level build.gradle.kts
repositories {
    google()
    mavenCentral()
}

// Module-level build.gradle.kts
dependencies {
    implementation("com.openclaw:rating-sdk:1.4.2")
}

Sync the project, and Android Studio will download the SDK JARs. The SDK includes:

• RatingClient – main entry point for API calls.
• ExplainabilityResult – data class for the edge explainability payload.
• Utility classes for request signing and error handling.

For developers who also want to experiment with OpenAI models, the OpenAI ChatGPT integration can be added alongside OpenClaw without conflict.

4. Configuring API credentials

OpenClaw uses OAuth‑2 client‑credentials flow. Store your client_id and client_secret securely – never hard‑code them in source files. The recommended approach on Android is to use the EncryptedSharedPreferences API.

// SecureCredentials.kt
object SecureCredentials {
    private const val PREF_NAME = "openclaw_prefs"
    private const val KEY_CLIENT_ID = "client_id"
    private const val KEY_CLIENT_SECRET = "client_secret"

    fun save(context: Context, clientId: String, clientSecret: String) {
        val masterKey = MasterKey.Builder(context)
            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
            .build()

        val sharedPrefs = EncryptedSharedPreferences.create(
            context,
            PREF_NAME,
            masterKey,
            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
        )
        sharedPrefs.edit()
            .putString(KEY_CLIENT_ID, clientId)
            .putString(KEY_CLIENT_SECRET, clientSecret)
            .apply()
    }

    fun getClientId(context: Context): String? =
        EncryptedSharedPreferences.create(
            context,
            PREF_NAME,
            MasterKey.Builder(context).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
        ).getString(KEY_CLIENT_ID, null)

    fun getClientSecret(context: Context): String? =
        EncryptedSharedPreferences.create(
            context,
            PREF_NAME,
            MasterKey.Builder(context).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
        ).getString(KEY_CLIENT_SECRET, null)
}

After storing the credentials, initialise the RatingClient in your Application class:

// MyApp.kt
class MyApp : Application() {
    lateinit var ratingClient: RatingClient
        private set

    override fun onCreate() {
        super.onCreate()
        val clientId = SecureCredentials.getClientId(this) ?: throw IllegalStateException("Client ID missing")
        val clientSecret = SecureCredentials.getClientSecret(this) ?: throw IllegalStateException("Client Secret missing")
        ratingClient = RatingClient.Builder()
            .clientId(clientId)
            .clientSecret(clientSecret)
            .environment(RatingClient.Environment.PRODUCTION)
            .build()
    }
}

The SDK automatically fetches an access token and refreshes it when needed, so you can focus on the business logic.

5. Using the Explainability endpoint

The explainability endpoint returns a JSON payload that contains:

• rating – numeric score (0‑100).
• explanations – an array of {feature, weight, description} objects.
• model_version – identifier of the edge model used.

Call the endpoint via the SDK’s explainRating method. Below is a concise Kotlin coroutine example that rates a piece of text and displays the explainability data in a RecyclerView.

// RatingRepository.kt
class RatingRepository(private val client: RatingClient) {

    suspend fun getExplainableRating(content: String): ExplainabilityResult {
        return client.explainRating(
            ExplainRatingRequest(
                content = content,
                contentType = ContentType.TEXT,
                language = "en"
            )
        )
    }
}

In your UI layer:

// MainViewModel.kt
class MainViewModel(application: Application) : AndroidViewModel(application) {
    private val repository = RatingRepository((application as MyApp).ratingClient)
    private val _result = MutableLiveData<ExplainabilityResult?>()
    val result: LiveData<ExplainabilityResult?> = _result

    fun rateContent(text: String) {
        viewModelScope.launch {
            try {
                val explainResult = repository.getExplainableRating(text)
                _result.postValue(explainResult)
            } catch (e: Exception) {
                // Handle network or SDK errors
                _result.postValue(null)
            }
        }
    }
}

The ExplainabilityResult can be bound to a simple list layout:

<!-- item_explanation.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:padding="8dp"
    class="bg-white rounded shadow-md mb-2">

    <TextView
        android:id="@+id/feature"
        android:textStyle="bold"
        class="text-gray-800"/>

    <TextView
        android:id="@+id/description"
        class="text-gray-600 mt-1"/>
</LinearLayout>

The UI now shows why the model gave a rating of, for example, 78 – perhaps because “language toxicity” contributed -0.12 while “positive sentiment” added +0.34.

6. Building a complete Kotlin sample app

Below is a concise project structure that you can clone and run:

Key implementation highlights:

1. Request user input via EditText and hide the keyboard on submit.
2. Invoke viewModel.rateContent() inside a coroutine scope.
3. Observe viewModel.result LiveData and submit the list to RecyclerView.Adapter.
4. Show a ProgressBar while the network call is in flight.

The full source code is available in the GPT‑Powered Telegram Bot template, which demonstrates similar API interaction patterns. (Note: this link is illustrative; replace with the actual template if needed.)

For developers who want to extend the app with voice feedback, the ElevenLabs AI voice integration can read out the rating and explanations aloud.

7. Testing and verification

Proper testing ensures that the explainability data is accurate and that edge cases (e.g., empty input, network timeout) are gracefully handled.

Unit tests

Use JUnit5 together with MockWebServer to simulate OpenClaw responses:

// RatingRepositoryTest.kt
class RatingRepositoryTest {

    private val mockWebServer = MockWebServer()
    private lateinit var client: RatingClient
    private lateinit var repository: RatingRepository

    @BeforeEach
    fun setUp() {
        mockWebServer.start()
        client = RatingClient.Builder()
            .baseUrl(mockWebServer.url("/"))
            .clientId("test_id")
            .clientSecret("test_secret")
            .environment(RatingClient.Environment.TEST)
            .build()
        repository = RatingRepository(client)
    }

    @Test
    fun `explainRating returns parsed result`() = runBlocking {
        val mockResponse = MockResponse()
            .setBody("""{
                "rating": 85,
                "explanations": [
                    {"feature":"positive_sentiment","weight":0.34,"description":"Positive language"},
                    {"feature":"spam_score","weight":-0.12,"description":"Potential spam"}
                ],
                "model_version":"v1.2-edge"
            }""")
            .addHeader("Content-Type", "application/json")
        mockWebServer.enqueue(mockResponse)

        val result = repository.getExplainableRating("Hello world!")
        assertEquals(85, result.rating)
        assertEquals(2, result.explanations.size)
    }

    @AfterEach
    fun tearDown() = mockWebServer.shutdown()
}

Instrumentation tests

Verify UI updates on real devices using Espresso. Ensure the RecyclerView displays each explanation row.

Finally, run a sanity check against the production endpoint (use a test API key) to confirm that the edge model version matches the one shown in the SDK’s RatingClient.getCurrentModelVersion() method.

8. Conclusion

Integrating the OpenClaw Rating API with edge explainability into an Android Kotlin app is straightforward once the SDK is installed and credentials are securely stored. By following the steps above you can deliver transparent AI‑driven ratings, satisfy compliance requirements, and provide users with actionable insights.

Remember to monitor usage quotas on the UBOS pricing plans page if you decide to host additional AI services alongside OpenClaw. Scaling your solution is as simple as upgrading your plan or enabling the Enterprise AI platform by UBOS.

For a quick start, explore the UBOS templates for quick start – they include pre‑configured Gradle scripts and UI components that reduce boilerplate.

Happy coding, and may your apps be both intelligent and explainable!