Integrating the Android System Service Application

Some enterprises use devices that are customized for their requirement. For example having a custom android device that functions as a POS. In such situations, organizations prefer to have and maintain custom firmwares or get device vendors to build a custom device to suite their requirement. For example, apps or devices having the capability to sign their POS app with the vendor firmware signing key and install it on devices as a system app.

WSO2 IoT Server provides a separate service application that can be signed by a firmware signing key and installed on the devices as a system application alongside the Android Agent application. This enables you to have better control over the devices registered with WSO2 IoT Server. Since this is a system app, it provides system level capabilities, such as device firmware upgrade, reboot and enforcing security policies, and much more.

For more information on managing the system service Android application see the following subsections:

Securing Communication

When the system service app is installed on a device that is registered with WSO2 IoT Server, the Android agent communicates with it to trigger system level operations from WSO2 IoT Server. The communication between the system service application and the Android agent is secured by two layers of protection as listed below:

Via the signature - The system will grant permission only if the requesting application is signed with the same certificate as the application that is declared in the permission.

For more information on securing the communication, see <permissions> on the Android Developer documents.
Check the package name of the intent who makes the call to verify that it’s a request from the Android agent.

Integrating the system service application

Follow the steps given below to integrate the system service Android application:

Build the system service application.
1. Download the source code.
2. The system service app can not be built via the usual Android developer Software Development Kit (SDK), as it requires access to developer restricted APIs. Therefore, you need to replace the existing android.jar file that is under the <SDK_LOCATION>/platforms/android-<COMPILE_SDK_VERSION> directory with the explicitly built android.jar file that has access to the restricted APIs. You can get the new jar file using one of the following options:
  - Download the Android Open Source Project (AOSP) and build the source code to get the jar file for the required SDK level.
  - Use a pre-built jar file from a third party developer. You can find it here.
    
    Make sure to use the jar file that matches the compileSdkVersion of the WSO2 Android agent. The current compileSdkVersion is 25.
3. Open the system service application source code via Android Studio and clean build it as a usual Android application.
Sign the application via the device firmware signing key. If you don’t have access to the firmware signing key, you have to get the system application signed via your device vendor.

For more information of singing the system service, see Signing Your Applications.
Install the system service application by following any of the methods given below:
- If you have your own firmware, the system service application is available out of the box with your firmware distribution.
  1. Copy the signed system service APK file to the /system/priv-apps directory of the device.
  2. When the device boots or restarts for the first time, it automatically installs the application as a system application.
- Install the system service application externally via an Android Debug Bridge (adb) command.
  
  For more information on how this takes place on WSO2 IoTS, see Configuring the service application.
Enable the system service invocations through the WSO2 Android Agent application.
Click here for more information on cloning the Android agent.
Clone the cdmf-agent-android GIT repository. This is referred to as <ANDROID_AGENT_SOURCE_CODE> throughout this document.

https://github.com/wso2/cdmf-agent-android.git -b <ENTER_THE_VERSION>

Check the WSO2 IoT Server and Agent Compatibility and find out what branch of this repo you need to clone.
Open the client folder that is in the <ANDROID_AGENT_SOURCE_CODE> via Android Studio.
Make sure to sign the Android agent using the same device firmware signing key that was used to sign the System Service Application, else you run into security exceptions.

Navigate to the Constants.java class, which is in the org.wso2.iot.agent.utils package and configure the SYSTEM_APP_ENABLED field as follows:
```
 public static final boolean SYSTEM_APP_ENABLED = true;
```
Rebuild the Android agent application.

Install the Android agent you just built to your mobile device.
You need to copy the APK to you device and install it. For more information on installing the Android agent, see Registering an Android device. Follow the steps from step 6 onwards.

Operations supported via the system service application

The following operations are supported via the system service application:

Device Reboot	Restart or reboot your Android device.
Firmware upgrade	Upgrade the firmware of Android devices.
Enforcing user restrictions	Restrict different functions on the user's device using this REST API. When adding a policy you will have the option of saving the user restriction policy or saving and publishing the user restriction policy.
Silent app installation, removal and update	Application installation, removal and update will be performed without the user's confirmation when the Android system service application is available on an Android device. This operation is only available for enterprise applications (apps that were created by your organization) and is not available for public applications (publicly available apps, such as free apps available online).