14 Jun 2019

Knox Code Bytes: Manage geofencing services

By Josh (Programmer Writer)

Welcome to the third Knox Code Bytes blog post. Throughout this series, we walk you through some of our most popular API calls. This series is also meant for those who are new to the SDK, have not used all the APIs yet, or want to improve their understanding of the Knox security platform.

This blog describes common ways to use a device’s location to tailor your app behavior. From retail to hospitality, there are a wide variety of use cases for location-based services.

Consider the layout of a multi-leveled department store and the vast number of products it contains. Using the customer’s precise location, instructions can be generated that will guide them directly to the product they are looking for. Another use case might be to notify an IT admin if an enterprise device leaves the enterprise perimeter. In this case, you can set up a geofence to identify the enterprise perimeter. Here are some additional specific examples:

  • You can check if a resident wanders off an elder care nursing home by scanning if their device is within inside the facility.
  • You can geofence a small compact area, like a retail store, by increasing the number of checks for geofence monitoring.

Calling the API methods from Knox’s Geofencing class can strengthen the security and functionality of your app. These APIs provide information about the device’s location, letting you see what the user needs and how they will interact with that location.

Let’s get started with this Knox Code Bytes.

 

NOTE: This tutorial assumes you have a basic understanding of Android Studio and have already set up the Knox SDK to call Knox APIs. Learn about installing the Knox SDK, setting up device admin, and licensing the Knox SDK before continuing.

 

What will we discuss in this blog post?

 

 

Code setup

To start, we need to set up the app that calls these features.

Open the Android Studio project to where you intend to add geofencing. Create a method that performs you­r intended tasks. Give it a descriptive name, such as manageGeofencing. Your main UI elements can then call this method, for example, through its onClick() method when the app user clicks a button or through calling it from your mainActivity.

When writing this method, start with the following two API calls:

// Create an instance of a device manager that contains API methods for granular device control
EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(this);

// Create the object to create, destroy, and monitor geofences
Geofencing geofencingService = edm.getGeofencing();

Next, in the AndroidManifest.xml file, request the following permission with a signature-level protection to use the APIs:

<uses-permission android:name="com.samsung.android.knox.permission.KNOX_GEOFENCING" />

Note: Declaring these permissions is important so that the Android OS can grant the app the ability to perform geofencing operations.

 

 

Geofence a device

After writing the first two API calls and requesting the Knox Restriction permissions in your manifest file, you can use any of the following seven code snippets. These seven features do not require a paid license to manage, meaning you can use them to secure your device for free.

 

Create a geofence

public int createGeofence(Geofence geofence)

Use this API call to create either a circular, polygonal, or linear geofence.

To create a geofence with a radius of 50 meters, type:

LatLongPoint center = new LatLongPoint(50, 50);
double radius = 50;
CircularGeofence circularGeofence = new CircularGeofence(center, radius);
int id = geofencingService.createGeofence(circularGeofence);
return id;

 

Check if the device is within a created geofence

public List<Integer> isDeviceInsideGeofence()

This API call lets you check whether a device is within any predefined geofences. It returns a list of geofence ids within which a device is located or null if a device is outside all geofences.

To implement this call in your method, type:

List listofGeofences = geofencingService.isDeviceInsideGeofence();

 

Set and get the minimum geofencing time parameter

public boolean setMinTimeParameter(long time)
public long getMinTimeParameter()

This API call lets you configure and retrieve the minimum time interval to control how frequent geofence checks should be performed.

To implement these calls in your method, type:

//Setting the minimum geofencing time parameter
boolean result = geofencingService.setMinTimeParameter(60000);
//Getting the minimum geofencing time parameter
long minTime = geofencingService.getMinTimeParameter();

 

Start geofencing

public boolean startGeofencing()

Use this API call to start geofence monitoring. To implement this call in your method, type:

boolean result = geofencingService.startGeofencing();

 

Stop geofencing

public boolean stopGeofencing()

Use this API call to stop geofence monitoring. To implement this call in your method, type:

boolean result = geofencingService.stopGeofencing();

 

 

Next steps

 

 

Knox Code Bytes 2019 blog series

Check our SEAP blog site every month for new posts on commonly used API calls in the Knox SDK. This blog series runs from February to August 2019.