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.

Requirements

SDKRequirements
AndroidAndroid API level 24 (Android 7.0) or later, Kotlin 1.9 or later, Jetpack Compose
iOSiOS 15.0 or later, Xcode 26 or later
React NativeReact 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 InsurelySDK library 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.zip from 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-webview

In a bare React Native app:

npm install @insurely/react-native-sdk react-native-webview
cd ios && pod install

If 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-doctor

The 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:

OptioniOS (InsurelyConfiguration)Android (InsurelyConfig)React Native (config)
Customer ID and config namecustomerId, configNamecustomerId, configNamecustomerId, configName
Languagelanguage: .english, .swedish, .norwegian, .danish, or .locale(Locale)language: InsurelyLanguage.English, Swedish, Danish, French, Estonianlanguage: a code from the configuration reference
Theme modethemeMode: .light, .dark, .systemthemeMode: InsurelyThemeMode.Light, Dark, SystemthemeMode: 'light', 'dark', 'system'
Auth tokenauthTokenauthTokenauthToken
Reference IDdataAggregation.referenceIddataAggregation.referenceIddataAggregation.referenceId
  • Language: .locale(Locale) uses the locale's language if it is one of the four, and English otherwise.
  • Theme mode: on iOS, leaving themeMode out renders the light theme; set .system to 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 Bearer JWT 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, call updateAuthToken.

Prefill

FieldiOS (InsurelyPrefill)Android (InsurelyPrefill)React Native (prefill)
Personal and phone numbersuser.swedishPersonalNumber, estonianPersonalNumber, estonianPhoneNumber, norwegianPersonalNumber, norwegianPhoneNumberuser.swedishPersonalNumber, estonianPersonalNumber, estonianPhoneNumber, norwegianPersonalNumberas on the website
Username or email loginuser.usernameuser.usernameuser.username
Contact detailscustomer.email, customer.phoneNumbercustomer.email, customer.phoneNumber
One company, skipping the selectiondataAggregation.companydataAggregation.companydataAggregation.company
Several companies, with multi-selectdataAggregation.companiesdataAggregation.companiesdataAggregation.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 to InsurelyEvent, such as CollectionStatusEvent (with status, value, collectionID and company), CollectionIDEvent, PageViewEvent, AppCloseEvent, AuthTokenExpiringSoonEvent and ValidAuthTokenEvent. Match on the type: if let status = event as? CollectionStatusEvent { … }. InvalidAuthTokenEvent and InvalidCredentialsEvent are still sent but deprecated from 2.0.0: handle the errors instead.
  • Android: onEventReceived gets an InsurelyEvent: ClosePressed, PageViewed, SelectedCompany, SelectedAuthenticationMethod, CollectionInitiated, CollectionIdReceived, CollectionStatus (with collectionId and company), OpenBankIdRequested, AuthorizationTokenExpiringSoon or ValidAuthToken.
  • React Native: onEvent gets { type, … }, where type is the event's name on the website, such as 'COLLECTION_STATUS'. An event the SDK has no type for arrives as type: 'UNKNOWN', with its name.

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

ErroriOSAndroid (onErrorReceived)React Native (onError)
The BankID app can't be opened.failedToOpenBankIDFailedToOpenBankIdBANKID_NOT_INSTALLED
Wrong login details.invalidCredentialsInvalidCredentialsINVALID_CREDENTIALS
The new auth token was rejected.invalidAuthTokenInvalidAuthorizationTokenINVALID_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 openedAUTH_APP_NOT_AVAILABLE
A request to the bank failedINSTRUCTION_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: cause says why, such as COLLECTION_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.

SDKSettingDefault
iOSLogger.insurelyLogLevel (import OSLog): .none, .error or .all.none
AndroidInsurelyLogging.isEnabledfalse
React NativelogLevel prop: 'none', 'error' or 'all''all' in development, 'none' in release builds

React Native only

  • ref: InsurelyView takes a ref (InsurelyHandle) with updateAuthToken(token), to replace the auth token, and reload(), to load the interface again from scratch.
  • onInstruction: during a collection the SDK makes requests to the bank on the interface's behalf. onInstruction reports 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, where kind is 'bankid', 'mitid', 'auth-app', 'browser', 'redirect' or 'companion-app'. Return true to open it yourself, for example in your own in-app browser, or false to 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