Use this document to install the VMware AirWatch SDK Plugin for Apache Cordova. The plugin helps enterprise app developers add enterprise-grade security, conditional access, and compliance capabilities to mobile applications.

For a PDF version of this document, see https://resources.air-watch.com/view/8s6jb465n5h8xrwlmw9q/en.

Supported Components

This plugin works with the listed component versions.

  • AirWatch Console v9.0+
  • Android v4.1+
  • iOS v9.0+

Install the SDK Plugin

To install the plugin, type cordova plugin add airwatch-sdk-plugin at the command line.

Note: The download from NPM, at https://www.npmjs.com/package/airwatch-sdk-plugin, usually takes 2-3 minutes on average, over high speed internet connection.

Initialize the Plugin

The plugin auto-starts on both Android and iOS devices and it automatically starts the AirWatch SDK. After startup, the functions are available in the window.plugins.airwatch object. No other initialization is required to use the documented functions.

To receive events from the SDK, initialize an event listener. See the Events section.

Initialization of the SDK adds the listed features to your application, depending on the configurations set in the SDK profile in the AirWatch Console.

  • Application level passcode
  • Application level tunneling of network traffic
  • Integrated authentication / single sign on
  • Data loss prevention
    • Disable screenshot (Android only)
    • Restrict open-in for documents, web links, and email to approved applications only
    • Restrict copy/paste (SDK provides flag value)
    • Restrict access to app when device is offline
  • Branding of VMware AirWatch splash screens when SDK application is launched on device

Supported Functions

Use supported functions for Android and iOS.

setSDKEventListener(listener) - Sets an event-handler function to receive events from the SDK. See the Events section. Call this after Cordova fires the deviceready event. The listener callback should have two parameters, event and info.

username(successCallback, errorCallback) - Gets the enrolled user's username. The username is returned as a string parameter to the successCallback function.

groupId(successCallback, errorCallback) - Gets the enrolled user's group ID. The group ID is returned as a string parameter to the successCallback function.

serverName(successCallback, errorCallback) - Gets the name of the server to which the device is enrolled. The server name is returned as a string parameter to the successCallback function.

allowCopyPaste(successCallback, errorCallback) - Gets the "allow copy/paste" setting for the profile. If true, then the user can copy and paste between managed apps. If false then the user cannot copy and paste between managed apps. The value is returned as a boolean parameter to the successCallback function.

customSettings(successCallback, errorCallback) - Gets any custom settings provided in the app's profile. The value is returned as a string parameter to the successCallback function.

allowOffline(successCallback, errorCallback) - Gets the "allow offline use" setting for the profile. If true, then the user can use managed apps when not connected to the network. If false, the user cannot use managed apps when not connected to the network. The value is returned as a boolean parameter to the successCallback function.

openFile(absolutepath, successCallback, errorCallback) - Opens the file specified by the absolute path in accordance with the data loss prevention settings as configured on the AirWatch Console. The plugin restricts the files only to those whitelisted applications. Applications can have a custom implementation using restrictDocumentToApps and allowedApplications APIs. A success callback is invoked when the plugin is successfully able to open the file. In all other cases, an error callback is invoked with the corresponding error code.

To obtain the absolute path of the file (whether the file available bundled in the app or downloaded to the documents folder by the app), refer to the Cordova plugin documentation, at https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/.

Error code values for openFile

  • 2 - File not found at the path
  • 1 - Absolute path not specified
  • 0 - No error

SDK Events for Applications

The AirWatch SDK sends event notifications to applications that use it when certain conditions arise. To receive these notifications in a Cordova app, call setSDKEventListener(listener). The listener is a function that accepts two parameters. The first parameter is a string containing the name of the event. The second is an object that contains additional data if relevant to that type of event.

Events for Android and iOS

initSuccess - Sent when the AirWatch SDK is successfully initialized. All the functions of the plugin, other than setSDKEventListener(listener), are available after this event is fired. See the Functions section.

initFailure - Sent when the AirWatch SDK cannot be successfully initialized. Any future calls to the plugin fail.

Events for iOS

wipe - Sent when the device receives a wipe instruction from the console.

lock - Sent when the device receives a lock instruction from the console.

unlock - Sent when the device receives an unlock instruction from the console.

stopNetworkActivity - Sent when the device receives a stopNetworkActivity instruction from the console. The event data parameter contains a property named status with a numeric value as specified in the list.

Network Status Values for stopNetworkActivity

  • -2 - initializing
  • -1 - normal
  • 0 - bad SSID
  • 1 - cellular data disabled
  • 2 - roaming
  • 3 - proxy failed
  • 4 - network not reachable

resumeNetworkActivity - Sent when the device receives a resumeNetworkActivity instruction from the console.

The initSuccess Event and Business Logic

For applications using the AirWatch SDK, add all business logic of the application after the SDK fires initSuccess event. This means the SDK successfully initialized and the user is authenticated successfully, if applicable.

The application waits until the initSuccess or initFailure event fires. Until the AirWatch SDK completely loads and the initSuccess event fires, the application shows a waiting screen or a loading screen to give feedback to the user that the applicaiton is in the process of loading and starting.

The deviceready Event and Business Logic

Do not add business logic to the deviceready event.

Unless there is a specific business requirement to perform operations before the AirWatch SDK is initialized, do not add logic to the deviceready event. The SDK shows an authentication screen above Cordova WebView which can block the application's UI until the SDK is initialized. The initFailure event fires when if SDK initialization somehow fails. The application listens to this event and shows the corresponding error in the application.

Example

On deviceready, please set the SDK event listener: window.plugins.airwatch.setSDKEventListener(sdkEventCallback). The sdkEventCallback is a function that takes two arguments.

  1. A string that holds the name of the event fired.
  2. An object that contains the additional info on the event function sdkEventCallback(event, info).

    function sdkEventCallback(event, info) 
                            { 
                            /* Check (event === "initSuccess") before using sdk functionalities */ 
                            }
                            
                            
                            
                         

Questions and Feedback

Let us know if you have any questions or feedback by emailing us at https://support.air-watch.com/.

For further details about the AirWatch SDK, go to https://my.air-watch.com/help/9.2/en/Content/Online_Help_Topics/Overview_Topics/DeveloperDocs.htm.