SDK — Native Android - LearnInk Developer Docs

Beta — installed from GitHub. During the beta you build the SDK locally once, then depend on it like any other library. When we publish to Maven Central the only change will be removing mavenLocal() and the build step. See Overview.

By the end of this guide, tapping a button in your app opens LearnInk with the user already signed in.

Prerequisites

Android Studio, with JDK 17 or newer (check in Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK)
Your app’s minSdk is 21 or higher
A backend endpoint that returns a LearnInk sign-in token — see Step 1 of the WebView setup guide
Your org ID
Access to github.com/LearnInkTeam/learnink-sdk

Build the SDK on your machine

Clone the repository somewhere outside your app project, check out the beta tag, and publish the SDK to your local Maven repository:

git clone https://github.com/LearnInkTeam/learnink-sdk.git
cd learnink-sdk
git checkout v0.1.0
cd android
./gradlew :sdk:publishToMavenLocal

You should see BUILD SUCCESSFUL. This places the SDK in ~/.m2/repository/ink/learn/, where Gradle can find it.

Every developer on your team must run this once, and so must your CI runner. It is the main inconvenience of the beta and it disappears when we publish to Maven Central. If your CI cannot clone the repository, see Using a shared repository instead below.

Build fails with 'Gradle requires JVM 17 or later'

Your default JDK is too old. Either set JAVA_HOME for this command:

JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew :sdk:publishToMavenLocal

or point Android Studio’s Gradle JDK at 17+ and run it from there.

Add the dependency

In your app’s settings.gradle.kts, add mavenLocal() to the repositories block:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        mavenLocal() // Beta only — remove once LearnInk publishes to Maven Central
    }
}

If your project uses the older style with allprojects { repositories { … } } in the root build.gradle, add mavenLocal() there instead.

Then in your app module’s build.gradle.kts:

app/build.gradle.kts

dependencies {
    implementation("ink.learn:learnink-sdk:0.1.0")
}

Sync Gradle. If it cannot resolve the dependency, you missed Step 1 or added mavenLocal() in the wrong place — see Troubleshooting.

Check your permissions

The SDK declares the permissions it needs (INTERNET and ACCESS_NETWORK_STATE) in its own manifest, and Android merges them into your app automatically. You do not need to add anything.ACCESS_NETWORK_STATE is used only to detect whether the device is online, so the SDK can show downloaded content immediately instead of waiting for a network request that cannot succeed.

Configure the SDK once, at startup

Tell the SDK your org ID and how to get a token. Do this once — in your Application class, or right after your own login completes:

import ink.learn.sdk.LearnInk
import ink.learn.sdk.LearnInkConfig
import ink.learn.sdk.TokenProvider

LearnInk.configure(
    LearnInkConfig(orgId = "your-org-id"),
    TokenProvider.fromSuspend { fetchLearnInkToken() },
)

fetchLearnInkToken() is your function that calls your backend. Here is a complete example using OkHttp — adapt it to whatever HTTP client your app already uses:

private suspend fun fetchLearnInkToken(): String = withContext(Dispatchers.IO) {
    val body = JSONObject().put("id", currentUserId).toString()
        .toRequestBody("application/json".toMediaType())

    val request = Request.Builder()
        .url("https://your-api.example.com/auth/learnink")
        .post(body)
        // Authenticate this call however your own API expects:
        .header("Authorization", "Bearer $yourOwnUserSessionToken")
        .build()

    okHttpClient.newCall(request).execute().use { response ->
        check(response.isSuccessful) { "Token request failed: HTTP ${response.code}" }
        JSONObject(response.body!!.string()).getString("token")
    }
}

Never call the LearnInk Identify API directly from your app. That would put your API key on user devices, where it can be extracted. Your app calls your backend; your backend holds the key. The SDK is built around this and gives you no way to do otherwise.

Not using coroutines?

Implement TokenProvider directly and call the callback from whatever async mechanism you use. Call it exactly once:

val tokenProvider = TokenProvider { callback ->
    myApi.fetchLearnInkToken(
        onSuccess = { token -> callback.onSuccess(token) },
        onError = { error -> callback.onFailure(error) },
    )
}

Open LearnInk

The simplest integration is one line. This opens a full-screen LearnInk experience that handles loading, closing, back navigation and session refresh for you:

LearnInk.open(context, path = "learning")

path is the section to open — "learning" is the main training area.That is a complete integration. If that is all you need, skip to Step 7.

Optional — embed it in your own screen

If you want LearnInk inside your own layout (under a toolbar, in a tab, in a bottom sheet), use LearnInkWebView directly instead of LearnInk.open:

class LearningActivity : AppCompatActivity() {

    private lateinit var learnInk: LearnInkWebView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        learnInk = LearnInkWebView(this).apply {
            eventListener = object : LearnInkEventListener {
                override fun onCloseRequested() = finish()

                override fun onOfflineContentUnavailable() = showNoOfflineContentScreen()
            }
        }

        findViewById<FrameLayout>(R.id.learnInkContainer).addView(learnInk)
        learnInk.load("learning")
    }

    override fun onDestroy() {
        learnInk.destroy() // Required — releases the WebView
        super.onDestroy()
    }
}

Always call destroy() in onDestroy() (or onDestroyView() for a Fragment). Forgetting this leaks the WebView.

Two layout rules worth knowing:

Give the view a real size — in a LinearLayout, use height = 0 with layout_weight = 1 so it fills the space your toolbar does not use. A wrap_content height renders nothing.
Position it clear of the system bars yourself. The SDK does not apply window insets, because only your app knows where the view sits in your layout.

Verify it works

Run your app and open LearnInk. You should see:

✅ A brief loading indicator, then LearnInk content
✅ No login screen — the user is signed in automatically
✅ Tapping the close button inside LearnInk dismisses the screen

If you see a login screen, the token did not reach LearnInk. That is the most common first-run problem and it is almost always the backend endpoint — see Troubleshooting.

Reacting to events

Override only the callbacks you care about — they all have default empty implementations.

learnInk.eventListener = object : LearnInkEventListener {
    override fun onCloseRequested() { finish() }
}

Callback	When it fires	What you should do
`onCloseRequested()`	User tapped close inside LearnInk	Dismiss your screen
`onAuthenticationFailed(error)`	Token fetch failed; page loaded signed-out	Log it — this usually means your backend is misconfigured
`onSessionRefreshFailed(error)`	Session expired and re-authentication failed	Offer a retry via `refreshSession()`
`onOfflineModeEntered()`	Offline; showing downloaded content	Usually nothing — LearnInk shows its own offline banner
`onOfflineContentUnavailable()`	Offline and nothing was downloaded	Show your own message — see Offline behaviour
`onConnectivityRestored()`	Network came back	Optionally call `refreshSession()`
`onMessage(type, rawJson)`	A message the SDK does not handle itself	Usually nothing
`onHistoryChanged(canGoBack)`	WebView history changed	Update your own back button, if you have one
`onPageStarted` / `onPageFinished`	Page load lifecycle	Custom loading UI, analytics
`onWebResourceError(description)`	A page failed to load	Log it

Configuration reference

LearnInkConfig(
    orgId = "your-org-id",
    baseUrl = "https://m.learn.ink",
    tokenTimeoutMillis = 5_000,
    openExternalLinksInBrowser = true,
    extraHttpHeaders = emptyMap(),
    offlineSupportEnabled = true,
    offlineFirstDelayMillis = 1_000,
)

Option	Default	What it does
`orgId`	required	Your LearnInk organisation ID
`baseUrl`	`https://m.learn.ink`	Only change if LearnInk gives you a staging URL
`tokenTimeoutMillis`	`5000`	How long to wait for your `fetchToken` before giving up
`openExternalLinksInBrowser`	`true`	Links leaving LearnInk open in the device browser
`extraHttpHeaders`	empty	Extra headers on page loads (rarely needed)
`offlineSupportEnabled`	`true`	Show downloaded content when offline
`offlineFirstDelayMillis`	`1000`	Show downloaded content if the token is slower than this

Using a shared repository instead

If running publishToMavenLocal on every machine and CI runner is impractical, publish the SDK once to a Maven repository your team already has (Artifactory, Nexus, or a static bucket), and point your app at that instead of mavenLocal():

cd learnink-sdk/android
./gradlew :sdk:publishReleasePublicationToLocalStagingRepository
# Upload the contents of sdk/build/staging-repo to your Maven repository

Email support@learn.ink if you would like help with this.

Next steps

Offline behaviour

What your app must show when a user has no connection and nothing downloaded.

Push notifications

Still required — the SDK does not change how notifications reach users.

Getting Started

Mobile SDK (Beta)

WebView Integration

Webhooks

Data Sync

Privacy & User Management

SDK — Native Android

Prerequisites

Reacting to events

Configuration reference

Using a shared repository instead

Next steps

Offline behaviour

Push notifications

​Prerequisites

​Reacting to events

​Configuration reference

​Using a shared repository instead

​Next steps

Offline behaviour

Push notifications

Prerequisites

Reacting to events

Configuration reference

Using a shared repository instead

Next steps