mobicontrol.app

This namespace provides access to the app control functionality, like starting or installing an app.
Since:
  • Version 1.0 (API level 1)

Classes

AdminDeactivationError
mobicontrol.app.AdminDeactivationError

App
mobicontrol.app.App

AppClearDataError
mobicontrol.app.AppClearDataError

AppError
mobicontrol.app.AppError

Members

static, readonly AdminDeactivationStatusCode :object

This enumeration represents an error status code of [AppAdminDeactivationErrorHostObject].
Properties:
Name Type Description
NOT_SUPPORTED object The device administrator deactivation is not supported by the current agent.
NOT_INSTALLED object The specified app is not installed.
NOT_PERMITTED object The device administrator deactivation is not permitted for the specified app.
Since:
  • Version 1.6 (API level 7)

static, readonly AppStatusCode :object

This enumeration represents an error status code of mobicontrol.app.AppError.
Properties:
Name Type Description
UNKNOWN object The exact error could not be determined.
NOT_INSTALLED object The app is not installed.
Since:
  • Version 1.3 (API level 4)

static, readonly ClearDataStatusCode :object

This enumeration represents an error status code of mobicontrol.app.AppClearDataError.
Properties:
Name Type Description
UNKNOWN object The exact error could not be determined.
NOT_SUPPORTED object Clear operation is not supported by the current agent.
NOT_INSTALLED object The specified app is not installed.
NOT_PERMITTED object Clearing the agent data can cause unrecoverable errors and is not permitted.
Since:
  • Version 1.3 (API level 4)

static, readonly, nullable foregroundActivities :Array.<mobicontrol.app.Activity>

Activities running in the foreground.

This property is null if the list of the foreground activities cannot be obtained. This might happen, for example, if the agent doesn't have the proper permissions.

Since:
  • Version 1.0 (API level 1)
Example
// Stop clock app if it runs in the foreground
var clockApp = 'com.android.deskclock';
var foregroundActivities = mobicontrol.app.foregroundActivities;
if (foregroundActivities != null) {
    foregroundActivities.forEach(function(activity) {
        if (activity.packageName == clockApp) {
            mobicontrol.app.stop(clockApp);
        }
    });
}

static, readonly InstallationStatusCode :object

This enumeration represents a return status code of mobicontrol.app.install.
Properties:
Name Type Description
NONE object No specific status code.
ALREADY_INSTALLED object Same version of the app is already installed.
FILE_NOT_FOUND object .apk file was not found.
VERSION_DOWNGRADE object Attempt to downgrade already installed app failed.
APK_FORMAT_NOT_CORRECT object .apk file format is not correct. This includes cases where the .apk file is incompatible with the device's OS.
Since:
  • Version 1.0 (API level 1)

static, readonly, nullable installedApps :Array.<mobicontrol.app.App>

The array of apps installed on the device.

This property is null if the list of the installed apps cannot be obtained.

Since:
  • Version 1.3 (API level 4)
Example
var installedApps = mobicontrol.app.installedApps;
if (installedApps == null) {
    mobicontrol.log.error("Cannot obtain the list of installed apps");
} else {
    var installedAppPackageNames = installedApps
        .map(app => app.packageName)
        .join('|');
    mobicontrol.log.info(installedAppPackageNames);
}

Methods

async, static clearCache(packageName)

Clear app cache.
Parameters:
Name Type Description
packageName string The package name of the app to be cleared.
Throws:
mobicontrol.app.AppClearDataError
Since:
  • Version 1.7 (API level 8)
Example
mobicontrol.app.clearCache('com.example');

async, static clearData(packageName)

Clear app data.
Parameters:
Name Type Description
packageName string The package name of the app to be cleared.
Throws:
mobicontrol.app.AppClearDataError
Since:
  • Version 1.3 (API level 4)
Example
mobicontrol.app.clearData('com.example');

static deactivateAdmin(packageName) → {boolean}

Deactivates the admin rights.

Deactivate device administrator for an app.

Parameters:
Name Type Description
packageName string the package name of the app to be deactivated.
Throws:
mobicontrol.app.AdminDeactivationError
Returns:
boolean - true if the device administrator for the app is deactivated, false otherwise.
Since:
  • Version 1.6 (API level 7)
Example
mobicontrol.app.deactivateAdmin('com.example');

static getInstalledApp(packageName) → {mobicontrol.app.App}

Get the installed app by package name.
Parameters:
Name Type Description
packageName string The app package name.
Throws:
mobicontrol.app.AppError
Returns:
mobicontrol.app.App - The installed app with the provided package name.
Since:
  • Version 1.3 (API level 4)
Example
if (mobicontrol.app.getInstalledApp("com.example").versionCode < 15000) {
    mobicontrol.log.error("The Example app is outdated; aborting script.")
}

async, static install(apkFilePath, callbackFunctionopt, invocationTimeoutInMillisopt) → {boolean}

Install an app.

If the app (same version) is already installed, no action is taken, and the function returns true. If app installation isn't possible, the function returns false. For example, app installation might not be possible if one of the following conditions exists:

  • The .apk file does not exist.
  • The .apk file has a wrong format.
  • A later version of the app is already installed.
Otherwise, the function returns true, and the installation process is asynchronously launched. Note that the installation might still fail, even if the function has returned true.

If a callback function parameter is supplied, it will be called when the installation attempt completes, with an argument describing the result of the installation attempt.

Parameters:
Name Type Attributes Default Description
apkFilePath string The path to the .apk (for example, "/data/example.apk").
callbackFunction mobicontrol.app.installCallback <optional>
 JavaScript function which is called when the installation attempt completes.
invocationTimeoutInMillis number <optional>
 60000 Invocation timeout in milliseconds. If the callback function isn't invoked before the timeout expires, it will be called with the timed-out result.
Returns:
boolean - true if the app installation process was successfully launched, false otherwise.
Since:
  • Version 1.0 (API level 1)
Example
// Install an app and start it as soon as it has been installed
mobicontrol.app.install('/sdcard/example.apk', onFinish);

function onFinish(result) {
    if (result.isSuccessful) {
        mobicontrol.app.start('net.soti.example');
    }
}

async, static start(packageName, classNameopt) → {boolean}

Start an app.
Parameters:
Name Type Attributes Description
packageName string The package name of the app to start.
className string <optional>
 The fully qualified class name of the specific component of the app.
Returns:
boolean - true if the app starting process was succesfully launched, false otherwise.
Since:
  • Version 1.0 (API level 1)
Example
mobicontrol.app.start('com.example', 'com.example.app.MyActivity');

async, static stop(packageName) → {boolean}

Stop an app.
Parameters:
Name Type Description
packageName string The package name of the app to be stopped.
Returns:
boolean - true if the app stopping process was successfully launched, false otherwise.
Since:
  • Version 1.0 (API level 1)
Example
mobicontrol.app.stop('com.example');

Type Definitions

Activity

This typedef represents an Android activity.
Properties:
Name Type Description
packageName string Package name of this activity.
className string Class name of this activity.
Since:
  • Version 1.0 (API level 1)

installCallback(result)

Callback function for mobicontrol.app.install.
Parameters:
Name Type Description
result object Result of the installation attempt.
Properties
Name Type Description
apkFileName string The .apk file of the application that is being installed.
statusCode mobicontrol.app.InstallationStatusCode The detailed status code of the callback.

Follow the link in the Type column to see all the possible values.
isSuccessful boolean Success status of the callback.

true if the callback completed successfully, false otherwise.
isTimedOut boolean Timeout status of the callback.

true if the callback was timed out, false otherwise.

Note: A timeout is considered a failure, so if the timeout status is true, failure status is true as well, and success status is false.
isFailed boolean Failure status of the callback.

true if the callback failed, false otherwise.
Since:
  • Version 1.0 (API level 1)