URL Schemes

Defining a custom URL scheme for your app will allow you to launch your app when tapping URLs and QR codes. This can be used to launch specific RapID operations, such as authentication and credential collection allowing for a better experience for your end users. Creating your own URL scheme has three main steps.

  • Creation of a unique protocol name and deciding on a URL structure.
  • Associating your mobile app with the protocol name.
  • Using the protocol to launch app operations.

Creating a protocol name

A protocol name should be unique and is expected to remain unique for the lifetime of an app. For example "MyApp" would be a poor choice for a protocol name. When more than one app share the same URL Scheme the behaviour is unspecified on iOS. On Android the user will be asked to choose which app to open.

The below examples defines a basic URL scheme using the protocol com.mycompany.appname. A URL Scheme can be more complex, please refer to official iOS and Android documentation to include the host, identifier and port within a URL Scheme.

Associating your app with a protocol

Once you have chosen your protocol, the association between protocol and the app is setup within the files AndroidManifest.xml and iOS Info.plist.

Cordova

The easiest way to setup a basic URL Scheme in Cordova is to install the plugin cordova-plugin-customurlscheme. This is an open source cordova plugin that is commonly used for URL Scheme setup and app launching. This plugin can be added to your project automatically using the following command in your project directory:

cordova plugin add cordova-plugin-customurlscheme --variable URL_SCHEME=com.mycompany.appname

During installation the plugin updates the AndroidManifest.xml and the iOS Info.plist with the URL Scheme com.mycompany.appname.

Native Android

Modify the AndroidManifest.xml file in your project and create an intent-filter element within the activity element.

Below is an example for the URL scheme com.mycompany.appname.

<activity android:name="">
  <intent-filter>
    <action android:name=""/>
    <category android:name=""/>
    <data android:scheme="com.mycompany.appname" android:host="" android:port="" android:path=""/>
  </intent-filter>
</activity>

For futher information see the Android documentation.

iOS

On iOS, change your project Info.plist and add a key value pair for CFBundleURLTypes.

Below is an example for the URL scheme com.mycompany.appname.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.mycompany.appname</string>
    </array>
  </dict>
</array>

For further information see Apples iOS documentation.

Associate a QR Code with a protocol

The QR Code should represent the operation you want the app to perform. The QR Code can be encapsulated by an <a> tag to make the QR Code tappable from a browser on the mobile device.


<a id="example_id_link" href="com.mycompany.appname://collection_challenge=d5f4e54a-50d0-4fcf-93b8-5100432d47ba">
   <img class="example_id_img" id="rapid_login_qr" name="rapid_login_qr" src="data:image/png;base64,iVBOR..." title="Scan with RapID to sign in">
</a>

In the above example the URL Scheme is followed by :// and then the data represented in the QR Code. When tapped, the link com.mycompany.appname://collection_challenge=d5f4e54a-50d0-4fcf-93b8-5100432d47ba is resolved to the app that has the URL Scheme com.mycompany.appname registered and will present the information collection_challenge=d5f4e54a-50d0-4fcf-93b8-5100432d47ba as the URL data when the app is launched.

Using URL Scheme in HTML pages and in emails

Some email clients will strip out unrecognised URL protocols for security reasons, which means when the link is tapped the registered app will not launch. To work around this problem a http(s) link is sent within the email which when tapped resolves to the URL Protocol allowing the app to launch.