App Switching to the Unloc App
The Unloc app can be invoked using specific App Switch parameters in order to make it perform specific actions
The App Switch URL has the following format:
https://dl.unloc.app/**Action Name**
Keep in mind that each Action can have different required parameters.
Prefetch Keys for enhanced performance and offline support
Before the Unloc app is opened, all Keys remain unloaded. By using the Prefetch Keys app-switch, the Unloc app will download all keys, so that they are instantly available when required by the user later on. This is particularly useful when creating Keys in batches ─ for instance before a service person goes on a route with limited access to the internet or where door opening speed matters. The prefetch can be triggered once before the activity starts. A returnUrl must be provided to automatically redirect the user to the right place on the source app.
https://dl.unloc.app/prefetch-keys?returnUrl=<redirectURL>| Query parameter | Meaning |
|---|---|
| returnUrl | An URL to redirect the user on success. For instance yourapphandler://keys-fetched |
Example
When the following URL is opened on a mobile device, the Unloc app will be launched and all the existing Keys for the user will begin being downloaded to the device (making them available off-line). If everything goes well, the Unloc app will invoke the returnUrl path after downloading all the Keys, in this case, opening Google Chrome on https://example.app/success-prefetch
https://dl.unloc.app/prefetch-keys?returnUrl=googlechrome://navigate?url=https://example.app/success-prefetchUse Key
https://dl.unloc.app/use-key?id=<keyId>&userid=<mobilePhoneNumber>&redirect=<redirectURL>&redirectOnError=<redirectOnErrorURL>| Query parameter | Meaning |
|---|---|
| id | The ID of the Key to open. |
| userid | The invited user's mobile number in E.164 format. |
| redirect | An URL to redirect the user on success. For instance yourapphandler://success |
| redirectOnError | An URL to redirect the user when the Key is not available. For instance: yourapphandler://key-error |
If the user does not have the Unloc app installed on their device, then the App Switch URL will take the user to App Store (iPhone) or Play Store (Android).
URL Encoding RequiredThe
+sign in the user's mobile number must be URL-encoded. For example,+15845551234must be encoded as%2B15845551234
Example
When the following URL is opened on a mobile device, the Unloc app will be launched and take the user directly to a given Key. Once the Key is used, the Unloc App will launch Google Chrome and navigate to https://example.app/success. If anything fails, Google Chrome will be opened but the target path will be https://example.app/key-error.
https://dl.unloc.app/use-key?id=e31d1213-ade5-4786-ab17-33637e602def&userid=%2B15845551234&redirect=googlechrome://navigate?url=https://example.app/success&redirectOnError=googlechrome://navigate?url=https://example.app/key-errorQuery parameters used in the example URL:
| Query parameter | Example Value | Note |
|---|---|---|
| id | e31d1213-ade5-4786-ab17-33637e602def | The ID of the key to open |
| userid | %2B15845551234 | URL-encoded mobile phone number +15845551234 |
| redirect | googlechrome://navigate?url=https://example.app/success | After key usage, the Unloc app will redirect the user back to the Google Chrome mobile app. |
| redirectOnError | googlechrome://navigate?url=https://example.app/key-error | A redirect URL for when the Key is not available or the operation of the lock failed. |
Error handling
Error information is passed as query params appended to the provided redirectOnError URL.
Example: https://example.app/key-error?operateLockErrorCode=1011
| Query parameter | Example value | Note | Testing |
|---|---|---|---|
| operateLockErrorCode | 1011 | The error code reported in the Unloc app when operating the lock fails. In this example, 1011, a Bluetooth operated lock could not be detected in time and a timeout error is reported. Always a four digit code. | Create a key to a lock you are not nearby or a lock that can't be reached. Create a URL for a valid key to this lock with a redirectOnError to your preference. Make sure the user is signed in to the Unloc app. Try the App Switch URL and it should result in the Unloc app redirecting to yourredirectOnErrorurl with the operateLockErrorCodepresent as a very param. |
| userIdMismatch | The key you tried to use is for +19175550123, but you are logged in with +19175550321 in the Unloc app. | The app switch was triggered with a key that does not belong to the user signed in to the Unloc app. Make sure the signed in user matches the one you are creating the app switch URL for. | Sign in to the Unloc app with a user. Create an App Switch URL to a different user and try it. It should result in the Unloc app redirecting to yourredirectOnErrorurl with the userIdMismatchpresent as a very param. |
| loadKey | An active key to this door could not be found. Make sure you have the correct access rights and try again. | An active key with the provided ID could not be loaded in time. This error can occur when the user don't have a key, the key is not in active state or network conditions prevented the key from being loaded. | Sign in to the Unloc app, leave the app, put in flight mode or turn off network access. Create a new for the user. Create an App Switch URL and try it. It should result in the Unloc app redirecting to yourredirectOnErrorurl with the loadKeypresent as a very param. |
App switching without key ID
The Unloc app can also be opened without specifying a Key ID. The app will then open on the front page of the app displaying all available Keys. This process will begin after visiting the following URL:
https://dl.unloc.app/getIf the Unloc app is not installed in the device, then the device's application marketplace (App Store for iPhone or Google Play for Android) will open offering the user the option to download the Unloc app.
appSwitchOnly Keys
appSwitchOnly KeysappSwitchOnly Keys are Keys that are not shown to the User on their Unloc app's Key list, so they can't interact with them directly; they rely on your implementation to perform an App switch process, after which the whole unlocking process remains unchanged.
Service Providers can add an appSwitchOnly: true entry to the body of their Key creation request to mark the Key so the Unloc app doesn't display it on the User's Key list.
Updated 5 days ago