Getting Started

Installation and Initialization

Requirements

Android 5.0+ (API level 21+)
A smile_config.json file from your portal Security Settings page

SDK Versions

We’re excited to share that our mobile SDKs have been upgraded from v10 to v11, bringing you enhanced functionality while maintaining full backward compatibility. These non-breaking updates ensure a smooth transition by simply updating to v11 to access the latest features without altering your existing integration.

Note: For native Android, please use version 11.0.2 or later to guarantee optimal performance.

For complete details, including bug fixes and new capabilities, please refer to our release notes.

Dependency

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

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

In Xcode, select File > Add Packages… and enter https://github.com/smileidentity/ios
Select the latest version number from our release page and click add package

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

The latest release is available on pub.dev

Add the dependency to your pubspec.yaml

dependencies:
  smile_id: <latest-version>

If you're using Kotlin < 2.0.0, you need to manually specify your Kotlin and Compose compiler versions. Set them in your project-level build.gradle.kts file like this:

extra.set("kotlinVersion", "1.9.25")
extra.set("kotlinCompilerExtensionVersion", "1.5.15")

⚠️ Note the Compose to Kotlin Compatibility Map here - https://developer.android.com/jetpack/androidx/releases/compose-kotlin

The latest release is available on npm

Add the dependency to your package.json

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

If you are using Kotlin <2.0.0 and you need to specify your Kotlin/Compose versions, you should set it up like this in the buildscript block of your android/build.gradle file

buildscript {
  ext {
    buildToolsVersion = "34.0.0"
    minSdkVersion = 23
    compileSdkVersion = 35
    targetSdkVersion = 35
    kotlinVersion = "1.9.24"
    kotlinCompilerExtensionVersion = "1.5.14"
    
    ndkVersion = "26.1.10909125"
  }
...
...
}

⚠️ Note the Compose to Kotlin Compatibility Map here - https://developer.android.com/jetpack/androidx/releases/compose-kotlin

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
    }
    kotlinOptions {
        freeCompilerArgs += ['-Xskip-metadata-version-check'] // only add if kotlin version is before 2.0
    }
}

⚠️ Note: If you are using any kotlin version before 2.0, please add this freeCompilerArgs += ['-Xskip-metadata-version-check'] as shown in the configuration above.

Smile Config

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

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: You may need to create this directory if it does not already exist

android {
    buildFeatures {
        compose true
    }
    composeOptions {
        kotlinCompilerVersion = "" // Specify the version compatible with your project's Kotlin version
    }
    kotlinOptions {
        freeCompilerArgs += ['-Xskip-metadata-version-check'] // only add if kotlin version is before 2.0
    }
}

⚠️ Note: If you are using any kotlin version before 2.0, please add this freeCompilerArgs += ['-Xskip-metadata-version-check'] as shown in the configuration above.

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

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.

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)
    }
}

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);
    }
}

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
    }
}

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

import 'package:smile_id/smile_id.dart';

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

import 'package:smile_id/smile_id.dart';
//the values should be passed in as secrets taken from your smile_config.json file
void main()  {
  SmileID.initializeWithConfig(
      useSandbox: false,
    config: FlutterConfig(
        partnerId: partnerId,
        authToken: authToken,
        prodBaseUrl: prodBaseUrl,
        sandboxBaseUrl: sandboxBaseUrl
    ),
    enableCrashReporting: false
  );
}

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

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

/**
   * Initialize SmileID SDK with configuration
   * @param useSandBox - Configuration object for the SDK
   * @param enableCrashReporting - Whether to enable crash reporting
   * @param apiKey - api key specific to the partner and also environment
   * @param config - Configuration object for the SDK
   */
  initialize: (
    useSandBox: boolean = false,
    enableCrashReporting = false,
    apiKey?: string,
    config?: Config,
  ) => _SmileID.initialize(useSandBox, apiKey, config, enableCrashReporting),

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

/* Option 1
This requires the smile_config.json be part of the copy bundle phases on your ios target and in your assets folder on android
*/
React.useEffect(() => {
  SmileID.initialize(true); 
}, []);

//For option 2 and 3 you would use the same config object this comes from the 
//smile id portall as the smile_config.json and youc an copy paste contents to this
//object
const config: Config = {
  partnerId: 'YOUR PARTNER ID',
  authToken: 'YOUR AUTH TOKEN',
  prodLambdaUrl: 'PROD LAMBDA URL',
  testLambdaUrl: 'TEST LAMBDA URL',
};
/* Option 2
This requires using the config
*/
React.useEffect(() => {
  SmileID.initialize(true,true,config); 
}, []);

/* Option 3
This requires using the api key
*/
React.useEffect(() => {
  SmileID.initialize(true,true,config,'YOUR API KEY'); 
}, []);

Initialize the Smile ID SDK in your app entry point by calling initialize method

  /**
   * Initialize SmileID SDK with configuration
   * @param useSandBox - Configuration object for the SDK
   * @param enableCrashReporting - Whether to enable crash reporting
   * @param config - Configuration object for the SDK
   * @param apiKey - api key specific to the partner and also environment
   */
  initialize(
      useSandBox: boolean,
      enableCrashReporting: boolean,
      config?: SmileConfig,
      apiKey?: string,
  ): Promise<void>;

The Smile ID Expo SDK offers three flexible initialization methods to suit different development needs.

import { initialize, SmileConfig } from 'react-native-expo';

Option 1: Configuration File (Recommended)

This method uses a smile_config.json file containing your configuration settings.

Setup Requirements:

iOS: Add smile_config.json to your copy bundle phases in your iOS target
Android: Place smile_config.json in your assets folder

// Initialize using configuration file
initialize(true);

Option 2: Programmatic Configuration

// Create configuration object with your Smile ID portal credentials
const config = new SmileConfig(
  'your_partner_id',              // Partner ID from Smile ID portal
  'your_auth_token',              // Authentication token
  'https://prod-lambda-url.com',  // Production lambda URL
  'https://test-lambda-url.com'   // Test lambda URL
);

// Initialize with configuration object
initialize(true, true, config);

Option 3: Configuration with API Key

// Use the same config object from Option 2
const config = new SmileConfig(
  'your_partner_id',
  'your_auth_token', 
  'https://prod-lambda-url.com',
  'https://test-lambda-url.com'
);

// Initialize with configuration and API key
initialize(false, true, config, 'YOUR_API_KEY'); // false for production, true for sandbox

Callback URL

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

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

Environments (Sandbox/Production)

To switch between Sandbox and Production you should initialize using:

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

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

In all three initialization methods, the first parameter, useSandBox of the initialize function determines the environment. Setting it to true enables the production environment, while false enables the sandbox environment.

initialize(true)

Usage

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.

SDK SwiftUI Screens

All product screens in the iOS SDK 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.

Using the SDK in an Objective-C Project

Objective-C does not support SwiftUI directly, as SwiftUI is tightly integrated with Swift's type system and runtime. To work around this, you need to use a Swift wrapper that embeds SwiftUI views inside a UIViewController using UIHostingController.

Steps

1. Create a Swift View Controller Wrapper

To use SwiftUI views in Objective-C, create a Swift class that embeds the SwiftUI view inside a UIHostingController.

Example:

import SmileID
import SwiftUI
import UIKit

@objcMembers
class SelfieCaptureViewModel: NSObject, @preconcurrency SmartSelfieResultDelegate {
    func didSucceed(selfieImage: URL, livenessImages: [URL], apiResponse: SmartSelfieResponse?) {
        // control your application with this responses
        print(selfieImage)
        print(livenessImages.map { $0 })
        print(apiResponse?.code ?? "")
    }

    @MainActor func didError(error: any Error) {
        // handle errors
        print(error.localizedDescription)
        UIApplication.shared.windows.first?.rootViewController?.dismiss(animated: true)
    }
}

@objcMembers
class SelfieCaptureViewController: UIViewController {
    let viewModel: SelfieCaptureViewModel = SelfieCaptureViewModel()

    override func viewDidLoad() {
        super.viewDidLoad()

        embedSwiftUIView()
    }

    private func embedSwiftUIView() {
        let smartSelfieView = SmileID.smartSelfieEnrollmentScreen(delegate: viewModel)
        let viewController = UIHostingController(rootView: smartSelfieView)
        let swiftUIView = viewController.view!

        // Standard UIKit View setup
        swiftUIView.translatesAutoresizingMaskIntoConstraints = false
        swiftUIView.backgroundColor = .white

        addChild(viewController)
        view.addSubview(swiftUIView)
        
        // Constrain the view however you want
        NSLayoutConstraint.activate([
            swiftUIView.topAnchor.constraint(equalTo: view.topAnchor),
            swiftUIView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            swiftUIView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            swiftUIView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
        ])

        viewController.didMove(toParent: self)
    }
}

Applying @objcMembers to SelfieCaptureViewController and SelfieCaptureViewModel ensures that all explicitly defined members are exposed to the Objective-C runtime, avoiding the need to manually annotate each method or property with @objc.

2. Expose Swift Classes to Objective-C

To enable Objective-C to recognise and use Swift classes in a mixed-language project, you need to create a Bridging Header. This header file acts as a link between the two languages, allowing Swift symbols to be exposed to Objective-C.

If you already have a bridging header file and at least one Swift file working in your project you can skip this step.

Automatic Approach: If you don't previously have any Swift file in your project, Xcode can automatically setup the bridging header file for you.

Add a new Swift file to any folder in your Objective-C project and you should get the dialog shown in the image below:

Click "Create Bridging Header" option and you should now have a Bridging Header in your project for Objective-C and Swift interoperability.

Manual Approach: You can also follow these steps to create and configure it manually:

In Xcode, go to File > New > File....
Choose Header File and name it YourProjectName-Bridging-Header.h
Add the following import statement in the bridging header:
```
#import "YourProjectName-Swift.h"
```
In Build Settings, find Objective-C Bridging Header and set its value to the path of your header file (YourProjectName/YourProjectName-Bridging-Header.h).

3. Use the Swift Wrapper in Objective-C

Once your Swift wrapper is properly set up and exposed to Objective-C, you can treat it like any other UIViewControllerwhen instantiating and presenting it in your Objective-C codebase. Now you can instantiate and present the SwiftUI view controller in Objective-C:

Example:

#import "ViewController.h"
#import "ExampleObjc-Swift.h"

@import SmileID;

@interface ViewController ()

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
}

// your other view controller code.

- (void)showSmartSelfieCapture {
    SelfieCaptureViewController *selfieVC = [[SelfieCaptureViewController alloc] init];
    UINavigationController *navController = [[UINavigationController alloc] initWithRootViewController:selfieVC];
    [navController setModalPresentationStyle:UIModalPresentationFullScreen];
    [self presentViewController:navController animated:YES completion:nil];
}

// ...

Additional Resources

For more information on importing Swift into Objective-C, refer to the official Apple documentation: Importing Swift into Objective-C

We have also put together a sample Objective-C project you can look at for inspiration.

Networking

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.

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.

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

Troubleshooting

Please see the troubleshooting guide here for situations where the camera is loading in full screen.

PreviousMobile NextProducts

Last updated 3 months ago

Was this helpful?

Requirements

SDK Versions

Dependency

Smile Config

Initialization

Callback URL

Environments (Sandbox/Production)

Usage

Networking

Checking Job Status

Crash Reporting (Android only)

Submitting to the App Store (iOS Only)

Resources

File Handling (Android only)

Troubleshooting

Camera / webView related issues