Mobile SDK - iOS
Docs for the Android SDK are here.
This is a lightweight, fully native SDK that allows a host app to receive and store
Before you begin: You need to be registered as Unum ID customer, and you need to register at least one
#
Overview#
Minimum Requirements- iOS 13 and above
- English language (internationalization coming soon)
#
Required Permissions- Camera: requested when you show the QR code scanner
- Biometrics/Passcode: requested when you call
initialize()
These permissions are requested by the SDK โ no action is required by the host app.
Because the SDK leverages the secure hardware of the user's device for cryptographic operations, it requires OS level user authentication. This means the user must have a lock screen biometric or passcode If the user doesn't have this set up, the SDK will prompt the user and direct them to the correct place in Settings to do so.
note
Device biometrics are typically aliases for passcodes (or similar options like PINs and patterns) and fall back to those. This is all handled at the OS level.
#
SetupInfo.plist
#
Because the SDK requires camera and biometric/passcode permissions, you need to add descriptions like these to the Info.plist
file:
#
Privacy - Camera Usage DescriptionThis app would like to use the camera for QR code scanning.
#
Privacy - Face ID Usage DescriptionThis app would like to use Face ID for authorization.
#
Privacy - Touch ID Usage DescriptionThis app would like to use Touch ID for authorization.
#
InstallationWhen you register a
#
Access to Current View ControllerThe SDK needs access to the current view controller to show system alerts to the user (this is essential for the SDK to work). So, you should always pass the this to the SDK like so:
#
InitializationYou should initialize the SDK when the app starts up. This will ensure the SDK is set up properly.
You can optionally include a did
), which identifies a user (technically called a
You can optionally include the UnumCallback
to be notified of the result of the initialization call.
After a user has successfully log in to the host app, and initialization call should be made to the SDK. The host app should store a reference to the user DID so that it can be passed to the initialization call. If a DID is not provided a new one will be created and returned.
The initialization process involves creating private keys for the user using the secure hardware of the device. This requires OS level authentication, so the user will be prompted to pass a biometric check or enter their passcode. If they don't have this set up, the SDK will direct them to the correct place in Settings to do so.
#
Deep LinksIn the context of Unum ID, a deep link is a URL that opens a specific
The SDK uses deep links to retrieve and display a
You need to pass Unum ID deep links to the SDK to be processed. To do so, set up your host app to receive the appropriate schemas. (You can optionally add logic to determine if the deep link should be passed to the SDK.) Do this in the Target -> Info tab.
Here's an example of sending the deep link to the SDK in SceneDelegate
:
When it receives a deep link, the SDK will display a system alert, asking the user how they want to respond to the
#
QR Code ScannerThe Unum ID deep links described above can be displayed in QR code form. This is important for cases when a user is on a non-mobile device. For example, the ACME Bank website might request that a user share an authentication credential to log into the ACME website on desktop. ACME would do so by displaying a QR code that the user scans. This would open the ACME mobile app on the user's phone and prompt the user to share the requested data.
Any QR code scanner can read an Unum ID deep link in QR code form. iOS devices support scanning directly from the native camera, but you should also allow the user to scan codes from within your app.
If you already have a QR code scanner, you can pass QR codes directly to the SDK like so:
If you don't have a QR code scanner, you can use the one included in the SDK. This will automatically pass the deep link to the SDK โ no further action is needed from the host app.
You can open this on a trigger of your choice. For example, you can create a "Scan QR Code" button that opens the scanner when the user clicks it:
#
LoggingYou can turn SDK logging on and off and set the log level:
#
CallbackYou can pass the UnumCallback
to most method calls within the SDK. This adds a listener that records the result of the method call โ a successful call, an SDK error, or an API error. The Initialization section shows one example of this, and here's another:
#
Handling Multiple UsersEach user is identified by some user ID in your system and by a
If you don't have existing user IDs, you could use the DIDs themselves as user IDs. However, we recommend using separate identifiers (internal to your company), to distinguish them from DIDs, which are global to the Unum ID ecosystem.
note
The technical details of DIDs are not relevant to deploying or using Unum ID. You can think of DIDs as identifiers in the normal sense โ unique, random strings of characters like UUIDs.
note
The technical details of DIDs are not relevant to deploying or using Unum ID. You can think of DIDs as identifiers in the normal sense โ unique, random strings of characters like UUIDs.
When you initialize the SDK, you can optionally include a DID.
- Don't include a DID for a user who's new to the SDK. The SDK will generate a new one that you should store, associated with the user ID in your system.
- Do include a DID for a user who returns to the SDK. The SDK will use this DID to access the correct stored data for that user.
important
DIDs are the only identifiers the SDK understands, so it relies entirely on the host app to pass the correct one.
For example, suppose Users 1 and 2 are associated with DIDs 1 and 2, respectively. If User 1 is using the host app, but the app passes DID 2 to the SDK, the SDK will give User 1 access to to User 2's data.
#
Example Flow- New User 1 logs into host app.
- SDK is initialized with no DID.
- SDK returns newly generated DID 1.
- Host app stores DID 1 and associates it with User 1.
- New User 2 logs into host app.
- SDK is initialized with no DID.
- SDK returns newly generated DID 2.
- Host app stores DID 2 and associates it with User 2.
- Returning User 1 logs into host app.
- Host app retrieves DID 1 and includes it in SDK initialization.
- SDK recognizes this is a returning user and does not generate a new DID.