ProKiosk

This topic describes how to create a purpose-built device for different vertical markets, using a ProKiosk mode which lets you fully customize a device.

About Knox Customization

Knox Customization is a comprehensive set of tools and services that allows businesses to customize and deploy end-to-end mobile solutions.

You can develop purpose-built devices for vertical markets, for example, informational kiosks for hospitality, in-flight entertainment systems for airlines, or point-of-sales devices for the retail industry.

Through the Knox SDK, you have full control over the device, controlling settings such as:

• ProKiosk Mode — Enable or disable the ProKiosk Mode, which restricts the device to a single app and limits the functionality of the device.
• Android Settings — Manage Android Settings.
• Animation — Set bootup and shutdown animations to show organizational logos.
• Auto answer incoming calls — Configure and manage auto answer incoming call numbers.
• Bluetooth — Toggle Bluetooth state.
• Hard key — Enable or disable hard key intent reporting in ProKiosk Mode.
• Home activity — Set the activity to launch when the home button is pressed in ProKiosk Mode.
• Home screen — Add or remove shortcuts and widgets from homescreen.
• Locale — Set system locale.
• Lock screen — Customize the lock screen shortcuts.
• Notifications — Suppress system-wide notifications to deliver a clean UX to end users.
• Power ON/OFF control — Customize automatic power ON/OFF for the devices with the Custom APIs.
• Quick panel — Add or remove items from the status bar’s quick panel.
• Ringtone — Customize the ringtone or notification sound.
• Status bar — Show or hide individual elements of the status bar, including notifications.
• USB — USBnet wired IP connectivity, dynamically authorize USB accessories, ADB control.

Unlike the basic Kiosk mode which is free, ProKiosk mode requires that systems integrators pay a subscription fee through their Knox Platform for Enterprise (KPE) license key.

Activate device administrator

To use Samsung Knox API methods to control Android settings, system behavior, and put the device in ProKiosk Mode, we must Active device administrator.

Android’s Device Administration API provides system-level device administration capabilities that enable the creation of apps that can take control of a device. Android’s Device Administration provides an in-depth explanation of using the Device Administration API to create device admin apps.

The Knox SDK provides additional control over Samsung devices and also provide significantly more policies than standard Android. You can use the combined features of the Device Administration API and the Samsung Knox SDKs to create device admin apps that provide a fine-grained customized experience on Samsung devices.

When an app requests device administrator privileges, the user is presented with a dialog that allows them to choose whether to grant device administrator status to the app.

To create a device admin app, you must include a receiver class in your app and include it in your app’s manifest. Your receiver must be a subclass of DeviceAdminReceiver that has both the BIND_DEVICE_ADMINpermission and the ability to respond to the ACTION_DEVICE_ADMIN_ENABLED intent, and the manifest must also include a list of the security policies being used.

The app’s AdminReceiver subclasses DeviceAdminReceiver. It’s included in AndroidManifest.xml as follows:

<receiver
    android:name="com.samsung.sample.sample1.AdminReceiver"
    android:label="@string/app_name"
    android:permission="android.permission.BIND_DEVICE_ADMIN" >
    <meta-data android:name="android.app.device_admin"
    android:resource="@xml/device_admin" />
    <intent-filter>
        <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
    </intent-filter>
</receiver>

For more background on the <receiver> element of the Android Manifest file, refer to Android’s documentation.

Declaring the permissions

To use Samsung Knox API methods to control Android settings, system behavior, and put the device in ProKiosk Mode, we must declare the permissions in the manifest.

<!-- Declare the Knox permissions used by this app -->
<uses-permission android:name="com.samsung.android.knox.permission.CUSTOM_PROKIOSK"/>
<uses-permission android:name="com.samsung.android.knox.permission.CUSTOM_SETTING"/>
<uses-permission android:name="com.samsung.android.knox.permission.CUSTOM_SYSTEM"/>

<application
    <!-- Enable selective Knox permissions -->
    <meta-data android:name="com.samsung.knoxlicense.permissions" android:value="true"/>
            :
</application>

These policies are presented to the user as potential operations the app can perform if the user chooses to activate the app as a device administrator.

Initializing the app

In the sample app, if the app isn’t a device administrator when the app starts, then the onCreate() method starts the DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN activity to add the app as a device administrator:

ComponentName deviceAdmin = new ComponentName(this, AdminReceiver.class);
DevicePolicyManager dpm = (DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE);
if(!dpm.isAdminActive(deviceAdmin)) {
    try {
        Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN);
        intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, deviceAdmin);
        intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION, "");
        startActivity(intent);
}

Enter ProKiosk Mode

After activating your Knox Platform for Enterprise (KPE) license key, you can use the Knox SDK to enable Pro Kiosk mode on the device.

To activate ProKiosk mode, call the ProKioskManager method setProKioskState(true,passCode), where passCode is a pass code that you set up to disable ProKiosk mode and revert to full device access. To enable ProKiosk mode in MainActivity.onClick():

// The passcode is defined at start of MainActivity:
private final String mPassCode = "12345";
try {
    int result = 0;
    // Enable ProKiosk mode
    CustomDeviceManager cdm = CustomDeviceManager.getInstance();
    ProKioskManager pkm = cdm.getProKioskManager();
    result = pkm.setProKioskState(true, mPassCode);

    // ProKiosk mode enabled, now enable the 'OFF' button and disable the 'ON' button
    ((Button)findViewById(R.id.buttonProKioskOFF)).setEnabled(true);
    ((Button)findViewById(R.id.buttonProKioskON)).setEnabled(false);
   ...

Customize device settings

When you activate ProKiosk Mode on a device, any custom configuration settings that you specified take effect. There are some features/settings that are set to hidden/disabled in ProKiosk Mode.

For example, you might want to hide all of the status bar icons and display the time when you lock down the device.

The following APIs allow you to hide status bar icons and show the clock in ProKiosk Mode:

pkm.setStatusBarIconsState(false);
pkm.setStatusBarClockState(true);

For details about all the other device settings that you can control in ProKiosk mode, browse the Knox SDK API reference for the package com.samsung.android.knox.custom.

Exit ProKiosk Mode

You should ensure that your app includes a way to exit ProKiosk Mode. You need to be out of these modes to perform device maintenance, such as software updates, and use other device functionality outside of the app.

To exit ProKiosk mode, call setProKioskState(false,passCode).

To set this up in MainActivity.onClick():

try {
    int result = 0;
    // Disable ProKiosk mode
    CustomDeviceManager cdm = CustomDeviceManager.getInstance();
    ProKioskManager pkm = cdm.getProKioskManager();
    result = pkm.setProKioskState(false, mPassCode);

    // ProKiosk mode disabled, now enable the 'ON' button and disable 'OFF' button
    ((Button)findViewById(R.id.buttonProKioskON)).setEnabled(true);
    ((Button)findViewById(R.id.buttonProKioskOFF)).setEnabled(false);
       ...

Disable power saving mode