LogoLogo
  • Welcome!
  • GETTING STARTED
    • Signing Up
    • Choose a Product
    • Choose an Integration Option
    • Run Your First Test Job
    • Complete Your KYC
    • Fund Your Wallet
    • Go Live!
    • Pricing
  • SUPPORTED ID TYPES & DOCUMENTS
    • For Individuals (KYC)
      • Using ID Number
        • Supported Countries
          • Côte d'Ivoire
            • National ID (without Photo)
            • Resident ID (without Photo)
          • Ghana
            • Ghana Card
            • Passport
            • Voter's ID
          • Kenya
            • Alien Card
            • KRA Pin
            • National ID
            • National ID (without Photo)
            • Passport
            • Tax Information
          • Nigeria
            • Bank Account
            • BVN
            • NIN V2
            • NIN Slip Verification
            • V_NIN (Virtual NIN)
            • Phone Number
            • Voter's ID
          • South Africa
            • National ID
            • National ID (without Photo)
            • Phone Number
          • Uganda
            • National ID (without Photo)
            • Basic KYC in Uganda
          • Zambia
            • Bank Account
            • TPIN
          • Zimbabwe
            • National ID (without Photo)
        • Test Data
          • Customising Sandbox Test Data
        • ID Number Regex
        • Visual Samples of Supported ID Types
      • Using Document Image
        • Continents
          • Africa
          • Asia and the Middle East
          • Europe
          • North America
          • Oceania
          • South America
    • For Businesses (KYB)
      • Supported Countries
        • Nigeria
          • Business Registration
          • Tax Information
        • Kenya
          • Business Registration
        • South Africa
          • Business Registration
      • ID Number Regex
  • PRODUCTS
    • For Individuals (KYC)
      • AML Check
        • AML News Media
      • Basic KYC
      • Biometric KYC
      • Digital Address Verification
      • Document Verification
        • Document Verification
        • Enhanced Document Verification
      • Electronic Signature
      • Enhanced KYC
      • Phone Number Verification
      • SmartSelfie™ Authentication
      • SmartSelfie™ Compare
      • Smile Secure
    • For Businesses (KYB)
      • Business Verification
  • Integration Options
    • Mobile
      • Getting Started
      • Products
        • Biometric KYC
        • BVN Consent
        • Document Verification
        • Enhanced Document Verification
        • Enhanced KYC
        • SmartSelfie™ Enrollment and Authentication
        • Enhanced SmartSelfie™ Enrollment And Authentication
      • Customization
        • UI Components
      • Offline Mode
      • Release Notes
        • Android Release Notes
        • iOS Release Notes
        • Flutter Release Notes
        • React Native Release Notes
    • No-Code
      • Smile Links
        • Link FAQs
        • Rest API
    • Server to Server
      • Ruby
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
          • KYB - Business Verification
          • AML Check
        • Generate Token for Web Integration
        • Utilities
      • Python
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
          • Business Verification
        • Generate Token for Web Integration
        • Utilities
      • Java
        • Release Notes
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
        • Generate Token for Web Integration
        • Utilities
      • Node.js
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • Enhanced Document Verification
          • SmartSelfie™ Authentication
          • Business Verification
        • Generate Token for Web Integration
        • Utilities
      • PHP
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
        • Generate Token for Web Integration
        • Utilities
    • Rest API
      • Signing your API Request
        • Using Signature
      • Products
      • Postman Collection
      • Utilities
    • Web / Mobile Web
      • Web Integration
        • Installation
        • Usage
        • End User Consent
        • Support
      • Javascript SDK
        • Installation
        • Usage
        • Migration
        • Deprecated Version
          • Installation
          • Usage
          • Notes
          • Support
  • FURTHER READING
    • FAQs
      • What are your support hours?
      • How do I set up a callback?
      • How to re-enroll, deactivate or delete a user?
      • Add or remove team members
      • What are top-level keys?
      • What are partner_params?
      • How do job types map to the new product names?
      • Is there an API I can use to monitor my wallet balance?
      • Is there an API I can query to check the availability status of an ID type?
      • How do I integrate Smile ID in other countries or query other ID types?
      • What are the image types I can upload to Smile ID?
      • Why aren't Kenyan IDs returning images for some IDs queried?
      • Why are some of my bank verification requests returning 'ID authority unavailable'?
      • How can I look up a specific user's data?
      • Selfie best-practices
      • Document capture best-practices
      • What happens under the hood?
      • Guide to the user consent screen
      • What is code 2302?
      • Using the Demo App and Scanning QR codes
    • Job status
    • KYC receipts
    • Result codes
      • Error codes
    • Securing your account with two-factor authentication (2FA)
    • Security Overview
    • Troubleshooting
      • Troubleshooting error 2204 & 2205 - "You're not authorized to do that"
      • Why is my Web API job taking so long?
      • Image capture issues on web client
Powered by GitBook
On this page
  • Requirements
  • Dependency
  • Smile Config
  • Initialization
  • Environments (Sandbox/Production)
  • Usage

Was this helpful?

  1. Integration Options
  2. Mobile

Getting Started

Installation and Initialization

PreviousMobileNextProducts

Last updated 1 month ago

Was this helpful?

Requirements

  • Android 5.0+ (API level 21+)

  • A smile_config.json file from your portal page

  • iOS 13+

  • Xcode 14+

  • A smile_config.json file form your portal page

  • Flutter 3.0.0+

  • Dart 3.0.5+

  • Android 5.0+ (API level 21+)

  • iOS 13.0+

  • A smile_config.json file from your portal page

  • [^1]

  • React Native 0.70.+

  • Android 5.0+ (API level 21+)

  • iOS 13.0+

  • A smile_config.json file from your portal page

Dependency

The latest release is available on and on .

Snapshot builds are also .

Add the dependency to your module-level Gradle Build file

implementation("com.smileidentity:android-sdk:<latest-version>")
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
  1. In Xcode, select File > Add Packages… and enter

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

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

  • If you don’t have an existing , 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

Add the dependency to your pubspec.yaml

dependencies:
  smile_id: <latest-version>

The latest release is available on

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

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

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

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

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)

iOS

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

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'); 
}, []);

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"))
SmileID.setCallbackUrl(url: URL(string: "https://smileidentity.com"))
SmileID.setCallbackUrl(callbackUrl: Uri.parse("https://smileidentity.com"));
SmileID.setCallbackUrl("https://smileidentity.com");

Environments (Sandbox/Production)

To switch between Sandbox and Production you should initialize using:

SmileID.initialize(context = this, useSandbox = true)
SmileID.setEnvironment(useSandbox: true)
SmileID.setEnvironment(useSandbox: true);
SmileID.setEnvironment(true); //true if running on sandbox false if running production

Usage

Javadoc

SDK SwiftUI Screens

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:

  1. In Xcode, go to File > New > File....

  2. Choose Header File and name it YourProjectName-Bridging-Header.h

  3. Add the following import statement in the bridging header:

    #import "YourProjectName-Swift.h"
  4. 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

Networking

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.

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)

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

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:

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.

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:

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.

Drag the [^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.

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

Drag the [^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 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 to use the bundled version which fixes the exception.

The latest Javadocs can be found

All are implemented using 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.

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 and presenting or pushing the views using UIKit's ViewController presentation mechanisms.

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

We have also put together a sample you can look at for inspiration.

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 for further details.

Please refer to the on SmileIDCrashReporting for further details.

⚠️
⚠️
⚠️
⚠️
⚠️
⚠️
⚠️
⚠️
https://developer.android.com/jetpack/androidx/releases/compose-kotlin
https://developer.android.com/jetpack/androidx/releases/compose-kotlin
here
here
Products
Jetpack Compose
androidx.fragment.app.Fragment
UIHostingController
Importing Swift into Objective-C
Objective-C project
Javadoc
Javadoc
smile_config.json file
smile_config.json file
⚠️
⚠️
⚠️
Security Settings
Security Settings
Security Settings
Security Settings
Maven Central
GitHub
available
https://github.com/smileidentity/ios
CocoaPods
Podfile
pub.dev
npm
A device with Google Play Services
A device with Google Play Services
Xcode Bridging Header Dialog