Getting Started

Installation and Initialization



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


Proguard rules are shipped with the SDK

If you use Dexguard, add the following rule

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

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


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


import com.smileidentity.SmileID

class ExampleApplication : Application() {
    override fun onCreate() {

Callback URL

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


Environments (Sandbox/Production)

To switch between Sandbox and Production you should initialize using:

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



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 based wrappers around the Composables. You should use getSupportFragmentManager().setFragmentResultListener(...) to listen for results. Examples are provided for each product.


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.

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


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

Last updated