Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.

Android SDK Early access

The ng.onshore.sdk library collects and shows sensitive values in an Android app, using the same single-use client tokens as the web components. It holds no credentials.

Packageng.onshore.sdk
Sourcegithub.com/Onshore-HQ/onshore-android 
Min SDK24 (Android 7.0)
LanguageKotlin, callable from Java
DependenciesNone beyond the Android framework
ThreadingSecureClient calls block: call them off the main thread. The views do this for you

Install

It isn’t on Maven Central yet. Build the library from its repository and add the AAR to your app:

git clone https://github.com/Onshore-HQ/onshore-android && cd onshore-android ./gradlew assembleRelease # writes build/outputs/aar/
app/build.gradle.kts
dependencies { implementation(files("libs/onshore-android-release.aar")) }

Set up

List your app as an origin

In Vaults → Secure components, add rvapp:// followed by your application ID in lower case: rvapp://com.yourbank.wallet.

Mint client tokens on your server

const { client_token } = await vault.createClientToken(VAULT, { kind: "collect", origin: "rvapp://com.yourbank.wallet", fields: ["national_id"], subjectRef: user.customerId, });

Create the client

val onshore = SecureClient( baseUrl = "https://vault.yourbank.example", appOrigin = "rvapp://com.yourbank.wallet", )

Collect with CollectView

class AddIdActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val token = intent.getStringExtra("clientToken")!! val form = CollectView( context = this, client = onshore, clientToken = token, labels = mapOf("national_id" to "National Insurance number"), submitLabel = "Save", onTokens = { tokens -> lifecycleScope.launch { api.saveIdToken(tokens.getValue("national_id")) } }, onError = { e -> when (e) { is VaultException.ValidationFailed -> Unit // shown under the field; the token still works VaultException.InvalidClientToken -> toast("This form expired. Open it again.") VaultException.Denied -> toast("You can't add this.") VaultException.RateLimited -> toast("Too many tries. Wait a minute.") is VaultException.Server, VaultException.Transport -> toast("Couldn't save. Try again.") } }, ) setContentView(form) } }
ParameterDefaultMeaning
contextAn Activity context (needed to secure the window)
clientYour SecureClient
clientTokenFrom your server
labelsemptyField name to label
submitLabel"Continue"The button text
onTokensCalled on the main thread with field → token
onErrorignoreCalled on the main thread with a VaultException

CollectView builds a field per field the token covers, with a number keyboard for numeric data types. It has a submit() method if you want your own button, and no method that returns what was typed.

What it does for you: sets FLAG_SECURE on the window while attached, which blocks screenshots, screen recording and the recent-apps preview; refuses touches when another app draws over it (filterTouchesWhenObscured); turns off autofill, suggestions and the copy and paste menu on each field; clears values when it leaves the window.

Reveal with RevealView

val shown = RevealView(this, onshore, revealToken, hideAfterMs = 30_000) { e -> Log.w("onshore", "reveal: $e") } container.addView(shown)

Values are removed after hideAfterMs, when the view stops being visible, and when it’s detached. FLAG_SECURE applies while it’s showing.

Jetpack Compose

Wrap the views with AndroidView:

@Composable fun SecureIdForm(token: String, onTokens: (Map<String, String>) -> Unit) { AndroidView(factory = { ctx -> CollectView(ctx, onshore, token, labels = mapOf("national_id" to "NI number"), onTokens = onTokens) }) }

SecureClient

class SecureClient(baseUrl: String, appOrigin: String, socketFactory: SSLSocketFactory? = null, timeoutMs: Int = 15_000) @Throws(VaultException::class) fun describe(clientToken: String): ComponentDescription @Throws(VaultException::class) fun collect(clientToken: String, values: Map<String, String>): Map<String, String> @Throws(VaultException::class) fun reveal(clientToken: String): List<RevealedValue>
MethodReturns
describeComponentDescription(kind, fields: List<FieldDescription(name, dataType)>, tokens). Doesn’t spend the token
collectA token per field. Spends the token unless a value fails its format check
revealList<RevealedValue(decision, value, errorCode)>. toString() leaves out value, so logging one doesn’t leak it

From a coroutine:

val tokens = withContext(Dispatchers.IO) { onshore.collect(token, mapOf("national_id" to typed)) }

Requests don’t follow redirects (a redirect mustn’t carry a value elsewhere) and don’t use caches.

Errors

sealed class VaultException : Exception { object InvalidClientToken // get a new token class ValidationFailed(val fields: List<String>) // names only; the token still works object Denied object RateLimited class Server(val status: Int, val serverCode: String) object Transport // network failure or unreadable response }

Pinning your server’s certificate

The simplest way needs no code: Android’s network security config  with a <pin-set> for the vault’s domain.

res/xml/network_security_config.xml
<network-security-config> <domain-config> <domain includeSubdomains="false">vault.yourbank.example</domain> <pin-set expiration="2027-12-31"> <pin digest="SHA-256">base64-of-current-public-key=</pin> <pin digest="SHA-256">base64-of-backup-public-key=</pin> </pin-set> </domain-config> </network-security-config>

Reference it from <application android:networkSecurityConfig="@xml/network_security_config">. For your own trust logic, pass an SSLSocketFactory from an SSLContext built with your TrustManager as socketFactory.

Limits

An app is weaker than a browser frame. While a value is typed it exists in your app’s process, and a hostile library in your app could walk the view tree to read it. rvapp:// is a name, not proof of which app is calling; set bind_ip when minting if you know the device’s address.

Tested: the client passed against a live install on an Android 10 emulator. The views have not yet been shown on a screen, and nothing has run on a physical device. Test in your app on real devices before release.

Last updated on