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
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
|
If you are creating a URL scheme manually, then you can use an online tool to encode values for you, such as this tool .
If you are creating URL schemes in javascript then you can encode values using the
encodeURIComponent()
method.
var pageName = encodeURIComponent('Page 3: HTML Point');
The following samples demonstrate how url schemes can be used with your projects.
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
The complete list of settings that can be changed are listed below along with examples which can be tested on your device at any time:
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:
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.
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.
Prefix: |
mda://device/new/session
|
Required Parameters: |
|
Optional Parameters: |
The new session's points can be populated with values:
|
mda://device/new/session?project=javascript_sample_subproject.ppc&values={"edit1":"NewValue","edit2":"NewValue"}
Prefix: |
mda://device/open/session
|
Required Parameters: |
|
Optional Parameters: |
|
C05DB001-2919-4103-AD76-1DFF47FC449D
mda://device/open/session?project=javascript_sample_subproject.ppc&session=C05DB001-2919-4103-AD76-1DFF47FC449D
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
Prefix: |
mda://device/send/sessions
|
Required Parameters: |
|
Optional Parameters: |
Sessions can be sent for multiple projects:
|
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.
Prefix: |
mda://device/duplicate/sessions
|
Required Parameters: |
|
Optional Parameters: |
The new session's points can be populated with values:
|
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.