Swiftpack.co - unissey/sdk-ios as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by unissey.
unissey/sdk-ios v3.0.0
Unissey iOS SDK
⭐️ 0
🕓 6 weeks ago
.package(url: "https://github.com/unissey/sdk-ios.git", from: "v3.0.0")

Unissey logo

Unissey iOS/macOS SDK

GitHub release (with filter)

This iOS/macOS Framework provides an easy way to obtain a video selfie to be used with Unissey's SaaS solution on an iOS or macOS application. This SDK has been developed with SwiftUI, allowing for an easy integration on both SwiftUI apps and traditional UIKit apps.

1. Installation & requirements

1.1 Requirements

The version of your app must be at least iOS 14.0 and macOS 11.0 in order to use this SDK.

1.2 Installation

If you already have Xcode configured with a GitHub personal access token with the proper permissions, you can skip directly to the third step of the installation.

1.2.1 Get a GitHub personal access token

First, you need to generate an access token by following the instructions provided here by GitHub. Make sure to include at least the repo and read:packages permissions.

Then, to gain access to Unissey's SDK, you need to contact the Unissey team and provide your GitHub account name.

1.2.2 Add you GitHub account on Xcode

Open Xcode, open the Settings window (CMD + ,) and go to the second tab Accounts. Add a new account by clicking on the + button on the bottom left corner, select GitHub and add your GitHub account's email and the personal access token you generated previously.

1.2.3 Download the framework

Finally, you can download our framework using the Swift Package Manager. To do so, in Xcode, go to File -> Add Packages... and enter the following URL in the search bar: https://github.com/unissey/sdk-ios. There Xcode will let you define the dependency rule. You can choose a specific version of your choice or use the latest version available that should be on the master branch.

2. Getting started

2.1 Overview

Unissey's SDK offers three screens, one of which is optional:

  1. If you choose to, the user is greeted with a screen displaying instructions on what to do to ensure our algorithms are delivering the best results possible.
  2. Then, if your application hasn't already asked for the user's permission to use the camera, a screen presenting a brief explanation on why the app requires the use of the camera is displayed. A button on this page will make the system dialog appear to request the user's consent to let the app use the camera. If the user happens to decline, subsequent clicks on this button will redirect to the settings page where the user will have to manually grant permission to the camera.
  3. Finally, if the permission has been granted, the main screen is displayed featuring a live preview of the camera. This screen provides a button (or none if you choose to hide it) that starts the video capture process. This process is divided in two steps. The SDK will start by detecting the user's face and providing indications, based on the face's location, to help the user position their face in the center of the frame. Once it's done and the user stayed still for at least one second, the actual video recording will start for the duration you specified with the Acquisition Preset.

The sample apps are here to provide a basic implementation of this library that you can use as a base for your integration inside your own application. Whether you're using SwiftUI or a traditional approach with UIKit, you will have to create a UnisseyViewModel and a UnisseyScreen to interact with this SDK. The UnisseyViewModel is the developer interface with which you can interact in your application's code, it's also the class that you can configure to suit your needs. The UnisseyScreen on the other hand holds the user interface and it's what your user will see and interact with.

2.2 UnisseyViewModel

The UnisseyViewModel class offers a constructor that should be used to create an instance of it. Only an AcquisitionPreset object and an OnRecordEndedListener are necessary to use the SDK. Note that the OnRecordEndedListener is optional during the initialization of the UnisseyViewModel since, most of the time, you're going to want to reference self inside your callback to handle the result, and there are situations where you will not be able to reference self when initializing the object. This field is still mandatory for the SDK to hand back a response, if you fail to provide an OnRecordEndedListener, the user will get stuck at the end of the video acquisition.

In addition to those parameters, the SDK can be further customized with an OnStateChangedListener and a SessionConfig. All of these parameters are detailed in the Reference section.

See the following code for simple usages where the default values are suitable for your use case:

let unisseyViewModel = UnisseyViewModel(acquisitionPreset: .selfieFast, onRecordEndedListener: { result in
    do {
        // `result` is a Result<Success, Failure> containing the response or an error
        let response = try result.get()
        print("Video record ended with file path: '\(response.videoFilePath)'")
    } catch {
        print("An error occurred while recording the video: \(error)")

2.3 UnisseyScreen

Once you have an instance of UnisseyViewModel, you can create the UnisseyScreen with the ViewModel as a parameter.

2.3.1 SwiftUI

In SwiftUI, you can use the UnisseyScreen as you would use any other View in your application:

struct ContentView: View {
    var body: some View {
        let unisseyViewModel = ...
        UnisseyView(unisseyViewModel: unisseyViewModel)

2.3.2 Traditional UIKit app

If your application is built with the older Storyboard and UIKit system, you can rely on a UIHostingController to host the SwiftUI UnisseyView. If you're not familiar with this class, it's a view controller that encapsulates and manages a SwiftUI hierarchy. You just need to provide a SwiftUI view as the rootView parameter when initializing your hosting controller:

import Foundation
import SwiftUI
import UnisseySdk

class UnisseyHostingController: UIHostingController<UnisseyView> {
    var videoUri: URL?
    let unisseyViewModel: UnisseyViewModel
    required init?(coder: NSCoder) {
        // Set up the UnisseyViewModel and UnisseyView
        unisseyViewModel = UnisseyViewModel(acquisitionPreset: .selfieFast)
        let unisseyView = UnisseyView(unisseyViewModel: unisseyViewModel)
        super.init(coder: coder, rootView: unisseyView)
    override func viewDidLoad() {
        // Register the callback
        unisseyViewModel.onRecordEndedListener = { result in
            do {
                // `result` is a Result<SessionResponse, Error> containing the response or an error
                let response = try result.get()
                print("Video record ended with file path: '\(response.videoFilePath)'")
                self.videoUri = response.videoFilePath
                DispatchQueue.main.async {
                    // Navigate to the next screen
            } catch {
                print("An error occurred while recording the video: \(error)")

You can use this UIHostingController as you would use any standard UIViewController in your storyboard:


3. Reference

3.1 AcquisitionPreset

The present SDK provides presets defining how the video is recorded. Even if you decide to override its values, you must select a preset when creating an instance of UnisseyViewModel. Here are the 2 current possible values of AcquisitionPreset:

Preset name Recording duration Video quality Description
selfieFast 1 second 480p resolution if possible, or 720p The preset that most use cases rely on. It provides the minimal configuration needed for Unissey's AI models to work at their best
selfieSubstantial 3 seconds 720p resolution if possible, or 1080p The preset fit for use cases aiming for a PVID substantial compliance

3.2 OnRecordEndedListener

This is the callback that triggers when the user is done recording a video.

This is a type alias for (Result<SessionResponse, Error>) -> Void.

The SessionResponse:

Parameter name Type Description
videoFilePath URL The path to the video file saved in the cache directory of your app
metadata String A String containing technical metadata useful to Unissey to be added to the request to Unissey's API

3.3 OnStateChangedListener

This is a callback that triggers everytime there's a significant change of state while the user is interacting with the SDK. This callback offers a possibility for your application to react to SDK and user events while the SDK is being used. This allows for more advanced usages that you could have, some of which are described in the Advanced usages section.

This is a type alias for (UnisseyEvent) -> Void.

A UnisseyEvent represents an event happening inside the SDK, often initiated by the user. Here's an exhaustive list of possible events:

Event Description
instructionsShown When the Instructions screen is displayed to the user
cameraPermissionShown When the Camera Permission screen is displayed to the user. This screen provides a simple explanation as to why this permission is necessary
cameraPermissionRequested When the camera permission has been requested, meaning when the system alert is being displayed to the user
cameraPermissionAccepted When the user has accepted the permission
cameraPermissionDenied When the user has declined the permission
cameraPreviewShown When the Video Capture screen is displayed, showing a live preview of the camera
cameraReady There is an initialization delay before the camera is fully set up and available. This event fires when the camera is actually ready to record a video.
videoCaptureStarted When the video capture has started. The term "video capture" refers to the process that begins when the user hits the "Start" button. The recording doesn't start right away, there's a first stage where a face detection is happening to help the user position their face in the oval
videoRecordStarted When the recording has started
videoRecordProgress This event is the only one to feature a parameter. It fires multiple times during the recording and provides a progress parameter indicating the recording progress with a value contained between 0 and 1 (1 being 100%)
videoRecordEnded When the recording is over. This event triggers along with the OnRecordEndedListener callback

3.4 SessionConfig

If the default state of the SDK doesn't suit your needs, the UnisseyViewModel can take a SessionConfig parameter with ways to customize the behavior of the library.

Here's what a SessionConfig is composed of:

Parameter name Type Description
recordingConfig RecordingConfig A nested configuration object meant for technical configuration
uiConfig UiConfig A nested configuration object meant for graphic configuration

The RecordingConfig:

Parameter name Type Default value Description
recordingDurationMs Float? nil The duration of the recording, overrides the value from the AcquisitionPreset
qualities [VideoQuality] nil An array of VideoQuality to override the qualities set in the AcquisitionPreset. The qualities are to be set in order of preference

The VideoQuality is an enum representing available qualities that the video can be recorded in:

Quality Resolution
lowest 144p
sd 480p
hd 720p
fhd 1080p
uhd 2160p
highest The highest resolution possible on the user device

⚠️ NOTE: When providing custom qualities to override the preset, you should make sure to provide plausible fallback values to support as many devices as possible. If no provided quality is available on the user's device, an error will be thrown on the OnRecordEndedListener callback.

The UiConfig:

Parameter name Type Default value Description
showInstructions Bool true Specify whether to show the first instructions screen or not
showVideoCaptureButton Bool true Specify whether to show the "Start" button on the video capture screen or not. This is mainly useful if you choose to enable auto-starting of the video capture, as explained in the Auto-starting the video capture section
showWideWindowPreviewInputsToTheRight Bool true Specify whether the preview inputs should be displayed to the right of the camera preview or to the left in wide window mode (typically on phones in landscape mode)

3.5 UnisseyViewModel's public variables and functions

A few variables and functions in the UnisseyViewModel are accessible in read or write mode from the client's application. Here's the exhaustive list:

Name Type Description
currentPage UnisseyPage (read only) Indicates which screen is being displayed to the user. It's an enum with values comprised in instructions, cameraPermission and videoCapture
navigateUp Function Tells the UnisseyViewModel to navigate one screen up
startVideoCapture Function Tells the UnisseyViewModel to start the video capture process. Useful when you want the video capture to autostart when the screen appears for example

3.6 String resources

Here's an exhaustive list of the String resources used in the SDK and that can be overridden (see the Customizing the texts and translations section to know how to override them):

Key English value French value
unissey_instructions_title Record a short video selfie Enregistrez un selfie vidéo
unissey_instructions_subtitle Let's make sure no one is impersonating you. Cette étape permet de vérifier que personne n'usurpe votre identité
unissey_instruction_maintain_stable_position Look straight at the camera, and keep your face clearly visible Maintenez votre visage droit et entièrement visible
unissey_instruction_plain_expression Have a plain expression Conservez une expression neutre
unissey_instruction_well_lit_environment Stand in a well-lit environment Assurez-vous d’être suffisamment éclairé
unissey_continue_label Continue Continuer
unissey_camera_permission_explanation The camera permission is required for this feature to be available. Please grant the permission. L'utilisation de la caméra est nécessaire à cette fonctionnalité. Merci d'autoriser l'usage de la caméra.
unissey_camera_permission_button Request permission Donner la permission
unissey_video_capture_title The acquisition will last %d second(s). L'acquisition durera %d seconde(s).
unissey_start_label Start Commencer
unissey_instruction_position_face_oval Position your face in the oval Placez-vous dans l'ovale
unissey_instruction_multiple_faces_detected Multiple faces detected Plusieurs visages détectés
unissey_instruction_no_face_detected No face detected Aucun visage détecté
unissey_instruction_get_closer Get closer Rapprochez-vous
unissey_instruction_get_further_away Get further away Reculez-vous
unissey_instruction_move_right Move your face to the right Plus vers la droite
unissey_instruction_move_left Move your face to the left Plus vers la gauche
unissey_instruction_move_up Move your face up Plus vers le haut
unissey_instruction_move_down Move your face down Plus vers le bas
unissey_instruction_do_not_move Perfect, don't move Parfait, ne bougez plus

3.7 Colors

This SDK offers a few Color assets to theme its UI elements that can be overridden (see Customizing the assets (colors and images) section to know how to override them).

Here's the exhaustive list of colors used in the SDK along with their default values corresponding to the Unissey color theme:

Key Default light mode value Default dark mode value
UnisseyCardBackground #F6F6F6 #48454F
UnisseyOverlayBackground #FFFFFF - 80% opacity #000000 - 80% opacity
UnisseyPrimary #09165C #3C58E8
UnisseySecondary #3C58E8 #3C58E8

3.8 Images

This SDK contains three customizable images (see Customizing the assets (colors and images) section to know how to override them). Those images illustrate the three instructions on the first optional screen.

Here's the exhaustive list of images:

Key Description
UnisseyFacePositionPicto The first illustration showing how to position the user's face
UnisseyFaceExpressionPicto The second illustration indicating to have a neutral expression
UnisseyFaceLightPicto The third illustration that displays that a good lighting is necessary

3.9 Typography

The SDK provides customizable fonts used throughout the three screens ( see Customizing the types section to know how to override them). Those are SwiftUI fonts that follow default text styles, allowing them to scale automatically with the user's accessibility settings.

Here's the exhaustive list of types along with their default values:

Parameter name Default family Default weight Default Text Style
unisseyHeadline System Default Bold Font.title
unisseyTitle System Default Bold Font.title3
unisseyBody System Default Normal Font.body
unisseyLabel System Default Medium Font.body

4. Advanced usage

4.1 Specifying a SessionConfig

To give you an idea of how you can customize the SDK to fit your needs using the SessionConfig, here's an example use case. Say you're happy with the SDK but you'd rather have your own instructions page, to make sure it fits your UI Design. And you want the video recording to last 2 seconds instead of the default 1 second of the SelfieFast preset, for whatever reason.

You could leverage the SessionConfig to achieve this:

let recordingConfig = RecordingConfig(recordingDurationMs: 2000)
let uiConfig = UiConfig(showInstructions: false)
let sessionConfig = SessionConfig(recordingConfig: recordingConfig, uiConfig: uiConfig)

let unisseyViewModel = UnisseyViewModel(acquisitionPreset: .selfieFast,
                                        sessionConfig: sessionConfig) { result in

4.2 Customizing the texts and translations

The Unissey SDK provides various default English texts as well as a French translation that you can choose to leave as they are. However you're free to override any or all of them through the Localizable.strings and Localizable.stringsdict resource file if they're not fit for your needs.

To do this, you just need to add a line in your Localizable.strings for each text you want to override. An exhaustive list of the texts you can redefine is available in the String resources section. You can redefine any language and even define your own that isn't English or French. All of our strings' keys are prefixed with "unissey" to prevent any conflict with the naming of your own string resources.

There is a special case for the unissey_video_capture_title string. Because the string can be pluralized according to the duration of the video, it's defined in a separate file of type .stringsdict that allows this pluralization out of the box.

Here's our definition of this string, were you to override it:

            <string>The acquisition will last %lld seconds.</string>
            <string>The acquisition will last %lld second.</string>
            <string>The acquisition will last %lld seconds.</string>

And here's the view from Xcode:


Example: Overriding the Instructions screen's title

"unissey_instructions_title" = "My custom title inside Unissey's SDK";

4.3 Customizing the assets (colors and images)

This SDK exposes some colors and images in its Assets.xcassets directory. They can be freely overridden by just providing your own colors and images using the same keys as the ones defined in the Framework and detailed in the Colors and Images sections.


4.4 Customizing the types

This SDK is using the default system fonts. It exposes a number of variables that can be overridden by the client's application, which are all listed in the Typography section. To override a type, you just need to redefine the corresponding value anywhere in your application before you create the UnisseyScreen. You can have a look at the official documentation to see how to define and import custom fonts in your application.

Example: Let's say you want to change the font family to "Futura" which should be present on iOS devices by default. You just need to write this function and call it somewhere before UnisseyScreen is instantiated, it could be in your app's initializer for example:

import SwiftUI
import UnisseySdk

struct MyAwesomeSwiftUiApp: App {
    init() {
    var body: some Scene {
        WindowGroup {

func customizeUnisseyTypography() {
    unisseyHeadline = Font.custom("Futura", size: 24, relativeTo: .title).weight(.bold)
    unisseyTitle = Font.custom("Futura", size: 18, relativeTo: .title3).weight(.bold)
    unisseyBody = Font.custom("Futura", size: 16, relativeTo: .body)
    unisseyLabel = Font.custom("Futura", size: 16, relativeTo: .body).weight(.medium)

⚠️ NOTE: Do not forget to import UnisseySdk to gain access to the typography variables. Note that the example makes use of the SwiftUI Font.custom() function to apply a font supporting dynamic sizing to match the user's accessibility settings in terms of font size, as explained in the official documentation.

4.5 Auto-starting the video capture when the camera's ready

This SDK provides an OnStateChangedListener that you can leverage to achieve more advanced behavior. One good example of advanced usage would be to use this listener, along with the public function startVideoCapture(), to auto-start the video capture when the camera is ready, so that the user doesn't have to click on the "Start" button.

First of all, you're going to hide the "Start" button which doesn't make any sense if we want the video to be captured right away. Then, you need to implement an OnStateChangedListener and trigger the startVideoCapture() function when the SDK's state becomes cameraReady.

Here's how you could do that in SwiftUI:

struct ContentView: View {
    var body: some View {
        let unisseyViewModel = createUnisseyViewModel()
        UnisseyView(unisseyViewModel: unisseyViewModel)
    func createUnisseyViewModel() -> UnisseyViewModel {
        let sessionConfig = SessionConfig(uiConfig: UiConfig(showVideoCaptureButton: false))
        let unisseyViewModel = UnisseyViewModel(acquisitionPreset: .selfieFast, sessionConfig: sessionConfig) { result in
        unisseyViewModel.onStateChangedListener = { state in
            if case .cameraReady = state {
        return unisseyViewModel

We're creating the UnisseyViewModel in a dedicated function to avoid the Type '()' cannot conform to 'View' error in SwiftUI when trying to assign an OnStateChangedListener on our UnisseyViewModel.

Note that doing it in UIKit is pretty much exactly the same as in SwiftUI.

5. Common issues

5.1 Add camera requirement to your application

To use this SDK on macOS, you need to provide an entitlement file specifying that your application can interact with the built-in and external cameras, as per the official documentation.

On iOS, you must provide a value for the key NSCameraUsageDescription. Note that this is the text that will be displayed in the system alert once the user clicks on the Request permission button, if the camera permission hasn't been granted before the use of the SDK. If you fail to provide this information, the application will crash when the use tries to grant the camera access.


Stars: 0
Last commit: 6 weeks ago
Advertisement: IndiePitcher.com - Cold Email Software for Startups

Release Notes

6 weeks ago

This version is a full refactor of Unissey's iOS Framework. It features, as the previous one, an instructions page, a camera permission request page as well as a page dedicated to capture a video selfie.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics