Feature: Automated Site Information Service

Overview

The Launcher has the capability to determine the current store/branch of a device based on either its current location, IP range or connected AP Mac addresses.

Starting 3.2.7, the Launcher has an additional Custom Site Finder feature to call a separate service to determine the siteId.

Starting in 3.16.15, the Launcher allows for an intent (com.bluefletch.launcher.action.FORCE_SITE_REPROCESS) to be used to force site location checking.

How it works

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

On device boot the Launcher will use the device location services to determine its current GPS coordinates, and if it falls within 200m (configurable) of a site, will use that as the device site.

If multiple sites are matched, the user will be prompted to choose a site.

If no sites are matched, the user is prompted to manually set the device site.

The search algorithm looks like:

• find nearest gps
• find ip range
• find subnet
• find access point

Instructions

1. Create 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. This 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 given site
longtitude	The gps longtitude of the given site
Add the following columns if using a different method of location other than GPS coordinates. These can also be used as fallback.
iprange	The IP ranges for the network expected at a given 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.

Example data:

2. Export 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

3. Launcher Configurations

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,
        …
    }

Custom Site Finder Feature

This feature was introduced to allow customers build their own service to determine a device' siteId, 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.

Building the Custom Service

The only requirement for the service is that once it has determined the siteId, it will need to perform a broadcast back to the Launcher, using the following sample code:

    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 ) ;

        }
    }

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. 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.

Set Launcher Configuration

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"
  }

Feature Introduced

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