Docs for the iOS 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
More detailed but less styled documentation can be found here. This serves as a useful technical reference.
- Android 6.0 (Marshmallow) and above
- English language (internationalization coming soon)
- Camera: requested when you show the QR code scanner
- Biometrics/Passcode: requested when you call
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, passcode, or similar. 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.
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.
When you register a
In the top level build.gradle add your artifactory username, password, and artifactory url to the all projects block
In the app level build.gradle add the reference to the SDK
You 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.
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, enter their passcode, or authenticate in an analogous way. If they don't have this set up, the SDK will direct them to the correct place in Settings to do so.
In 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 an activity as shown below. This will catch a deep link like the example one shown above.
When it receives a deep link, the SDK will display a system alert, asking the user how they want to respond to the
The SDK will do the following based on the user's action. If the user clicks:
- "Yes": the SDK will send a A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.+ More...presentation (of the requested credentials) to the company that made the request.
- "No": the SDK will send an empty presentation that indicates that the user declined the request.
- "Something's wrong...": the SDK will flag the request as suspicious.
The 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. Some but not all devices support scanning directly from the native camera, so you should make it possible for 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. Simply start the QR code activity as shwon below. This will automatically pass the deep link to the SDK — no further action is needed from the host app.
You can call this on a trigger of your choice. For example, you can create a "Scan QR Code" button that starts the activity when the user clicks it:
The QR code scanner lookss like this:
You can turn SDK logging on and off and set the log level:
You 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:
Each 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.
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 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.
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.
- 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.