Handling Deeplinks and Applinks

Owned by Olesya Kershaw
Last updated: Jun 12, 2023 by Viacheslav Zhelobkov
4 min read

ProofSpace mobile application (main app) has functionality to handle calls from third-party applications via Deeplinks (https://en.wikipedia.org/wiki/Mobile_deep_linking ) and Applinks (calling native application from a web page). With both calls, the main app can be requested to execute specific interactions and prefill attributes of certain self-attested credentials. 

The application also supports a callback to call/open the requester after the successful execution of the interactions. This allows third-party apps and websites to integrate with ProofSpace platform services via the native application.

Call format

The main application receives calls in the following URL format:

[<https>|<custom schema>]://[application domain]/native/execute/[base64 encoded request json]

Note: URL safe Base64 encoding must be used. Otherwise some links can appear not readable by the application.

For application domains and custom schemas see below.

The request format follows the ActionInstanceInfoDTO (https://github.com/zakaio/service-dashboard-backend/blob/master/src/dto/ActionInstanceDTO.ts) with several additional fields.

One of those fields is the optional field sourceURL. If the sourceURL field presents and has a web URL, the remaining fields are ignored and used to download the ActionInstance object for further processing. In this case, the downloaded object's sourceURL field is ignored in any state to prevent recursion.

Another optional field is the callback, which contains a URL that will be called by the main application if the interaction is successfully executed.

Deeplinking custom schemas

The third-party application must be configured in such a way to be able to call external applications and, optionally, to be called back. Custom schemas of the main app are:

  • ProofSpace: zakaio://

  • ProofSpace test: testzakaio://

  • ProofSpace staging: stagezakaio://

  • ProofSpace preprod: prodtestzakaio://

Application domains

Depends on application environment application is configured to requests towards following domains:

  • ProofSpace: proofspace.id

  • ProofSpace test: test.proofspace.id

  • ProofSpace staging: stage.proofspace.id

  • ProofSpace preprod: prod-test.proofspace.id

Constrains

For an ActionInstance object downloaded via the sourceURL field or the request, its sourceURL field is ignored with any state to prevent recursion.

Only those predefined attributes handled that are required by the interaction requested to be executed. The rest of the attributes are ignored.

User Experience

With the deep link, it is the third-party app's responsibility to verify if it is possible to call the main app. 

If the main app is not installed on the user's device or, for some other reason, the third-party app cannot make a call, the native app must either prompt the user to install the main app or handle the situation in another way.

When the third-party application calls the installed main app, the user is switched there and sees an interaction screen with all corresponding attributes.

If some of the required credentials are absent, the user can request them via corresponding interactions. After receiving all required credentials, the user can proceed with the interaction.

In case of successful execution, and if the third-party app reveals a callback link, the main app tries to call it back and switch the user to the calling application. In all other cases, the user remains in the main application and receives corresponding popups.

Calls via app links happen from web pages, opened either in the user's device system web browser or with scanning QR code by a system scanner, which opens decoded URLs with a system browser.

Opening a link embedded in a third-party app web view or scanning a QR code with the custom scanner (most likely) will not call the installed main app and instead will open the requested link as a web page.

In this case, it is expected that the ProofSpace dashboard will show the user a page with the link to a corresponding application store to install the main app. These are existing limitations for both Android and iOS, and the main app cannot avoid them.

If a given interaction request should be initiated from a web page in a system browser, the user sees a link with an explanatory description. After the user taps the link, the system will open the main app and pass the request. The user sees the interaction screen and acts correspondingly.

In case of initiating an interaction from a QR code, the user will scan it using the system or the built-in scanner and get switched to the main app to the interaction screen.

If the main app is not installed on a user's device, during the app link call, the ProofSpace dashboard will be opened, and it is supposed to show a page with the links to the app stores to install it.

Callbacks flow

On iOS, to open Safari on the existing tab, its address, and the URL application opens must be identical and contain the page name (with or without an extension). E.g., https://www.unionen.se/ opens a new tab in Safari, and https://www.unionen.se/kurser-och-aktiviteter switches user to existing tab.

In order to open Chrome on the last tab, it opened applications both on iOS and Android can open URLs with "googlechrome://" schema without the following address.

Some other applications (e.g., WhatsApp, skype, telegram, etc.) can be opened similarly — using its specific custom schema: "skype://," "whatsapp://", etc. Though, their behavior should be tested when opened through the custom schema.

Changes in start interaction page

  1. Start interaction web page must have page file name.

  2. If interaction is requested from Chrome, request callback must be “googlechrome://"

  3. If it is possible to identify on the web page that it was opened in non browser application (skype/telegram/whatsapp), then callback should contain corresponding custom schema: skype://, telegram://, whatsapp://. Otherwise it should be empty for Android and contain full page URL on iOS.