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 real-time location of a device based on either its current location, IP range, or connected AP Mac addresses.

User Guide

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

  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 200 meters (configurable) 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 will 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, then the 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.

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

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 subtab in the Portal.

Anytime a change is made to the active site list on the Portal, applying the change to devices, the URL string should be updated/changed somehow. BlueFletch suggests incrementing the ts value. For example, if the first site list url is "https://ems-services-api.bluefletch.com/playbook/apiv1/sites/current/download?apikey=xxxx67gR20H854dfspe6bb3809144nqKyw6c5N22&ts=000000" the second would be "https://ems-services-api.bluefletch.com/...?apikey=xxxx...22&ts=000001".

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 3.2.7. Force Reprocess Intent introduced in 3.16.15.

PreviousCustom Field DisplayNextCustom Intents

Last updated