Mobile SDKs
We provide three SDKs for embedding the Prebuilt UI in a native app: Android, iOS and React Native.
Each SDK loads the Prebuilt UI in a native web view and exposes a single view component plus a small set of configuration, prefill and event APIs, so you do not have to build the webview integration yourself.
Android
Jetpack Compose. Published to Maven Central.
iOS
SwiftUI. Distributed as an XCFramework from GitHub.
React Native
Expo and bare React Native. Distributed as an npm package.
Requirements
| SDK | Requirements |
|---|---|
| Android | Android API level 24 (Android 7.0) or later, Kotlin 1.9 or later, Jetpack Compose |
| iOS | iOS 15.0 or later, Xcode 26 or later |
| React Native | React Native 0.76 or later, New Architecture only. iOS 15 or later, Android minSdk 24 |
iOS 15.0–16.3
The iOS SDK installs on iOS 15.0 and later, but the interface hasn't been fully verified on iOS
15.0–16.3 yet. Until it has, show InsurelyView only on iOS 16.4 and later:
if #available(iOS 16.4, *) {
InsurelyView(context: context, configuration: configuration)
}Installation
The SDK can be installed three ways. All produce an identical, signed binary in your app, they differ only in how the framework reaches your project.
- Swift Package Manager (remote) when GitHub is reachable at build time and you want SPM to manage
version updates. Add the repository in File → Add Package Dependencies…, then add the
InsurelySDKlibrary to your target with Embed & Sign. - Swift Package Manager (local clone) when you want to vendor the SDK for reproducibility, build in air-gapped CI, or pin to a specific commit. Clone the repository, then File → Add Package Dependencies… → Add Local….
- Manual framework integration when you do not use SPM. Download
InsurelySDK.xcframework.zipfrom the latest release, unzip it, drag it into your project, and set Embed & Sign.
Step-by-step instructions for each method are in the repository README.
Add the dependency:
dependencies {
implementation("com.insurely:insurely-android-sdk:3.0.0")
}mavenCentral() is already in most projects' repository list; if it is not, add it in
settings.gradle.kts:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}Sync Gradle, and the SDK is available under import com.insurely.blocks.sdk.*. Gradle resolves the
SDK's own dependencies from its POM, so there is nothing else to declare.
Use 2.1.1 or later
Before 2.1.1, when a user signs in with Swedish BankID by personal number instead of a QR code, the SDK opens the BankID app with an invalid token.
Upgrading from the AAR
If you integrated before 1.2.2, the SDK was distributed as an AAR you vendored or downloaded, and you
declared its dependencies yourself. Switching to the Maven coordinate lets you delete the vendored
AAR, the flatDir repository entry and those dependency declarations, since the POM carries what the
SDK needs. Keep a declaration only if your own code uses that library. From 2.0.0 the SDK uses OkHttp
instead of Ktor.
The AAR is still attached to every
release for builds that
cannot reach Maven Central. That path requires declaring two dependencies by hand,
org.jetbrains.kotlinx:kotlinx-serialization-json and com.squareup.okhttp3:okhttp, at the versions the
repository README
lists for your SDK version.
Expo Go is not supported
The SDK has native code, which Expo Go can't load, so the view fails as soon as it is imported.
Use a development build instead: npx expo run:ios / npx expo run:android, or
eas build --profile development.
Install the package and its react-native-webview peer dependency:
npx expo install @insurely/react-native-sdk react-native-webviewIn a bare React Native app:
npm install @insurely/react-native-sdk react-native-webview
cd ios && pod installIf you need Swedish BankID, there is native setup on top of that, because the BankID app returns the
user to your app through a custom URL scheme. On Expo the bundled config plugin handles all of it, so
you never edit Info.plist or AndroidManifest.xml by hand. Add it to app.json, passing the scheme
your app uses to receive the user back:
{
"expo": {
"scheme": "myapp",
"plugins": [
["@insurely/react-native-sdk/app.plugin.js", { "bankIdRedirectScheme": "myapp" }]
]
}
}Rebuild afterwards. Editing app.json alone changes nothing until the next prebuild.
Without Expo there is no plugin to run, so those entries go in by hand. The SDK ships a checker that reports exactly which are missing and prints the block to paste in:
npx insurely-sdk-doctorThe getting started guide has the full bare React Native setup, the event model and the imperative API.
Quickstart
The whole SDK is reached through a single view. We provide your Customer ID and Config name during onboarding, see Introduction.
import SwiftUI
import InsurelySDK
struct InsurelyScreen: View {
var body: some View {
InsurelyView(
context: InsurelyContext(environment: .production),
configuration: InsurelyConfiguration(
customerId: "your-customer-id",
configName: "your-config-name"
)
)
.onInsurelyResults { results in
// Handle the collected data when the flow completes.
print(results.data)
}
.onInsurelyError { error in
switch error {
case .loadFailed:
// The interface couldn't load, e.g. no network. Offer a way to try again.
break
case .nonRecoverableError:
// The interface shows its error screen and can't continue. Close the view.
break
default:
// Such as .failedToOpenBankID or .collectionFailed. Log it or show a message.
break
}
}
}
}import androidx.compose.runtime.Composable
import com.insurely.blocks.sdk.InsurelyView
import com.insurely.blocks.sdk.config.InsurelyConfig
import com.insurely.blocks.sdk.config.InsurelyEnvironment
import com.insurely.blocks.sdk.config.InsurelySettings
@Composable
fun InsurelyScreen() {
InsurelyView(
settings = InsurelySettings(
environment = InsurelyEnvironment.Prod,
config = InsurelyConfig(
customerId = "your-customer-id",
configName = "your-config-name",
),
),
onResultsReceived = { results ->
// Handle the collected data when the flow completes.
},
onEventReceived = { event ->
// Handle SDK events (collection status, page views, etc.).
},
onErrorReceived = { error ->
// Handle SDK errors.
},
)
}environment defaults to InsurelyEnvironment.Test, so always set InsurelyEnvironment.Prod in
production builds. Without it, your app runs against the test environment.
import { InsurelyView, type InsurelyConfig } from '@insurely/react-native-sdk';
const config: InsurelyConfig = {
customerId: 'your-customer-id',
configName: 'your-config-name',
language: 'sv',
};
<InsurelyView
style={{ flex: 1 }}
environment="test"
config={config}
bankIdRedirectUrl="myapp:///"
onResults={(results) => console.log(results.data)}
onError={(error) => console.warn(error)}
onEvent={(event) => console.log(event)}
/>;This reaches the company selection screen. environment selects the Blocks deployment and takes
'production', 'staging' or 'test', or { url: 'https://...' } to point at a specific one.
bankIdRedirectUrl only matters if you need Swedish BankID. It is the scheme the BankID app uses to
return the user to your app.
Configuration
The SDKs pass your configuration to the same interface as the website, so each option works as described in the configuration reference. Each SDK uses its own names:
| Option | iOS (InsurelyConfiguration) | Android (InsurelyConfig) | React Native (config) |
|---|---|---|---|
| Customer ID and config name | customerId, configName | customerId, configName | customerId, configName |
| Language | language: .english, .swedish, .norwegian, .danish, or .locale(Locale) | language: InsurelyLanguage.English, Swedish, Danish, French, Estonian | language: a code from the configuration reference |
| Theme mode | themeMode: .light, .dark, .system | themeMode: InsurelyThemeMode.Light, Dark, System | themeMode: 'light', 'dark', 'system' |
| Auth token | authToken | authToken | authToken |
| Reference ID | dataAggregation.referenceId | dataAggregation.referenceId | dataAggregation.referenceId |
- Language:
.locale(Locale)uses the locale's language if it is one of the four, and English otherwise. - Theme mode: on iOS, leaving
themeModeout renders the light theme; set.systemto follow the device. On Android and React Native, leaving it out uses the interface's default. Dark mode also needs a dark theme in your configuration on our side. - Auth token: the same
BearerJWT as on the website, see Auth token. To replace it while the view is open, on iOS and Android render the view again with a configuration holding the new token: the SDK hands it over without reloading. On React Native, callupdateAuthToken.
Prefill
| Field | iOS (InsurelyPrefill) | Android (InsurelyPrefill) | React Native (prefill) |
|---|---|---|---|
| Personal and phone numbers | user.swedishPersonalNumber, estonianPersonalNumber, estonianPhoneNumber, norwegianPersonalNumber, norwegianPhoneNumber | user.swedishPersonalNumber, estonianPersonalNumber, estonianPhoneNumber, norwegianPersonalNumber | as on the website |
| Username or email login | user.username | user.username | user.username |
| Contact details | customer.email, customer.phoneNumber | customer.email, customer.phoneNumber | |
| One company, skipping the selection | dataAggregation.company | dataAggregation.company | dataAggregation.company |
| Several companies, with multi-select | dataAggregation.companies | dataAggregation.companies | dataAggregation.companies |
React Native also takes the { value, inputField } form that
locks a field.
On Android before 3.0.0, dataAggregation.companies was a single string that skipped the
selection, as company does now, and several companies couldn't be prefilled. From 3.0.0, rename it
to company, or pass a list to companies.
On iOS before 2.0.0, InsurelyPrefill.DataAggregation requires autostart. Pass false: neither
autostart nor loginMethod has any effect. From 2.0.0 you can leave both out.
InsurelyView(
context: InsurelyContext(environment: .production),
configuration: configuration,
prefill: InsurelyPrefill(
user: .init(swedishPersonalNumber: "200001020000"),
dataAggregation: .init(company: "se-demo")
)
)Events
Each SDK hands you the interface's events as typed values:
- iOS:
.onInsurelyEvent { event in … }. Each event is its own type conforming toInsurelyEvent, such asCollectionStatusEvent(withstatus,value,collectionIDandcompany),CollectionIDEvent,PageViewEvent,AppCloseEvent,AuthTokenExpiringSoonEventandValidAuthTokenEvent. Match on the type:if let status = event as? CollectionStatusEvent { … }.InvalidAuthTokenEventandInvalidCredentialsEventare still sent but deprecated from 2.0.0: handle the errors instead. - Android:
onEventReceivedgets anInsurelyEvent:ClosePressed,PageViewed,SelectedCompany,SelectedAuthenticationMethod,CollectionInitiated,CollectionIdReceived,CollectionStatus(withcollectionIdandcompany),OpenBankIdRequested,AuthorizationTokenExpiringSoonorValidAuthToken. - React Native:
onEventgets{ type, … }, wheretypeis the event's name on the website, such as'COLLECTION_STATUS'. An event the SDK has no type for arrives astype: 'UNKNOWN', with itsname.
Only some collection statuses have their own case. The rest arrive as "other", with the status
exactly as the interface sent it: value on iOS, Other(label) on Android, raw on React Native.
Match on that string for statuses such as WAITING_FOR_USER_ACTION.
Close the view when you get APP_CLOSE (AppCloseEvent on iOS, ClosePressed on Android). The
interface can't close itself.
Errors
| Error | iOS | Android (onErrorReceived) | React Native (onError) |
|---|---|---|---|
| The BankID app can't be opened | .failedToOpenBankID | FailedToOpenBankId | BANKID_NOT_INSTALLED |
| Wrong login details | .invalidCredentials | InvalidCredentials | INVALID_CREDENTIALS |
| The new auth token was rejected | .invalidAuthToken | InvalidAuthorizationToken | INVALID_AUTH_TOKEN |
| A collection failed for another reason | .collectionFailed(cause:collectionStatus:message:) | CollectionFailed(cause, collectionStatus, message) | ERROR |
| The interface shows its error screen | .nonRecoverableError(type:) | NonRecoverableError(type) | NON_RECOVERABLE_ERROR |
| The interface could not load | .loadFailed(url:statusCode:description:) | LoadFailed(url, statusCode, description) | LOAD_FAILED. Call reload() once the device is back online |
| A bank's login app can't be opened | AUTH_APP_NOT_AVAILABLE | ||
| A request to the bank failed | INSTRUCTION_FAILED |
On iOS, errors arrive in .onInsurelyError. Everything after .failedToOpenBankID needs 2.0.0:
before that, wrong login details and a rejected token arrived only as events, and the rest weren't
reported. On Android, failed collections, the error screen and failed loads need 3.0.0.
- Failed collection:
causesays why, such asCOLLECTION_FAILED_THIRD_PARTY_ERROR. The message is for your logs, not for the user. - Error screen: the flow can't continue. Close the view, or let the user start over.
- Could not load: no network, a DNS or TLS failure, or an HTTP error from our servers. The view shows an error page or nothing, so show your own message or a way to try again. The status code is set for an HTTP error only.
A switch (iOS) or when (Android) that lists every error with no default or else stops
compiling when an SDK adds an error, so keep one.
On iOS, same-device BankID needs bankid in LSApplicationQueriesSchemes in your Info.plist.
Without it, every attempt fails with .failedToOpenBankID.
Logging
Each SDK can log what it does while you integrate it. Leave logging off in release builds.
| SDK | Setting | Default |
|---|---|---|
| iOS | Logger.insurelyLogLevel (import OSLog): .none, .error or .all | .none |
| Android | InsurelyLogging.isEnabled | false |
| React Native | logLevel prop: 'none', 'error' or 'all' | 'all' in development, 'none' in release builds |
React Native only
ref:InsurelyViewtakes a ref (InsurelyHandle) withupdateAuthToken(token), to replace the auth token, andreload(), to load the interface again from scratch.onInstruction: during a collection the SDK makes requests to the bank on the interface's behalf.onInstructionreports each one that succeeded as{ url, status, finalUrl }, never headers, bodies or cookies, so you can tell a stuck collection from one that is running.onOpenUrl(url, kind): called before the SDK opens a URL, wherekindis'bankid','mitid','auth-app','browser','redirect'or'companion-app'. Returntrueto open it yourself, for example in your own in-app browser, orfalseto let the SDK open it.
const insurely = useRef<InsurelyHandle>(null);
<InsurelyView ref={insurely} {...props} />;
insurely.current?.updateAuthToken(newToken);Building your own instead
If you would rather set the webview up yourself instead of using an SDK, the mobile webview guide covers the full iOS and Android integration.
Last updated on