Development

Step 1: Preparing the area

Open the Android Studio IDE, and open the starting version of the Kiosk Mode sample app.

1. Go to File > Open to access the Open File or Project window.

   

2. In the Open Project window, look for and select the kioskmode Android app project, and press OK.

   

   Tip :

   Learn more by watching the video

   
   

3. The project should automatically kickoff a Gradle build when opened and display results in the Build Output toolbar. You can also start the build by navigating to Build > Rebuild Project.

4. Project structure should look like below (Project structure window at the left side of the window).

   

5. Open Constants.java from the project structure by navigating to java > Constants.

6. Fill in String KPE_LICENSE_KEY = with your license key.

   To get a license refer to:
   https://docs.samsungknox.com/dev/common/tutorial-get-a-license.htm

   Tip :

   Learn more by watching the video

   
   

Step 2: Running and using the app

Before we get started with coding and developing, let’s see how the app works.

Building and running the app

1. Clean and rebuild the project by going to Build > Rebuild Project.

   Note :

   This is a highly recommended step rather than performing Make Project or clicking the hammer icon at the top right sidebar.

2. On your device (e.g. Galaxy Note10 or S10),

   a. Activate developer mode by going to Settings > About phone > Software information and tapping the Build number 7 times.

   b. Navigate back to the main Settings page and go to the Developer options category. Toggle on Stay awake and USB debugging.

3. Back in Android Studio, select the device that you want to run your app on from the target device drop-down menu.

   

4. Run the app by clicking Play button, pressing Shift + F10, or going to Run > Run ‘app’. Wait for it to load, and you should see this screen:

   

Using the app

There are three mandatory steps when running an app that uses the Knox SDK:

1. Tap Activate Admin. A pop-up screen will ask you to activate the device admin app, letting you to have admin control over your device. Tap Activate.

   

2. Tap Activate License. Wait for a few seconds for a message at the bottom of the app to prompt you that license activation is successful.

   

3. Tap Grant Permissions. The permission com.android.launcher.permission.INSTALL_SHORTCUT should have been successfully granted.

To complete this app, we need two major features: displaying a default kiosk, and displaying a customized kiosk.

Step 3: Toggling a default kiosk screen

We will first add a button that can toggle a default kiosk screen. This screen will show your device’s homepage with only the Kiosk Mode app itself, hiding other apps and widgets on that page.

Adding the Toggle Default Kiosk button

1. Open the main activity’s appearance file (activity_main.xml) from the project structure by navigating to res > layout > activity_main.xml.

   

2. We can add a button in two ways: visually and programmatically. This step will demonstrate the first, but longer way to do it.

   a. Inside the Palette window at the top left, make sure to be in the Common category and click on Button. Hold and drag the new button element onto the middle of the Design surface, on top of the other buttons.

   

   b. Inside the Attributes window at the top right, fill in the following fields:

   Declared attributes

   • id = @+id/toggleDefaultKioskBtn

   • text = @string/toggle_kiosk

   Layout

   • layout_width = 200dp

   • layout_height = wrap_content

   c. Open the All Attributes panel by the bottom of the Attributes window and fill in the following fields:

   • layout_alignStart = @id/toggleAdminBtn

   • layout_below = @id/grantPermissionsBtn

   

The new button should look like this:

If you transfer to the Text tab at the bottom of activity_main.xml’s appearance window, you should be able to see the code for the new button.

3. Open the main activity’s behavior file (MainActivity.java) from the project structure by navigating to java > com.samsung.knox.example.kioskmode > MainActivity.java.

4. Declare and define our new button.

   • In the list of declared variables above the onCreate(Bundle savedInstanceState) method, add:

     private Button mToggleDefaultKioskBtn;
     

   • In the list of defined variables at the start of onCreate(), add:

     mToggleDefaultKioskBtn
     = (Button) findViewById(R.id.toggleDefaultKioskBtn);
     

   • In the list of initialized onClick listeners inside onCreate(), add:

     mToggleDefaultKioskBtn.setOnClickListener(new
     View.OnClickListener() {
         @Override
         public void onClick(View v) {
             toggleKiosk();
         }
     });
     

   

Implementing the behavior for the Toggle Default Kiosk button

5. Look for the toggleKiosk() method, write the following code, and fill in the missing methods:

   private void toggleKiosk () {
       try {
           EnterpriseDeviceManager enterpriseDeviceManager = EnterpriseDeviceManager.getInstance(this); // Instantiate the EnterpriseDeviceManager class
           KioskMode kioskMode = enterpriseDeviceManager.getKioskMode(); // Get the KioskMode object where the enable/disableKioskMode method lives
   
           boolean kioskState = kioskMode.isKioskModeEnabled(); // Check whether Kiosk Mode is enabled.
   
           if (kioskState) { // If in Kiosk Mode, disable Kiosk Mode
               mUtils.log(getString(R.string.leaving_kiosk));
               removeShortcutFromKioskMode();
               kioskMode.disableKioskMode();
           } else { // If not in Kiosk Mode, enable Kiosk Mode with the current package as the home package
               mUtils.log(getString(R.string.entering_kiosk));
               addShortcutToKioskMode();
               kioskMode.enableKioskMode();
           }
       } catch (SecurityException e) {
           mUtils.processException(e, TAG);
       }
   }
   
   

   You can look for these missing methods in the Knox SDK v3.4 API reference. If you look at the classes for these missing methods, these are Enterprise Device Manager and Kiosk Mode. Also, the comments attached to these methods act as hints to help you find them.

   Tip :

   Learn more by watching the video

   
   
   

Testing the Toggle Default Kiosk button

1. Rebuild and run the app again

2. Tap Toggle Default Kiosk. It shows you a screen with just the Kiosk Mode app shown, and a few empty scrollable pages.

   

3. To navigate out of this kiosk state, tap the Kiosk Mode app and hit Toggle Default Kiosk.

   Note :

   You can also exit Kiosk Mode by going back to Android Studio, hitting Stop ‘app’, and running the app again.

Step 4: Toggling a custom kiosk screen

Next, we will add a button that can toggle a custom kiosk screen and let you customize it. This screen will show your device’s homepage, with other apps and widgets that you want on that page or allowed in your app’s operations.

Adding the Toggle Custom Kiosk button

1. Open activity_main.xml, and add the button – this time, by directly writing the code for it in the Text tab. You can write it below the code block for our Toggle Default Kiosk button:

   <Button
       android:id="@+id/toggleCustomKioskBtn"
       android:layout_width="200dp"
       android:layout_height="wrap_content"
       android:layout_below="@id/toggleDefaultKioskBtn"
       android:layout_alignStart="@id/toggleAdminBtn"
       android:text="@string/toggle_kiosk_settings" />
   

   The new button should look like this:

   

   Tip :

   Learn more by watching the video

   
   

2. Go back to MainActivity.java. Declare and define our new button, following the same three steps for Toggle Default Kiosk:

   private Button mToggleCustomKioskBtn;
   

   mToggleCustomKioskBtn = (Button)
   findViewById(R.id.toggleCustomKioskBtn);
   

   mToggleCustomKioskBtn.setOnClickListener(new
       View.OnClickListener() {
           @Override
           public void onClick(View v) {
               promptCustomKioskSetting();
           }
       });
   

Implementing the behavior for the Toggle Custom Kiosk button

1. Look for the toggleCustomKiosk(KioskSetting kioskSetting) method and write the following code:

   private void toggleCustomKiosk (KioskSetting kioskSetting) {
       try {
           EnterpriseDeviceManager enterpriseDeviceManager = EnterpriseDeviceManager.getInstance(this); // Instantiate the EnterpriseDeviceManager class
           KioskMode kioskMode = enterpriseDeviceManager.getKioskMode(); // Get the KioskMode object where the enable/disableKioskMode method lives
   
           boolean kioskState = kioskMode.isKioskModeEnabled();
   
           if (kioskState) { // If in Kiosk Mode, disable Kiosk Mode
               mUtils.log(getString(R.string.leaving_kiosk));
               removeShortcutFromKioskMode();
               kioskMode.disableKioskMode(kioskSetting);
           } else { // If not in Kiosk Mode, enable Kiosk Mode with provided Kiosk Mode settings
               mUtils.log(getString(R.string.entering_kiosk));
               kioskMode.enableKioskMode(kioskSetting);
           }
       } catch (SecurityException e) {
           mUtils.processException(e, TAG);
       }
   }
   
   

   Tip :

   Learn more by watching the video

2. Go to the promptCustomKioskSetting() method. Look for the onClick() method of builder.setPositiveButton, and add:

   KioskSetting kioskSetting = new KioskSetting();
   kioskSetting.settingsChanges = chkSettingsChanges.isChecked();
   kioskSetting.statusBar = chkStatusBar.isChecked();
   kioskSetting.statusBarExpansion = chkStatusBarExpansion.isChecked();
   kioskSetting.systemBar = chkSystemBar.isChecked();
   kioskSetting.taskManager = chkTaskManager.isChecked();
   kioskSetting.homeKey = chkHomekey.isChecked();
   kioskSetting.airCommand = chkAirCommand.isChecked();
   kioskSetting.airView = chkAirView.isChecked();
   kioskSetting.multiWindow = chkMultiwindow.isChecked();
   kioskSetting.smartClip = chkSmartclip.isChecked();
   kioskSetting.navigationBar = chkNavBar.isChecked();
   kioskSetting.wipeRecentTasks = chkWipeRecentTasks.isChecked();
   kioskSetting.clearAllNotifications = chkClearNotifications.isChecked();
   
   toggleCustomKiosk(kioskSetting);
   
   

   These are the different settings available in Kiosk Mode. You can learn more about them in the Kiosk Mode API documentation we discussed earlier, especially the enableKioskMode(KioskSetting kioskSetting) method.

3. Finally, find the refreshButtons() method and uncomment the code snippets that set the text prompts for our two new buttons.

   Tip :

   Learn more by watching the video

   
   

Testing the Toggle Custom Kiosk button

You can now run the complete version of your purpose-built device.

1. Rebuild and run the app again, as we did for the Toggle Custom Kiosk button.

2. Tap Enter Custom Kiosk Mode and choose the settings that you want allowed or shown on the home screen.

   

3. Tap Confirm. You are now in your customized kiosk.

4. To navigate out of this kiosk state, you can go back to Android Studio, hit Stop ‘app’, and run the app again.

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab activity. Now, you can develop a kiosk mode using Knox SDK by yourself! You can learn more about kiosk mode and how it caters to your business needs in our Knox SDK developer guide.

If you're having any trouble with the activity, you may check out the link below.