Tutorial: Using Android Agent JavaScript from Lockdown Screen

In SOTI MobiControl Android Agent version 15.2 and later, you can customize the lockdown screen to display any information obtained using SOTI MobiControl Agent JavaScript (which is referred to as McScript below). You can update the screen regularly to show up-to-date information.

For example, the lockdown screen can show current battery level, memory and storage usage, or number of installed applications.

This feature is supported across all agents and lockdown types and requires template modification.

Displaying the Result of an McScript on the Lockdown Screen

In order to populate an HTML element with the result of an McScript script, the Lockdown template needs to feature a script element, holding a JavaScript script that will execute the following:

  • Send an HTTP request to URI mcscript://<encoded Android Agent script>, where <encoded McScript script> is an McScript script, with all HTTP-invalid characters replaced with escape sequences.
  • Register a callback to be executed on HTTP response. The response text will contain the output of the McScript script.
  • Assign response text to the HTML element.

The following code sample shows the script element that you need to append to the Lockdown template in order to show the battery level:

<script>
1. var request = new XMLHttpRequest();
2. request.addEventListener("load", onLoad);
3. var encodedScript = encodeURIComponent("(mobicontrol.battery.level * 100) + '%'");
4. request.open("GET", "mcscript://" + encodedScript);
5. request.send();
6.
7. function onLoad() {
8.	var responseText = this.responseText;
9.	var div = document.getElementById("batteryLevel");
10.	var spans = div.getElementsByTagName("span");
11.	spans[0].innerHTML = responseText;
12.}
</script>
  • Lines 1-5 configure and send the HTTP request. The encodeURIComponent JavaScript function is used to encode the McScript script, so it only contains valid HTTP characters. Newlines can be entered as "\\n".
  • Function onLoad is a callback for HTTP response, which is registered at line 2.
  • Lines 9-10 find the "batteryLevel"-named element in the HTML document, with a "span" sub-element. This assumes such an element is defined in the Lockdown template, for example:
    <div id="batteryLevel">Battery level: 
<span></span>
</div>
  • The result of the McScript is assigned to the span sub-element at line 11.

Dynamically Updating the Lockdown Screen

If the McScript script result might change over time (when reporting battery level, for example) you can update the Lockdown template to refresh certain HTML elements at a designated frequency.

The following sample amends the previous example to refresh the batteryLevel element every minute:

<script>
1. sendBatteryRequest();
2.
3. function sendBatteryRequest() {
4.	var request = new XMLHttpRequest();
5.	request.addEventListener("load", onLoad);
6.	var encodedScript = encodeURIComponent("(mobicontrol.battery.level * 100) + '%'");
7.	request.open("GET", "mcscript://" + encodedScript);
8.	request.send();
9. }
10.
11. function onLoad() {
12.	var responseText = this.responseText;
13.	var div = document.getElementById("batteryLevel");
14.	var spans = div.getElementsByTagName("span");
15.	spans[0].innerHTML = responseText;
16.	setTimeout(sendBatteryRequest, 60000);
17.}
</script>
  • Lines 1-5 in the original code are wrapped in the sendBatteryRequest function. This function is called from two places: at the very start of line 1 and at line 16.
  • At line 16 you can use the JavaScript setTimeout function to invoke sendBatteryRequest in 1 minute (the second parameter of setTimeout is specified in milliseconds).
  • sendBatteryRequest triggers onLoad, which in turn triggers sendBatteryRequest. This causes a recursive refresh of the batteryLevel element.

Error Handling

In case the McScript script is malformed or throws an error, the HTTP response will contain an Internal Server Error status (on Android Lollipop and later, but not supported on pre-Lollipop devices), and the response text will show the error message.

You can amend the Lockdown template script to handle such errors:

<script>
1. sendBatteryRequest();
2.
3. function sendBatteryRequest() {
4.	var request = new XMLHttpRequest();
5.	request.addEventListener("load", onLoad);
6.	var encodedScript = encodeURIComponent("(mobicontrol.battery.level * 100) + '%'");
7.	request.open("GET", "mcscript://" + encodedScript);
8.	request.send();
9. }
10.
11. function onLoad() {
12.	var responseText = this.status == 500 ? "Unavailable" : this.responseText;
13.	var div = document.getElementById("batteryLevel");
14.	var spans = div.getElementsByTagName("span");
15.	spans[0].innerHTML = responseText;
16.	setTimeout(sendBatteryRequest, 60000);
17.}
</script>
  • Line 12 is amended to handle the McScript error: if the error occurs - the batteryLevel element will show "Unavailable" instead of the error message.