Page tree
Skip to end of metadata
Go to start of metadata

This article describes how to start Nexus Personal Mobile, or an app based on the Personal Mobile SDK, from another app on the same device. 

Expand/Collapse All

Prerequisites

 Prerequisites

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

Step-by-step instruction

 Add code to start app on idle screen

To open Personal Mobile on the idle screen, waiting for requests:

For an authentication or signing message to show up in Personal Mobile, an authentication or signing request first need to be sent to the Hermod Messaging Server or Hybrid Access Gateway. 

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

  1. Add the following code to start the Personal Mobile app directly from another app on the same device:

    <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
    personal://start?title=My+title&redirect=my-redirect-URL%3A%2F%2F 

 Add code to start app for provisioning

To open Personal Mobile for provisioning and creating a new user profile:

  1. Add the following code to start the Personal Mobile app directly from another app on the same device:

    <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
    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

 Examples
Example: Link in html
<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
var startURL = 'bank-app://start'
window.location.replace(startURL);
Example: Link in Swift 3 for iOS 8-10
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 the Personal Mobile application is the following: 

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

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

<URL-Scheme> optionDescription
personal

for the standard Nexus Personal app

<my-app-name>
for apps based on the Nexus Personal SDK
 <Message>

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

<Message> optionDescription
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>
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> optionDescription
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.


Related information