Site Information Service

Site Information Service is a Launcher feature that pinpoints the current store/branch of a device based on either its current location, IP range, or connected AP Mac addresses.

Overview

Location-aware applications or location-based services (LBS) provide real-time insights and visibility into device location. This, in turn, enables organizations to monitor device usage patterns, identify underutilized devices, and ensure the security of sensitive data. Site Information Service is a Launcher feature that helps determine the device location based on either its current GPS location, IP range, or connected AP MAC addresses.

User Guide

Based on GPS Location

1. A CSV file named sitelist.csv file is pushed to the device into the Launcher files folder. This file will contain the Organization's list of Sites and their GPS coordinates.

2. When the device boots up, the Launcher will use the device location services to determine its current GPS coordinates.

3. If the device's GPS coordinates are within a configurable range (e.g. 200 meters) of any of the locations listed in sitelist.csv, the Launcher will use that as the device site.

4. If the device is close to multiple locations, the user may be prompted to select which location they are currently at.

5. If the device is not close to any of the listed locations, the user will be prompted to manually select their location.

6. To determine the device location, the search algorithm checks the nearest GPS coordinates. Optionally, a fall-back option may be set to refer the device site information from an IP range, subnet, and access point.

Based on Device IP Address

1. A CSV file named sitelist.csv file is pushed to the device into the Launcher files folder. This file will contain the Organization's list of Sites and their GPS coordinates.

2. When the device boots up, the Launcher will connect to a pre-configured Wi-Fi Access Point so that it can be assigned a site-specific IP address.

3. The device IP address will then be matched to a corresponding iprange value in sitelist.csv, to determine the device site.

4. If the device does not match any of the listed locations, the user can be prompted to manually select their location.

5. To determine the device location, the search algorithm checks the nearest GPS coordinates. Optionally, a fall-back option may be set to refer the device site information from an IP range, subnet, and access point.

Based on the Access Point

1. A CSV file named sitelist.csv file is pushed to the device into the Launcher files folder. This file will contain the Organization's list of Sites and their GPS coordinates.

2. When the device boots up, the Launcher will connect to a pre-configured Wi-Fi Access Point so that it can be assigned a site-specific IP address.

3. The device can reference the Access Point MAC Address to match the corresponding apmacaddress in sitelist.csv, to determine the device site.

4. If the device does not match any of the listed locations, the user can be prompted to manually select their location.

5. To determine the device location, the search algorithm checks the nearest GPS coordinates. Optionally, a fall-back option may be set to refer the device site information from an IP range, subnet, and access point.

Feature Configuration

To set up Site Information Service for a particular device profile or device group, please follow the steps below:

Creating a Location File

Create a CSV file named sitelist.csv containing all known sites for where the device is expected to be used.

Column Header	Description
siteid	Unique ID of the site/store/branch, which will be used to locate the site within the BlueFletch Portal
sitename	The name of the site/store/branch that will be displayed on the Launcher home screen.
latitude	The gps latitude of the respective site
longtitude	The gps longtitude of the respective site

Add the following columns if using a different method of location other than GPS coordinates. These can also be used as fallback.

Column Header	Description
iprange	The IP ranges for the network expected at the respective site. Multiple ranges are supported by separating with a semi-colon, e.g.: One range: 192.3.4.1-192.3.4.255 Multiple ranges: 192.3.4.1-192.3.4.255;192.3.5.1-192.3.5.200
apmacaddress	The mac addresses of the APs that this device is expected to connect to, separated by semi-colons, e.g.: 6a:9c:f0:00:83:2f;c2:f5:f8:fb:15:31
subsequent columns	Values that will be injected into the configuration's extended attributes for the location selected. The column name will be the field name. Commonly used for Site Group filters in the Portal.

Exporting the File

Export the file as a CSV (comma delimited file) and push the sitelist.csv to the device folder /sdcard/Download/ems/.

The equivalent ADB command is:

adb push sitelist.csv /sdcard/Download/ems/sitelist.csv

Enabling Site Information Service

In your launcher.json configuration file under settings, enable the useSiteInfoService flag to true. You can also change the distanceInMeters value based on the radius from the site’s GPS coordinates:

"settings":{
    …
    "useSiteInfoService" : true,
    "distanceInMeters" : 200,
    …
}

Setting Site List with Portal Sites

The BlueFletch Portal website gives the option of uploading a site list to the Sites page, so that the Portal can filter dashboards by all of the organization's stores and locations. Uploading a site list to the Portal also allows that file to be distributed to all devices.

The Launcher configuration's settings parameter sitelistUrl can be configured to point to the active site list from the Portal using the following pattern:

https://ems-services-api.bluefletch.com/playbook/apiv1/sites/current/download?apikey=<API key>&ts=<any numeric pattern>

The API key can be found on the Admin - Security sub-tab in the Portal.

When changes are made to the active site list on the Portal, the updated list must be applied to devices by modifying the URL string. BlueFletch recommends incrementing the ts value in the URL to reflect the update. For example:

Initial URL:

https://ems-services-api.bluefletch.com/playbook/apiv1/sites/current/download?apikey=xxxx67gR20H854dfspe6bb3809144nqKyw6c5N22&ts=000000

Updated URL:

https://ems-services-api.bluefletch.com/playbook/apiv1/sites/current/download?apikey=xxxx67gR20H854dfspe6bb3809144nqKyw6c5N22&ts=000001

This ensures devices recognize and apply the latest site list changes effectively.

Setting Up Site List Automatic Updates

In Launcher 4, users can have access to the latest site list without manual sitelistUrl changes. To configure automatic updates, use the following parameter in the Launcher configuration:

"settings":{
    …
    "useSiteInfoService": true,
    "sitelistUrl": "https://ems-services-api.bluefletch.com/playbook/apiv1/sites/current/download?apikey=xxxx67gR20H854dfspe6bb3809144nqKyw6c5N22&ts=000001",
    "siteListPollingIntervalMinutes": 1440
    …
}

Default is set to 1440 minutes (24 hours) On reboot, Launcher will update the current site list with the latest version.

Custom Site Finder

Custom Site Finder is a Launcher feature that enables customer to build their own service to determine the location of a device, which may not be covered by the above functionality. To use this functionality, the customer shall create a separate application to be installed on the device, that contains an Android Service that broadcasts the siteId back to the Launcher.

User Guide

1. If the custom Site Finder feature is enabled on the device configuration, it will trigger the onStartCommand method to run.

2. Once the siteId is found, the custom service will broadcast it back to the Launcher using the sendSiteResponse method.

3. The sendSiteResponse method will create an intent with the siteId information and broadcast it back to the Launcher application.

4. When the Launcher receives the siteId, it will search for the corresponding site record in the sitelist.csv using the siteId and use the resolved row.

5. If the siteId is empty or null, the user will receive a message that the site could not be found, and will be prompted to manually select one from the list.

Building the Custom Service

Use the following sample code below as a guide:

package com.bluefletch.services;

public class CustomSiteFinder extends Service {

    private static final String ACTION_SITE_RESPONSE = "com.bluefletch.sitelocationservice.action.SITE_RESPONSE";
    private static final String EXTRA_REQUESTED_SITEID = "com.bluefletch.sitelocationservice.extra.REQUESTED_SITE_ID";
    private static final String LAUNCHER_PACKAGE_NAME = "com.bluefletch.ems.emm.launcher";
    ...

    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {

        // TODO: perform your custom processing here
        String siteId = getCurrentSiteId();
        this.sendSiteResponse( siteId );

        return START_NOT_STICKY;
    }

    private void sendSiteResponse(String siteId) {

        Intent intent = new Intent();
        intent.setAction( ACTION_SITE_RESPONSE );
        intent.putExtra( EXTRA_REQUESTED_SITEID, siteId );
        intent.setPackage( LAUNCHER_PACKAGE_NAME );
        sendBroadcast( intent ) ;

    }
}

Enabling Custom Site Finder

On the Launcher configuration file, add the following section. When these configuration are set, the Launcher will invoke the custom service at startup to determine the device location. This will also be invoked when the user requests to change the site from the UI.

The packageName should be the applicationId of the application where the custom service can be found. The serviceName is the full path to the service. These two will be used to form a component to invoke the service.

"externalSiteInfoFinder": {
  "packageName": "com.bluefletch.services.app",
  "serviceName": "com.bluefletch.services.CustomSiteFinder"
}

Base Feature Introduced in Launcher 2.6.x. External Site Service Feature introduced in Launcher 3.2.7. Force Reprocess Intent introduced in Launcher 3.16.15. Site List Automatic Updates introduced in Launcher 4.