Set up Smart ID Mobile App to start on same device

This article describes how to set up Smart ID Mobile App, or an app based on the Smart ID Mobile SDK, to start from another application on the same device.

Prerequisites

The app that is intended to start Smart ID Mobile App must have registered a url-scheme, as described in the article.

Add code to start app on idle screen

To open Smart ID Mobile App on the idle screen, waiting for requests:

For an authentication or signing message to show up in Smart ID Mobile App, an authentication or signing request first need to be sent to the Hermod Messaging Server or Smart ID Digital Access (Hybrid Access Gateway).

For more information on how to send authentication and signing requests to Hermod Messaging Server, see here.

Add the following code to start Smart ID Mobile App directly from another app on the same device:
TEXT
```
<URL-Scheme>://start?<Parameter>=<Value>
```
For parameter options, see Personal protocol specification.
Example with a title and a redirect to my-redirect-URL://:
Example: start app with title and redirect
TEXT
```
personal://start?title=My+title&redirect=my-redirect-URL%3A%2F%2F 
```

Add code to start app for provisioning

To open Smart ID Mobile App for provisioning a new mobile virtual smart card for a user:

Add the following code to start Smart ID Mobile App directly from another app on the same device:
TEXT
```
<URL-Scheme>://<Link to message>?<Parameter>=<Value>
```
For parameter options, see Personal protocol specification.
Example with a <link to message>, a title and a redirect to my-redirect-URL://:
Example: start app for provisioning with title and redirect
TEXT
```
personal://<my-hermod-host>/hermod/rest/ms/ee2fec93-5daf-436f-b7d2-32a7ff86fe75/0573a28d-ecfa-480d-ade6-11d2144953a8?title=My+title&redirect=my-redirect-URL%3A%2F%2F 
```

Examples

Example: Link in html

XML

<a href="bank-app://<my-hermod-host>/hermod/rest/ms/ee2fec93-5daf-436f-b7d2-32a7ff86fe75/0573a28d-ecfa-480d-ade6-11d2144953a8?title=My+title&redirect=<my-redirect-URL>">Open with Bank App</a>

Example: Link in JavaScript

JS

var startURL = 'bank-app://start'
window.location.replace(startURL);

Example: Link in Swift 3 for iOS 8-10

CODE

let redirect = "bank-app://start".addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
let scheme = "bank-app://start?redirect=\(redirect)"

if let url = URL(string: scheme) {
    if #available(iOS 10, *) {
        let options = [UIApplicationOpenURLOptionUniversalLinksOnly : true]
        UIApplication.shared.open(url, options: options, completionHandler: {
            (success) in
            print("Open \(scheme): \(success)")
            // handle error or success contitions
        })
    } else {
        let success = UIApplication.shared.openURL(url)
        print("Open \(scheme): \(success)")
        // handle error or success contitions
    }
}

Personal protocol specification

General syntax

The general syntax to start Smart ID Mobile App is the following:

CODE

<URL-Scheme>://<Message>?<Parameter1>=<Value1>[&<Parameter2>=<Value2>]

<URL-Scheme>

The available values for <URL-Scheme> are described in this table:

<URL-Scheme> option	Description
^personal	for the standard Smart ID Mobile App
^{<my-app-name>}	for apps based on the Smart ID Mobile SDK

<Message>

The available values for <Message> are described in this table:

<Message> option

Description

start

Starts the app on the idle screen, to wait for requests.

<Link to message>

Starts the app for provisioning, to handle the request in the package.

The <Link to message> is the part after https:// in a normal provision request link.
The app automatically appends https:// before the request is made.

Example: <Link to message>

TEXT

personal://<my-hermod-host>/hermod/rest/ms/ee2fec93-5daf-436f-b7d2-32a7ff86fe75/0573a28d-ecfa-480d-ade6-11d2144953a8?title=My+title&redirect=<my-redirect-URL>

Other message types

The functionality to open a link to an authentication or signing request is not yet implemented.

<Parameter>=<Value>

The available values for <Parameter> and <Value> are described in this table. Two parameters can be used, separated by '&':

<Parameter>=<Value> option

Description

^{title=<string>}

<string> is a URL-encoded string that the app shows to the user while waiting for the request to complete.

^{redirect=<my-redirect-URL>}

Makes the app return to the <my-redirect-URL> after first confirmation is done (Provision, Authentication or Signature).
Failure to open the <my-redirect-URL> means that the user will stay in the personal app.

<my-redirect-URL> is a URL-encoded string to allow return parameters if required.

Example:
redirect=googlechrome://mail.google.com
This will open the chrome browser app, if it is available, and browse to gmail. If chrome is not available, it will fail.