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
⚠️ Note the Compose to Kotlin Compatibility Map here - https://developer.android.com/jetpack/androidx/releases/compose-kotlin
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
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.
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
}
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[^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.
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
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.
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');
}, []);
Callback URL
To set the callback URL used for jobs (to deliver results to your own server), use the setCallbackUrl method
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:
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.
It is advisable not to set the requestTimeout below the value of SmileID.defaultRequestTimeout, to avoid premature timeouts in slow network conditions.
You can make network requests to the Smile ID backend using the SmileIDService class, accessible by calling SmileID.api
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
