The Unloc App
The Unloc mobile App can be used by both, end users and Service Providers to open Locks. Here we will discuss how you can use it as a Service provider.
The integration of your solution with the Unloc app is actually quite straight forward; our goal was to have a
one-size-fits-all solution so you don't need to add any additional efforts on your end, that's why the Unloc app allows Unloc Keys to be used via URLs.
The only requirement is that the person providing the service has previously logged into the Unloc app using their mobile phone number, this way you can generate a Key for that specific User (which is the same as their mobile phone number).
Once you create a Key for the specific User on your solution, you then generate a URL containing the Key ID, the User ID (again, this is their mobile phone number), and a URL to be invoked once the "Unlocking process" is completed. This is known as an App Switch URL.
The App Switching flow.
When the App Switch URL is followed, the following happens:
- The Unloc app is invoked
- The Unloc app uses both the Key ID and the User ID present in the App Switch URL to verify if they actually match on the Unloc Platform side. If they do, the Key for that Lock is fetched
- The person providing the service can use the Unloc app to open the Lock
- Once the Lock is opened, the redirect URL is invoked to continue the flow back on your solution
One of the benefits of using App Switch URLs is that they can be used from either a mobile or web app (via the device's browser) with the same result: the Unloc App is invoked ready to open the Lock.
The App Switch URL
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 begin downloading them, 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 may 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-prefetch
Use 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 Required
The
+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-error
Query 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. |
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://unlocapp.page.link/download
If 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 10 months ago