Getting Started

Installation and Initialization

Requirements

Android

• Android 5.0+ (API level 21+)

• A smile_config.json file from https://portal.usesmileid.com/sdk

iOS

• iOS 13+

• Xcode 14+

• A smile_config.json file form https://portal.usesmileid.com/sdk

Flutter

• Flutter 3.0.0+

• Dart 3.0.5+

• Android 5.0+ (API level 21+)

• iOS 13.0+

• A smile_config.json file from https://portal.usesmileid.com/sdk

• A device with Google Play Services[^1]

React Native

• React Native 0.70.+

• Android 5.0+ (API level 21+)

• iOS 13.0+

• A smile_config.json file from https://portal.usesmileid.com/sdk

• A device with Google Play Services

Dependency

Android

The latest release is available on Maven Central and on GitHub.

Snapshot builds are also available.

Add the dependency to your module-level Gradle Build file

build.gradle.kts (Kotlin DSL)

implementation("com.smileidentity:android-sdk:<latest-version>")

build.gradle (Groovy)

implementation "com.smileidentity:android-sdk:<latest-version>"

Proguard rules are shipped with the SDK

If you use Dexguard, add the following rule

-encryptassetfiles assets/io/*, assets/dexopt/*, assets/smile_config.json

iOS

Swift Package Manager

1. In Xcode, select File > Add Packages… and enter https://github.com/smileidentity/ios

2. Select the latest version number from our release page and click add package

CocoaPods

• If you haven’t already, install the latest version of CocoaPods.

• If you don’t have an existing Podfile, run the following command to create one:

$ pod init

• Add this line to your Podfile:

pod 'SmileID'

• Run the following command:

$ pod install

• Make sure to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file subsequently

Flutter

The latest release is available on pub.dev

Add the dependency to your pubspec.yaml

dependencies:
  smile_id: <latest-version>

React Native

The latest release is available on npm

Add the dependency to your package.json

"dependencies" : {
 "@smile_identity/react-native": "<version>"
}

Smile Config

Android

Place the smile_config.json file under your application's assets, located at src/main/assets (This should be at the same level as your java and res directories)

⚠️ Note: The smile_config.json file is unique to the environment (sandbox/production) and api key for which it was created. This means you will need one file for each environment (sandbox/production) of your application.

⚠️ Note: You may need to create this directory if it does not already exist

iOS

Drag the smile_config.json file[^1] into your projects file inspector and ensure that the file is added to your app's target. Confirm that it is by checking the Copy Bundle Resources drop down in the Build Phases tab as shown below.

⚠️ Note: The smile_config.json file is unique to the environment (sandbox/production) and api key for which it was created. This means you will need one file for each environment (sandbox/production) of your application.

Flutter

Android

Place the smile_config.json file under your application's assets, located at src/main/assets (This should be at the same level as your java and res directories)

⚠️ Note: The smile_config.json file is unique to the environment (sandbox/production) and api key for which it was created. This means you will need one file for each environment (sandbox/production) of your application.

⚠️ Note: You may need to create this directory if it does not already exist

If you run into build issues related to Jetpack Compose, you may need to also update your application build.gradle file to enable Compose and specify the Compose Compiler version. See here for additional details: https://developer.android.com/jetpack/androidx/releases/compose-kotlin

android {
    buildFeatures {
        compose true
    }
    composeOptions {
        kotlinCompilerVersion = "" // Specify the version compatible with your project's Kotlin version
    }
}

FlutterFragmentActivity

Be sure to update your MainActivity.kt (android/app/src/main/kotlin//MainActivity.kt) like below:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity() {}

iOS

Drag the smile_config.json file[^1] into your projects file inspector and ensure that the file is added to your app's target. Confirm that it is by checking the Copy Bundle Resources drop down in the Build Phases tab as shown below.

React Native

Android

Place the smile_config.json file under your application's assets, located at src/main/assets (This should be at the same level as your java and res directories)

⚠️ Note: The smile_config.json file is unique to the environment (sandbox/production) and api key for which it was created. This means you will need one file for each environment (sandbox/production) of your application.

⚠️ Note: You may need to create this directory if it does not already exist

iOS

Drag the smile_config.json file[^1] into your projects file inspector and ensure that the file is added to your app's target. Confirm that it is by checking the Copy Bundle Resources drop down in the Build Phases tab as shown below.

Initialization

Android

Initialize the Smile ID SDK in your Application class' onCreate

You may need to create an Application class for your app, if one doesn't already exist

⚠️ Note: The SmileID.initialize() method now returns a deferred result. You can use you can use the isSuccess and isFailure properties of Result. An exception is thrown if MLKit initialization fails. You will need to handle this exception in your application.

See the guide here to use the bundled version which fixes the exception.

Kotlin

ExampleApplication.kt

package com.example.app

import android.app.Application
import com.smileidentity.SmileID

class ExampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        SmileID.initialize(this)
    }
}

Java

ExampleApplication.java

package com.example.app;

import android.app.Application;
import com.smileidentity.SmileID;

public class ExampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        SmileID.initialize(this);
    }
}

iOS

Initialize the SDK as early as possible. This can be done either in your AppDelegate's application(_:didFinishLaunchingWithOptions:) method or the SceneDelegate scene(_:willConnectTo:options:) depending on your app's structure.

AppDelegate.swift

class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions
                     launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let config = try? Config(url: Constant.configUrl)
        SmileID.initialize(config: config)
        return true
    }
}

Flutter

Initialize the Smile ID SDK in main.dart by calling initialize

import 'package:smile_id/smile_id.dart';

void main()  {
  SmileID.initialize();
}

On Android, your Activity must inherit from FlutterFragmentActivity instead of FlutterActivity

React Native

Initialize the Smile ID SDK in your app entry point, typically App.tsx by calling initialize

import { SmileID } from "@smile_identity/react-native";

React.useEffect(() => {
  SmileID.initialize(true); //true if running on sandbox false if running production
}, []);

Callback URL

To set the callback URL used for jobs (to deliver results to your own server), use the setCallbackUrl method

Android

SmileID.setCallbackUrl(URL("https://smileidentity.com"))

iOS

SmileID.setCallbackUrl(url: URL(string: "https://smileidentity.com"))

Flutter

SmileID.setCallbackUrl(callbackUrl: Uri.parse("https://smileidentity.com"));

React Native

SmileID.setCallbackUrl("https://smileidentity.com");

Environments (Sandbox/Production)

To switch between Sandbox and Production you should initialize using:

Android

SmileID.initialize(context = this, useSandbox = true)

iOS

SmileID.setEnvironment(useSandbox: true)

Flutter

SmileID.setEnvironment(useSandbox: true);

React Native

SmileID.setEnvironment(true); //true if running on sandbox false if running production

Usage

Android

Javadoc

The latest Javadocs can be found here

All Products are implemented using Jetpack Compose and therefore exposed as Composable functions. This is the encouraged usage pattern.

If your application employs the traditional View-based approach, then we also expose androidx.fragment.app.Fragment based wrappers around the Composables. You should use getSupportFragmentManager().setFragmentResultListener(...) to listen for results. Examples are provided for each product.

iOS

All products are implemented in SwiftUI and are therefore exposed as SwiftUI views. If your project is implemented in UIKit, you can still use the SwiftUI views by embedding them in a UIHostingController and presenting or pushing the views using UIKit's ViewController presentation mechanisms.

Networking

Android

The product screens will handle performing all network requests for you. However, it is also possible to make REST API calls directly via SmileID.api. Please refer to the Javadoc for further details.

iOS

The products screens handle performing network requests for you. However, you can also submit data to the API directly using SmileID.api , an instance of SmileIDService.

You can configure the request timeout for all network requests made by the SDK by using the requestTimeout parameter when initializing the SDK.

SmileID.initialize(config: config, useSandbox: false, requestTimeout: 120)

It is advisable not to set the requestTimeout below the value of SmileID.defaultRequestTimeout, to avoid premature timeouts in slow network conditions.

Flutter

You can make network requests to the Smile ID backend using the SmileIDService class, accessible by calling SmileID.api

React Native

Checking Job Status

Use SmileID.api.pollSmartSelfieJobStatus, SmileID.api.pollDocVJobStatus, or SmileID.api.pollBiometricKycJobStatus to poll a given Job's status until it is complete.

It is implemented asynchronously, which will emit a response for every poll attempt made.

You must handle and catch errors within your own implementation.

The delay and number of attempts is configurable.

Alternatively, you may use SmileID.api.getSmartSelfieJobStatus, SmileID.api.getDocVJobStatus, or SmileID.api.getBiometricKycJobStatus to perform a one-off job status check.

Crash Reporting (Android only)

Crash reporting is enabled by default. Only crashes caused by Smile Identity will be reported. This will not interfere with any other crash reporting you may be doing.

It can optionally be disabled by calling SmileIDCrashReporting.disable() at runtime or by passing false at initialization (Not Recommended)

Please refer to the Javadoc on SmileIDCrashReporting for further details.

Submitting to the App Store (iOS Only)

The Smile ID SDK for iOS uses the TrueDepth API. As a result, you must declare this API usage to Apple when submitting your iOS app for review to the App Store. Here is the relevant information you may be asked to provide:

What information is your app collecting

We use ARKit to capture face 3D spatial orientation and facial expressions.

For what purposes are you collecting this information

We use this data to ensure the selfie being taken is of a live user for authentication and fraud reduction purposes.

Will the data be shared with any third parties

The ARKit information is processed entirely locally and the spatial orientation/facial expression data is not submitted to any third (or first) parties

Resources

All resource identifiers defined by the SDK are prefixed by si_ so as to prevent naming clashes with your application resources. You may override any resource value -- for further information, see Customization

File Handling (Android only)

Captured files are saved to the result of calling context.getDir("SmileID", MODE_PRIVATE), which is usually: /data/user/0/<package name>/app_SmileID