Esper Device SDK

Responses

sdk.removeApnConfig(
           new EsperDeviceSDK.Callback() {
               @Override
               public void onResponse(@Nullable Integer response) {
                   showMethodResult("onResponse: removeAPN Result: " + response);
               }
    
               @Override
               public void onFailure(Throwable t) {
                   Log.e(TAG, "onFailure: ", t);
                   showFailureResult(t);
               }
    }, apnID);
    

EsperDeviceSDK.Callback

Responses

Usage

/**
          * @param packageNames - List of apps where data will be cleared.
          * @param callback - Invokes after the operation completes. 
          */
        sdk.clearAppData(appsToBeCleared, new EsperDeviceSDK.Callback<ArrayList>() {
            @Override
            public void onResponse(@Nullable ArrayList response) {
                        
            }
        
            @Override
            public void onFailure(Throwable t) {
        
            }
        });
        

Clear data from apps by passing the list of the package names. The API will return null in onResponse if it’s successful. If unsuccessful, it returns a list of packages where data was not cleared.

Managed App Configurations

Configure the app.

Managed Configurations (also known as app restrictions) allow you to configure apps remotely. Apply rules on the apps deployed to a work profile.

For example, an organization might require that approved apps allow you to:

• Allow or block URLs for a web browser.
• Configure whether an app is allowed to sync content via cellular or Wi-Fi.
• Configure the app’s email settings.

Requirements

This method is available for Android Version 21 and above.

Parameters

EsperDeviceSDK.Callback

Usage

sdk.updateAppConfigurations(appConfigurationString, new  EsperDeviceSDK.Callback() {
    
        @Override
        public void  onResponse(@Nullable  Boolean response) {
            Log.d(TAG, "updateAppConfigurations: was settings applied: "  + response);
        }
    
        
        @Override
        public void  onFailure(Throwable throwable) {   
            Log.e(TAG, "updateAppConfigurations: Error: "  + throwable.getMessage());
        }
    
    });
    

Schema:

{
        "managedAppConfigurations": {
            "app_package_name": {
                "key1": "value1",
                "key2": "value2",
                "keyN": "valueN"
            }
        }
    }
    

Manage AppOpp Permissions

Automatically grants permissions to your app without the need to ask an end user’s permission.

Android 6.0 introduced “Special app access” meaning permissions such as “Display over other apps” and “usage access” need manual input from users. The Esper Device SDK allows you to automatically grant these permissions. The AppOp permission constants are available in the io.esper.devicesdk.constants.AppOpsPermissions class.

Parameters

EsperDeviceSDK.Callback

Usage

/**
         * @param appOpMode - integer value of the AppOp permission for which grant status is to be set
         * @param granted   - true or false
         * @param callback  - callback implementation to be invoked upon completion
         *                    of the operation.
         */
        sdk.setAppOpMode(AppOpsPermissions.OP_WRITE_SETTINGS, true, new EsperDeviceSDK.Callback() {
            @Override
            public void onResponse(@Nullable Void response) {
                showToast("Successfully set the permissions");
            }
        
            @Override
            public void onFailure(Throwable t) {
                 showToast("Failed to set the permissions");
                 t.printStackTrace();
             }
         });
        

public class AppOpsPermissions {
            // Write System settings 
            public static final int OP_WRITE_SETTINGS = 23; 
        
            // Screen projection 
            public static final int OP_PROJECT_MEDIA = 46; 
        
            //Draw over other apps 
            public static final int OP_SYSTEM_ALERT_WINDOW = 24; 
        
            //Get process usage stats 
            public static int OP_GET_USAGE_STATS = 43;
        }

USB and File Methods

Getting Removable Storage Path

Returns a cache path to removable storage (such as an SD card). Files inside this path are accessible by other applications.

In Esper SDK version TESSARION_MR12, the Get storage path API was introduced.

Requirements

Requires Android API level 21-29.

Responses

 storage/140C-113C/Android/data

/io.shoonya.shoonyadpc/cache/

InactiveSDKException

InvalidAndroidSdkException

PathNotFoundException

Usage

/**  
    * @param callback - callback implementation to be invoked upon completion of the operation.  
    */  
      
    sdk.getEsperRemovableStorageCachePath(new EsperDeviceSDK.Callback() {  
        @Override  
        public  void  onResponse(@Nullable String response) {  
            Log.d(TAG, "getEsperRemovableStoragePath successful. Path : " + response);  
        }  
    
        @Override  
        public  void  onFailure(Throwable t) {  
            Log.e(TAG, "getEsperRemovableStoragePath failure. Error : " + t.getMessage());  
        }  
    });  
    

Whitelist USB for an App

Whitelist a USB device for a particular application, granting permission for that application to use the USB device.

You can obtain the USB device's Product and Vendor IDs using the Android UsbDevice API.

Requirements

Requires Samsung KNOX enabled devices and Esper Device SDK version SUNFYRE_V8.

Parameters

EsperDeviceSDK.Callback

Usage

sdk.whitelistUsbDeviceForPackage(
           "com.example.app",
           20,  // USB Vendor ID
           20,  // USB Product ID
           new EsperDeviceSDK.Callback() {
               @Override
               public void onResponse(@Nullable Integer response) {
                   showMethodResult("onResponse: Update Result: " + response);
               }
    
               @Override
               public void onFailure(Throwable t) {
                   Log.e(TAG, "onFailure: ", t);
                   showFailureResult(t);
               }
    });
    

Clear USB Whitelist for an app

Clear all USB devices that were whitelisted for an application using the whitelistUsbDeviceForPackage SDK method.

Requirements

Requires Samsung KNOX enabled devices and Esper Device SDK version SUNFYRE_V8.

Parameters

EsperDeviceSDK.Callback

Usage

sdk.clearUsbDeviceWhitelistForPackage(
           "com.example.app",
           new EsperDeviceSDK.Callback() {
               @Override
               public void onResponse(@Nullable Integer response) {
                   showMethodResult("onResponse: Update Result: " + response);
               }
    
               @Override
               public void onFailure(Throwable t) {
                   Log.e(TAG, "onFailure: ", t);
                   showFailureResult(t);
               }
    });
    

Grant or Deny USB Access Permissions for an App

Grant or deny USB access permissions for an app.

Parameter

Responses

The example shown below will grant permissions to the app identified with package name com.example.app. Grant status false will deny the permission.

Once granted via here, the apps no more need to request for permission via ACTION_USB_PERMISSION intent.

Usage

    try {
        usbPermissionManager.setAccessGranted("com.example.app", true);
    } catch (EsperSdkException t) {
        Log.e(TAG, "onFailure: ", t);
        showFailureResult(t);
    }

Get USB Permission Manager

Returns an instance of UsbPermissionManager which can be used for granting or denying USB device/accessory access permissions to packages.

Requirements

Only available for x86, x86_64 and arm64 GSI devices running Esper Foundation for Android.

Usage

sdk.getUsbPermissionManager(new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(@Nullable UsbPermissionManager usbPermissionManager) {
            // use UsbPermissionManager to perform needed actions
        }
      
        @Override
        public void onFailure(Throwable t) {
            Log.e(TAG, "onFailure: ", t);
            showFailureResult(t);
        }
    });
    

About the USB Permission Manager

Compared to the default permission manager of Android, this one can persist permissions across package re-installations, as this one uses the package name instead of UID.

Here it is possible to grant or deny access for all USB devices and accessories to a package in one go, instead of the default one that operates on individual device identifiers.

Check USB Access Permissions for an App

Check the USB's access permissions for an app.

Parameters

Responses

Usage

        try {
            boolean granted = usbPermissionManager.isAccessGranted("com.example.app");
        } catch (EsperSdkException t) {
            Log.e(TAG, "onFailure: ", t);
            showFailureResult(t);
        }

Connection Methods

Start or Stop Mobile Data

Mobile data can be started or stopped.

Requirements

Requires supervisor plugin on Android 5.0+.

Parameters

EsperDeviceSDK.Callback

Responses

Usage

sdk.enableMobileData(false, new EsperDeviceSDK.Callback() {
       @Override
       public void onResponse(@Nullable Boolean response) {
           Log.d(TAG, "onResponse: " + response);
       }
    
       @Override
       public void onFailure(Throwable t) {
           Log.e(TAG, "onFailure: ", t);
       }
    });
    

A Wi-Fi hotspot can be enabled or disabled with a provision to set SSID and password.

For a password-protected hotspot, a minimum of an eight character password needs to be provided. The call will be failed for characters less than eight and greater than zero. If the hotspot is created successfully, the method returns success.

An empty password will create an open Wi-Fi hotspot.

Parameters

Usage

sdk.enableWifiTethering(​"EsperSDKHotspot"​, ​"123123123"​, true, ​new​ ​EsperDeviceSDK​.​Callback​<​String​>() {  
        @Override ​public​ ​void​ onResponse(@Nullable ​String​ response) {
            ​Log​.d(TAG, ​"onResponse: "​ + response);            
        }
        @Override ​public​ ​void​ onFailure(​Throwable​ t) {
            ​Log​.e(TAG, ​"onFailure: "​, t);
        }
    });
    

Start or Stop Wi-Fi Hotspot

A Wi-Fi hotspot can be enabled or disabled with a provision to set SSID and password.

For a password-protected hotspot, a minimum of an eight character password needs to be provided. The call will be failed for characters less than eight and greater than zero. If the hotspot is created successfully, the method returns success.

An empty password will create an open Wi-Fi hotspot.

Parameters

Usage

sdk.enableWifiTethering(​"EsperSDKHotspot"​, ​"123123123"​, true, ​new​ ​EsperDeviceSDK​.​Callback​<​String​>() {  
        @Override ​public​ ​void​ onResponse(@Nullable ​String​ response) {
            ​Log​.d(TAG, ​"onResponse: "​ + response);            
        }
        @Override ​public​ ​void​ onFailure(​Throwable​ t) {
            ​Log​.e(TAG, ​"onFailure: "​, t);
        }
    });

Turn Wi-Fi or Bluetooth for the Device to On/Off

Turn Bluetooth or Wi-Fi off or on for a device.

Parameter

Usage

This method starts processing the Bluetooth/Wi-Fi to true(ON) or false(OFF), but does not necessarily guarantee a state change.

• For the best results, add a listener if the state change is successful. For Bluetooth, you will need to use BluetoothAdapter.ACTION_STATE_CHANGED.

    sdk.changeSettingsState(EsperDeviceSDK.BLUETOOTH,true, new EsperDeviceSDK.Callback<Boolean>() {
        @Override
        public void onResponse(@Nullable Boolean response) {
            if (response) {
                Log.e(TAG, "response: " +response);
            }
        }
    })

Device Methods

Get Device Info

Get an object containing information about an Esper-managed device.

Responses

Usage

sdk.getEsperDeviceInfo(new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(@Nullable EsperDeviceInfo esperDeviceInfo) {
            String deviceId = esperDeviceInfo.getDeviceId();
            if (sdk.getAPILevel() >= EsperSDKVersions.TESSARION_MR2) {
                String serialNo = esperDeviceInfo.getSerialNo();
                String imei1 = esperDeviceInfo.getImei1();
                String imei2 = esperDeviceInfo.getImei2();
                String wifiMacAddress = esperDeviceInfo.getWifiMacAddress();
                String uuid = esperDeviceInfo.getUUID();
            }
         }
    
        @Override
        public void onFailure(Throwable t) {
            t.printStackTrace();
        }
    });
    

When successful, onResponse returns information about the device in a EsperDeviceInfo object. Query the object with the following functions: getDeviceId(), getSerialNo(), getImei1(),getImei2(), getWifiMacAddress(), and getUUID().

When unsuccessful, onFailure triggers a Throwable with one of the following exceptions: EsperSDKNotFoundException or InterruptedException.

Getting Device Settings

The response contains information about device settings as well as the DPC parameters. Device Settings include device details.

Responses

Returns an InactiveSDKException if authentication fails.

If successful, returns a JSON object with the following key-value pairs:

Code Snippet to use Device Settings API:

sdk.getDeviceSettings(new EsperDeviceSDK.Callback() {
       @Override
       public void onResponse(@Nullable JSONObject response) {   
       }
    
       @Override
       public void onFailure(Throwable t) {       
       }
    });
    

If successful, onResponse returns the settings in a JSON Object.

If unsuccessful, onFailure is called.

Sample JSON response:

{
       "adbTimeout":3600000,
       "brightnessScale":9,
       "gpsState":"LOCATION_MODE_SENSORS_ONLY",
       "adbEnabled":false,
       "remoteAdbPort":0,
       "remoteAdbEnabled":false,
       "bluetoothState":false,
       "DPC_PARAMS":{
          
       },
       "audioSettings":[
          {
             "volumeLevel":28,
             "audioStream":"STREAM_RING"
          },
          {
             "volumeLevel":85,
             "audioStream":"STREAM_ALARM"
          },
          {
             "volumeLevel":20,
             "audioStream":"STREAM_MUSIC"
          },
          {
             "volumeLevel":28,
             "audioStream":"STREAM_NOTIFICATION"
          }
       ],
       "remoteAdbIp":"",
       "screenOffTimeout":-1,
       "wifiState":false
    }
    

Getting Device Temperatures

Get the device hardware component's temperatures such as CPU, GPU, Battery, or Skin in Celsius.

Requirements

Requires Android API version 24.

Parameters

Responses

InvalidAndroidSdkException

InternalError

Usage

/**
         * @param type     - type of requested device temperature, one of the following:
         *                 {@link android.os.HardwarePropertiesManager#DEVICE_TEMPERATURE_CPU},
         *                 {@link android.os.HardwarePropertiesManager#DEVICE_TEMPERATURE_GPU},
         *                 {@link android.os.HardwarePropertiesManager#DEVICE_TEMPERATURE_BATTERY} or
         *                 {@link android.os.HardwarePropertiesManager#DEVICE_TEMPERATURE_SKIN}.
         * @param source   - source of requested device temperature, one of
         *                 {@link android.os.HardwarePropertiesManager#TEMPERATURE_CURRENT},
         *                 {@link android.os.HardwarePropertiesManager#TEMPERATURE_THROTTLING},
         *                 {@link android.os.HardwarePropertiesManager#TEMPERATURE_THROTTLING_BELOW_VR_MIN} or
         *                 {@link android.os.HardwarePropertiesManager#TEMPERATURE_SHUTDOWN}.
         * @param callback - callback implementation to be invoked upon completion of the operation.
         *                 In devices running android 7 or above, the callback will return float array
         *                 of temperatures of given type and source.
         *                 Callback's onFailure method returns InvalidAndroidSdkException in case Device is
         *                 running below Android 7
         *                 Callback's onFailure method returns InternalError in case device
         *                 is not able to access {@link android.os.HardwarePropertiesManager}
         *
         */
        sdk.getDeviceTemperatures(HardwarePropertiesManager.DEVICE_TEMPERATURE_CPU, HardwarePropertiesManager.TEMPERATURE_CURRENT, 
                                    new EsperDeviceSDK.Callback<float[]>() {
            @Override
            public void onResponse(@Nullable float[] response) {
                Log.d(TAG, "getDeviceTemperatures successful. temperatures : " + Arrays.toString(response));
                showMethodResult(Arrays.toString(response));
            }
        
            @Override
            public void onFailure(Throwable t) {
                Log.d(TAG, "getDeviceTemperatures failure. error : " + t.getMessage());
                showFailureResult(t);
            }
        });
        

Set Brightness

Set the device’s brightness.

Paremeters

EsperDeviceSDK.Callback

Responses

Usage

    // scale: Integer. The percentage of brightness for the device.
    // EsperDeviceSDK.Callback for the results. Response is boolean with
    // true = success.
    // false = an error occurred.
    
    sdk.setBrightness(10, new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(@Nullable Boolean response) {
            if(response != null) {
                showMethodResult(response.toString());
            }
        }
    
        @Override
        public void onFailure(Throwable t) {
            Log.d(TAG, "Error", t);
        }
    });
    

Set Device Orientation

Set the device’s orientation.

We support five orientations:

1. AUTO
2. PORTRAIT
3. INVERTED PORTRAIT
4. LANDSCAPE
5. INVERTED LANDSCAPE

Parameters

EsperDeviceSDK.Callback

Usage

    Orientation option: String. Constants for multiple options are defined in the EsperDeviceSDK class.
    ROTATION_STATE_AUTO
    ROTATION_STATE_PORTRAIT_ONLY
    ROTATION_STATE_LANDSCAPE_ONLY
    ROTATION_STATE_INVERTED_PORTRAIT_ONLY
    ROTATION_STATE_INVERTED_LANDSCAPE_ONLY
    
    Use EsperDeviceSDK.Callback for the results.
    
    sdk.setDeviceOrientation(orientation, new EsperDeviceSDK.Callback() {
       @Override
       public void onResponse(Boolean response) {
       }
    
       @Override
       public void onFailure(Throwable t) {
           Log.d(TAG, "orientation change failed", t);
           showFailureResult(t);
       }
    });
    

Set Global Settings

Set global settings.

Global system settings contain preferences that apply to all users. Applications may read but cannot write to these settings. Users must explicitly set these preferences from the UI.

The following is a list global settings which doesn't need supervisor:

• "adb_enabled"
• "auto_time"
• "auto_time_zone"
• "data_roaming"
• "usb_mass_storage_enabled"
• "wifi_sleep_policy"
• "stay_on_while_plugged_in"
• "wifi_device_owner_configs_lockdown"
• "bluetooth_on"
• "development_settings_enabled"
• "mode_ringer"
• "network_preference"
• "wifi_on"

Parameters

Key-value Reference:

• To learn about the possible key-value pairs, refer to the official Android documentation on Global Settings.

Usage

sdk.setGlobalSetting(key, value, new  EsperDeviceSDK.Callback() {
        @Override
        public void  onResponse(@Nullable  Boolean response) {
            Log.d(TAG, "setGlobalSetting: is setting applied: "  + response);
        }
    
    
        @Override
        public void  onFailure(Throwable throwable) {
            Log.e(TAG, "setGlobalSetting: Error: "  + throwable.getMessage());
        }
    }
      
    

Set System Settings

Set system settings.

System settings contain miscellaneous system preferences. This table holds simple key/value pairs. setSystemSettings are convenient functions for accessing individual setting entries.

Parameters

Key-Value Reference:

• To learn about possible key-value pairs, refer to the official Android documentation on System Settings.

Usage

sdk.setSystemSetting(key, value, new  EsperDeviceSDK.Callback() {
        @Override
        public void  onResponse(@Nullable  Boolean response) {
            Log.d(TAG, "setSystemSetting: is setting applied: "  + response);
        }
    
        @Override
        public void  onFailure(Throwable throwable) {
            Log.e(TAG, "setSystemSetting: Error: "  + throwable.getMessage());
        }
    }
    
    

Set Screen Timeout

Use this method to set the screen timeout for the device. 

Parameters

EsperDeviceSDK.Callback

Usage

sdk.setScreenTimeOut(timeoutInMills, new EsperDeviceSDK.Callback() {
                    @Override
                    public void onResponse(@Nullable Boolean response) {
                        Log.d(TAG, "screen timeout to " + timeout + " is success : " + response);
                        showMethodResult(getString(R.string.result, "" + response));
                    }
                    @Override
                    public void onFailure(Throwable t) {
                        Log.d(TAG, "Screen Timeout change failed", t);
                        showFailureResult(t);
                    }
                });

Push Telemetry Data

Pushes data to be stored and synced with Quantum but does not need to be fetched or handled by the Quantum Telemetry System.

Parameters

Usage

HashMap<String, Object> data = new HashMap<>();
                    data.put("test", "testValue");
                    data.put("test 2", 123);
                    
                    /**
                     * @param name Name of the Custom Telemetry Data Type
                     * @param id   Id of the Custom Telemetry Data Type must be between 2000 and 3000
                     * @param data the data pertaining to the custom Telemetry type
                     */
                    sdk.pushTelemetryData("Sdk Test Telemetry", 1001, true, data, new EsperDeviceSDK.Callback() {
                        @Override
                        public void onResponse(@Nullable Void response) {
                            Log.d(TAG, "pushTelemetryData: onResponse - hence success");
                        }
                    
                        @Override
                        public void onFailure(Throwable t) {
                            runOnUiThread(() -> Toast.makeText(MainActivity.this, "pushTelemetryData: onFailure - " + t.getMessage(), Toast.LENGTH_SHORT).show());
                            Log.e(TAG, "pushTelemetryData: onFailure - " + t.getMessage(), t);
                        }
                    });
                    

Reboot Device via Esper Device SDK

Reboot the device.

Requirements

Requires Android 7.0 and above.

The Reboot API was introduced in Esper SDK version TESSARION_MR5.

A callback in arguments is required to enable the Reboot function.

Usage

sdk.reboot(new EsperDeviceSDK.Callback() {
       @Override
       public void onResponse(Void response) {
       }
    
       @Override
       public void onFailure(Throwable t) {
           Log.e(TAG, "onFailure: ", t);
       }
    });
    

Manage Dock

Show or hide the Esper menu. 

In Kiosk-mode, a device user may access hidden Esper settings by tapping three times on the top-right corner or by hitting the power button three times. This method allows you to show or hide from within your app.

Requirements

Only available for devices in Kiosk mode.

Usage

Show Dock:

Shows the chevron shortcut to the Esper Settings app. 

sdk.showDock(new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(Void response) {
            showToast(R.string.success);
        }
    
        @Override
        public void onFailure(Throwable t) {
            t.printStackTrace();
            showToast(R.string.failure);
        }
    });
    

sdk.startDock(new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(Void response) {
            showToast(R.string.success);
        }
    
        @Override
        public void onFailure(Throwable t) {
            t.printStackTrace();
            showToast(R.string.failure);
        }
    });
    

Hide Dock:

Hides the chevron and the associated Esper Settings app.

sdk.stopDock(new EsperDeviceSDK.Callback() {
        @Override
        public void onResponse(Void response) {
            showToast(R.string.success);
        }
    
        @Override
        public void onFailure(Throwable t) {
            t.printStackTrace();
            showToast(R.string.failure);
        }
    });
    

Power Off the Device

Use this method to power off the device.

Requirements

This method is only available for devices with Supervisor, Knox-supported devices & CSDK-supported devices.

Usage

sdk.powerOff(new EsperDeviceSDK.Callback() {
                                    @Override
                                    public void onResponse(@Nullable Boolean response) {
                                        Log.d(TAG, "performPowerOff: onResponse: " + response);
                                        showMethodResult(getString(R.string.result, "" + response));
                                    }
                        
                                    @Override
                                    public void onFailure(Throwable t) {
                                        Log.e(TAG, "performPowerOff: onFailure: ", t);
                                        showFailureResult(t);
                                    }
                                });
                    
                    

Disable Users from Powering Off Devices

Enables or disables the ability for an end user to turn off the device if they press the power button.

Once disabled:

• Can only be enabled if a call is made to re-enable it.
• A notification “Security policy prevents power off” will appear when the end user tries to power down the device.

Requirements

Only available on Samsung KNOX-enabled devices, or via a Supervisor plugin and the Esper Device SDK version TESSARION_MR8.

Responses

The allowPowerOff function returns a boolean if allowing or disallowing power off was successful.

sdk.allowPowerOff(true/false, new EsperDeviceSDK.Callback<Boolean>() {
        @Override
        public void onResponse(@Nullable Boolean response) {
            Log.d(TAG, "onResponse: " + response);
            showMethodResult(getString(R.string.result, "" + response));
        }
        @Override
        public void onFailure(Throwable t) {
            Log.e(TAG, "onFailure: ", t);
            showFailureResult(t);
        }
});