URL Schemes

Learn how the URL schemes can be used in your projects to create dynamic actions for creating, sending and opening sessions and much more.

What are URL Schemes?

URL Schemes are a way of sending commands to the Mobile Data Anywhere mobile application in order to perform actions such as opening a project or a session. These commands are formed similar to a URL to a website except that they use a special prefix, mda:// instead of the typical https:// . A basic example of a URL scheme command that creates a new session in a project can be seen below:

mda://device/new/session?project=url_scheme_sample_project.ppc

Key Features

  • Can be used to create new sessions and pass in values to populate points.
  • Can be used to open, send, duplicate and delete sessions within a project.
  • Can be used in conjunction with Sub Project point to send commands between parent and child sessions and visa versa.
  • Can be used to update the settings for a device.
  • Can be executed from an external application to provide interaction with other mobile applications.

What is URL Encoding?

This is a term given to the practice of translating spaces and special characters such as ?, &, %, ! into a value that is acceptable for a URL. To ensure that a URL scheme is constructed correctly, it is important that any unsafe parameter values are URL encoded. Some examples can be seen below:

Unencoded Encoded
page=Page 3: HTML Point page=Page%203%3A%20HTML%20Point
values={"name"="John Smith", "email"="john.smith@example.com"} values=%7B%22name%22%3D%22John%20Smith%22%2C%20%22email%22%3D%22john.smith%40example.com%22%7D

Encoding Manually

If you are creating a URL scheme manually, then you can use an online tool to encode values for you, such as this tool .

Encoding in Javascript

If you are creating URL schemes in javascript then you can encode values using the encodeURIComponent() method.

var pageName = encodeURIComponent('Page 3: HTML Point');

Sample Projects

The following samples demonstrate how url schemes can be used with your projects.


Sample Projects
You can download the sample files for this tutorial or import the projects directly into your account.

Sample 1: Configuring Device Settings

This sample demonstrates how to configure a device's settings using URL schemes. The first page of the sample project displays a Button point which will open this tutorial on your mobile device's browser. Each of the example URL schemes provided below can be tested on your mobile device by clicking on the link.

A URL Scheme can be used to set or update a device's settings simply by clicking a link or a button. This can be used to quickly setup new devices out on the field by sending them a link via an email or SMS. To create a URL scheme that can configure a device, the link must start with mda://device/configure . The settings that you wish to update will need to be added to the end of this as parameters, for example:

mda://device/configure?unit_id=test_device&server_address=data.mobiledataanywhere.com&server_password=password1234&encryption=1&server_port=2001

Url schemes settings ios

Automatically Submit New Sessions
Parameter Name: auto_send_new

Automatically Submit Old Sessions
Parameter Name: auto_send_old

Prevent Session Duplication
Parameter Name: prevent_duplicate

Prevent Project Deletion
Parameter Name: prevent_project_delete

Sample 2: URL Schemes for Sessions

This sample demonstrates how to create URL schemes that interact with sessions on your device. This sample uses the project files used in the Javascript point tutorial which can download here:


Sample Projects
You can download the sample files for this tutorial or import the projects directly into your account.

Session URL Schemes

The second section on page 3 of the sample project, javascript_sample.ppc , provides an example of how URL schemes can be used to interact with sessions in a project. This example creates a new session in the sub project, javascript_sample_subproject.ppc , and then provides links to open, send, duplicate and delete the session.

Url schemes session ios

The list of URL schemes that are available for sessions are listed below. To test the examples on a mobile device you will need to install the provided sample projects on your mobile device.


Create a Session
Prefix: mda://device/new/session
Required Parameters:
project=PROJECT_FILE_NAME
Optional Parameters:

The new session's points can be populated with values:

values={"edit1":"VALUE FOR EDIT1", "edit2":"VALUE FOR EDIT2"}
Show Examples
Examples:

Creating a new session in a sub project:
mda://device/new/session?project=javascript_sample_subproject.ppc&values={"edit1":"NewValue","edit2":"NewValue"}

Open a Session
Prefix: mda://device/open/session
Required Parameters:
project=PROJECT_FILE_NAME
Optional Parameters:
project=CAPTION_OF_PAGE_TO_OPEN
Show Examples
Examples:

Open a session with that has the GUID C05DB001-2919-4103-AD76-1DFF47FC449D
mda://device/open/session?project=javascript_sample_subproject.ppc&session=C05DB001-2919-4103-AD76-1DFF47FC449D

Open the same session and open page 3 which has the caption; Page 3: HTML Point . Since the page caption contains characters that are unsafe for a URL, the page value will need to be encoded . The encoded page caption is: Page%203%3A%20HTML%20Point .
mda://device/open/session?project=javascript_sample_subproject.ppc&session=C05DB001-2919-4103-AD76-1DFF47FC449D&page=Page%203%3A%20HTML%20Point

Sending Sessions
Prefix: mda://device/send/sessions
Required Parameters:
sessions=[
{
  "project":"PROJECT_FILE_NAME",
  "sessions":["FIRST_SESSION_GUID", "SECOND_SESSION_GUID"]
}]
Optional Parameters:

Sessions can be sent for multiple projects:

sessions=[
{
  "project":"FIRST_PROJECT_FILE_NAME",
  "sessions":["FIRST_SESSION_GUID", "SECOND_SESSION_GUID"]
},
{
  "project":"SECOND_PROJECT_FILE_NAME",
  "sessions":["THIRD_SESSION_GUID", "FOURTH_SESSION_GUID"]
}]
Show Examples
Examples:

Sending a session

Since this URL scheme's parameters include multiple arrays and dictionaries, the value will need to be translated into a usable value using javascript:

Before encoding the values:
mda://device/send/sessions?sessions=[{"project":"javascript_sample_subproject.ppc", "sessions":["C05DB001-2919-4103-AD76-1DFF47FC449D"]}]
Encoding the values using javascript:
var unencodedValue = [{"project":"javascript_sample_subproject.ppc", "sessions":["C05DB001-2919-4103-AD76-1DFF47FC449D"]}];
var encodedJSONForSend = encodeURIComponent(JSON.stringify(unencodedValue));
var urlToSendSession = "mda://device/send/sessions?sessions=" + encodedJSONForSend;
The encoded URL scheme:
mda://device/send/sessions?sessions=%22%5B%7B%5C%22project%5C%22%3A%5C%22javascript_sample_subproject.ppc%5C%22%2C%20%5C%22sessions%5C%22%3A%5B%5C%22C05DB001-2919-4103-AD76-1DFF47FC449D%5C%22%5D%7D%5D%22

For a complete example of this URL scheme, see the javascript file javascript_sample_3_url_schemes.js supplied with the sample files.


Duplicating a Session
Prefix: mda://device/duplicate/sessions
Required Parameters:
params={
  "duplicate":[
    {
      "project":"PROJECT_FILE_NAME",
      "sessions":["SESSION_GUID"]
    }
  ]
}
Optional Parameters:

The new session's points can be populated with values:

params={
  "duplicate":[
    {
      "project":"PROJECT_FILE_NAME",
      "sessions":["SESSION_GUID"],
      "values":{"edit1":"VALUE FOR EDIT1", "edit2":"VALUE FOR EDIT2"}
    }
  ]
}
Show Examples
Examples:

Duplicating a session

Since this URL scheme's parameters include multiple arrays and dictionaries, the value will need to be translated into a usable value using javascript:

Before encoding the values:
mda://device/duplicate/sessions?params={"duplicate":[{"project":"javascript_sample_subproject.ppc", "sessions":["C05DB001-2919-4103-AD76-1DFF47FC449D"], "values":{"edit1":"Edit 1 Value", "edit2":"Edit 2 Value"}}]}
Encoding the values using javascript:
var unencodedValue = {"duplicate":[{"project":"javascript_sample_subproject.ppc", "sessions":["C05DB001-2919-4103-AD76-1DFF47FC449D"], "values":{"edit1":"Edit 1 Value", "edit2":"Edit 2 Value"}}]};
var encodedJSONForDuplicate = encodeURIComponent(JSON.stringify(unencodedValue));
var urlToDuplicateSession = "mda://device/duplicate/sessions?params=" + encodedJSONForDuplicate;
The encoded URL scheme:
mda://device/duplicate/sessions?params=%7B%22duplicate%22%3A%5B%7B%22project%22%3A%22javascript_sample_subproject.ppc%22%2C%22sessions%22%3A%5B%22C05DB001-2919-4103-AD76-1DFF47FC449D%22%5D%2C%22values%22%3A%7B%22edit1%22%3A%22Edit%201%20Value%22%2C%22edit2%22%3A%22Edit%202%20Value%22%7D%7D%5D%7D

For a complete example of this URL scheme, see the javascript file javascript_sample_3_url_schemes.js supplied with the sample files.


Delete a Session
Prefix: mda://device/delete/session
Required Parameters:
project=PROJECT_FILE_NAME
session=SESSION_GUID
Show Examples
Examples:

Deleting a session:
mda://device/delete/session?project=javascript_sample_subproject.ppc&session=C05DB001-2919-4103-AD76-1DFF47FC449D