GeofenceMgr (CPIK Libraries)
Contents
A class used for managing geofences. A geofence defines a geographic area that will either generate an alert when a route enters it, or will be avoided by the route.
A geofence has many different applications, including:
- Drawing zones around a warehouse to identify delivery or billing zones.
- Alerting dispatchers when a vehicle enters an area that it wasn’t authorized to enter – for example, leaving the country.
- Avoiding or warning about steep grades, mountain passes susceptible to snow closures, tunnels requiring escorts, etc.
- Avoiding or warning if an asset has crossed into a high crime or high accident area.
Class
com.alk.cpik.geofence
Methods
Method Name | Return Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
addGeofencesXML(String) |
void | Adds geofences from an XML file. | ||||||||||||
addGeofenceSet(GeofenceSet) |
void | Adds a geofence set. If a set with the same name exists, it will be overwritten. | ||||||||||||
addGeofences(String, List
| void Adds a list of geofences to an existing geofence set. If the set does not exist, or if the set name is blank, the fences will be added to the default set.
| getGeofenceSet(String)
|
| GeofenceSet Gets a geofence set by its name.
| getGeofence(String, String)
|
| Geofence Gets an individual geofence using its name and set name.
| getGeofences()
|
| List<GeofenceSet> Gets a list of all of CoPilot’s current geofences.
| deleteGeofences(String, List |
| void Deletes geofences, geofence sets, or both. If both parameters are null, all geofences and geofence sets will be deleted.
| |
Hooks and Callbacks
Hooks and Callbacks related to Geofencing can be found below.
GeofenceListener
- onGeofenceEntry
- onGeofenceExit
- onGeofenceRouteThrough
GeofenceActiveState
true
if GeofenceActiveState is set to WARN
or AVOID
.
Enum
com.alk.cpik.geofence
Values
Value | Description |
---|---|
NONE | Do not take the geofence into account while routing |
WARN | Warn before routing through the geofence |
AVOID | Avoid routing through the geofence |
GeofenceNotification
Enum
com.alk.cpik.geofence
Values
Value | Description |
---|---|
NONE | No callbacks will be sent. |
ENTER | Send a callback when entering the geofence, but not when exiting. |
EXIT | Send a callback when exiting the geofence, but not when entering. |
ENTER_AND_EXIT | Send callbacks both when entering and exiting the geofence. |
GeofenceShape
Enum
com.alk.cpik.geofence
Values
Value | Description | Notes |
---|---|---|
CIRCLE | Circle | Defined by exactly two points. These points define the bounding square in which the circle lies. For best results, the two points (coordinates) used to create a circular geofence should be placed at each end of the horizontal diameter of the circle. (The coordinates should have the same latitude, but a different longitude.) |
POLYGON | Multi-sided polygon | Must have three or more points. Each point is connected in order, then closed to form the polygon. |
Geofence
Object
com.alk.cpik.geofence
Static Methods
Method Name | Return Type | Description | |||
---|---|---|---|---|---|
getPolygon(List
| Geofence Returns a polygon geofence by using list of coordinates.
| getCircle(Coordinate pointA, Coordinate pointB)
|
| Geofence Returns a circle geofence by using two coordinate points.
| |
Methods
Method Name | Return Type | Description |
---|---|---|
getShape() |
GeofenceShape | Returns shape of the geofence (i.e. circle or polygon). |
getLabel() |
String | Returns label of the geofence. |
getName() |
String | Returns name of the geofence. |
getPoints() |
ArrayList<Coordinate> | Returns list of coordinate points of the geofence. |
setName(String) |
Void | Sets name of the geofence. |
setLabel(String) |
Void | Sets label of the geofence. |
GeofenceSet
Object
com.alk.cpik.geofence
Constructor
Constructor | |
---|---|
GeofenceSet(String setName) |
Methods
Method Name | Return Type | Description |
---|---|---|
getName() |
String | Returns the name of the geofence. |
isPersistent() |
Boolean | Returns true if the geofence is persistent (saved and loaded after CoPilot is closed). |
getNotification() |
GeofenceNotification | Gets geofence notification. |
hasUINotification() |
Boolean | Returns whether or not the geofence has a UI notification. |
hasRouteThroughEvent() |
Boolean | Returns whether or not the geofence has route-through events. |
getActiveState() |
GeofenceActiveState | Returns the active state of the geofence. |
hasBeep() |
Boolean | Returns whether or not the geofence has a beep sound. |
getFillColor() |
Int | Returns the geofence fill color value. |
getBorderColor() |
Int | Returns the geofence border color value. |
getDrawUnderRoads() |
Boolean | Returns true if fences are drawn under the roads. |
getBorderWidth() |
Int | Returns the number of geofences added in geofence set. |
getGeofenceList() |
ArrayList<Geofence> | Returns the list of geofences in the geofence set. |
setName(String) |
Void | Sets the name for the geofence. |
setPersistent(boolean) |
Void | Sets whether the geofence set is persistent (saved and loaded after CoPilot is closed). |
setNotification(GeofenceNotification) |
Void | Sets the notification for the geofence set. |
setUINotification(Boolean) |
Void | Sets the UI notification for the geofence set. |
setRouteThroughEvent(Boolean) |
Void | Sets the route-through event for the geofence set. Must be set to true in order for CoPilot to warn the driver before routing through a geofence or to avoid routing through a geofence.
|
setActiveState(GeofenceActiveState) |
Void | Sets the activation state for the geofence set. |
setBeep(Boolean) |
Void | Sets the beep for the geofence set. |
setFillColor(int) |
Void | Sets the fill color for the geofence set. |
setBorderColor(int) |
Void | Sets the border color for the geofence set. |
setDrawUnderRoads(Boolean) |
Void | Sets whether or not to draw fences under the roads. |
setBorderWidth(int) |
Void | Sets the number Geofence in Geofence set. |
addGeofence(Geofence) |
Void | Adds a geofence to the geofence set. |
GeofenceMgr.addGeofencesXML
Overview | |
---|---|
Description | Imports geofences from an XML document. |
Supported on Android Since Version | 9.6.0.821 |
Type | Object |
Package | com.alk.cpik.geofence |
Syntax
void addGeofencesXML(String xmlDocument)
Parameters
xmlDocument – The contents of the xml file to import
Sample Code
//Put the full file path of geofenceXmlFile
String geofenceXmlFile = "Geofence XML file with path";
GeofenceMgr.addGeofencesXML(geofenceXmlFile);
XML Format
Single Polygon Set:
<ArrayOfMapObjects Name="SampleSet" Persistent="1" NotifySDKOnEnterExit="both" NotifyUIWhileInside="1" NotifySDKOnRouteThrough="1" ActiveState="off" BeepOnEnterExit="0" InnerColor="0xb0345678" OuterColor="0x00ff0000" DrawBelowRoads="0" >
<MapObject Type="Polygon" Label="Philly Area" Name="PolygonA">
<Point lat="40.000000" lon="-75.100000">
<Point lat="40.000000" lon="-75.300000">
<Point lat="39.870000" lon="-75.300000">
<Point lat="39.870000" lon="-75.100000">
</MapObject>
<MapObject Type="Polygon" Label="Cape May Area" Name="PolygonB">
<Point lat="38.930000" lon="-74.980000">
<Point lat="38.980000" lon="-74.970000">
<Point lat="38.950000" lon="-74.870000">
<Point lat="38.940000" lon="-74.900000">
<Point lat="38.920000" lon="-74.926000">
</MapObject>
</ArrayOfMapObjects>
Multiple Polygon Sets:
<MapObjectSets>
<ArrayOfMapObjects Name="SampleSet1" Persistent="1" NotifySDKOnEnterExit="both" NotifyUIWhileInside="1" NotifySDKOnRouteThrough="1" ActiveState="off" BeepOnEnterExit="0" InnerColor="0xb0345678" OuterColor="0x00ff0000" DrawBelowRoads="0">
<MapObject Type="Polygon" Label="Philly Area" Name="PolygonA">
<Point lat="40.000000" lon="-75.100000">
<Point lat="40.000000" lon="-75.300000">
<Point lat="39.870000" lon="-75.300000">
<Point lat="39.870000" lon="-75.100000">
</MapObject>
<MapObject Type="Polygon" Label="Cape May Area" Name="PolygonB">
<Point lat="38.930000" lon="-74.980000">
<Point lat="38.980000" lon="-74.970000">
<Point lat="38.950000" lon="-74.870000">
<Point lat="38.940000" lon="-74.900000">
<Point lat="38.920000" lon="-74.926000">
</MapObject>
</ArrayOfMapObjects>
<ArrayOfMapObjects Name="SampleSet2" Persistent="1" NotifySDKOnEnterExit="none" NotifyUIWhileInside="1" NotifySDKOnRouteThrough="1" ActiveState="avoid" BeepOnEnterExit="1" InnerColor="0xb0345678" OuterColor="0x00ff0000" DrawBelowRoads="0">
<MapObject Type="Polygon" Label="Jersey City Area" Name="PolygonC">
<Point lat="40.711400" lon="-74.064800">
<Point lat="40.711400" lon="-74.064800">
<Point lat="40.801400" lon="-74.864800">
<Point lat="40.951400" lon="-74.964800">
</MapObject>
<MapObject Type="Polygon" Label="Hoboken Area" Name="PolygonD">
<Point lat="43.745400" lon="-74.027900">
<Point lat="43.745400" lon="-74.027900">
<Point lat="43.775400" lon="-74.727900">
<Point lat="43.785400" lon="-74.827900">
<Point lat="43.805400" lon="-74.927900">
</MapObject>
</ArrayOfMapObjects>
</MapObjectSets>
Explanation of ArrayOfMapObjects properties:
Property | Description | Required/Optional |
---|---|---|
Name | The name of the polygon set. | Optional |
Persistent | Whether or not this set should be saved and loaded after CoPilot is closed. | Optional, default is false if the set is not named, true if the set is named. |
NotifyUIWhileInside | Whether or not to display a fence icon when within the bounds of the fence. | Optional, default is false |
BeepOnEnterExit | Whether or not to sound an audible beep when entering/exiting the bounds of the fence. | Optional, default is false |
InnerColor | The inner shading of the fence, in the format 0xRRGGBBAA. | Optional, default is 0x00afafaf |
OuterColor | The border color of the fence, in the format 0xRRGGBBAA. | Optional, default is 0x000000ff |
DrawBelowRoads | Whether to draw the fence below roads or on top of them. | Optional, default is true |
Explanation of MapObject properties:
Property | Description | Required/Optional |
---|---|---|
Type | Whether the shape is a “Polygon” or a “Line.” | Required |
Label | A label to draw on the map next to the shape. | Optional |
Name | A unique identification name for the fence. | Optional |
GeofenceMgr.addGeofenceSet
Overview
Method
com.alk.cpik.geofence
Syntax
Java Void addGeofencesSet(GeofenceSet geofenceSet)
Parameters
GeofenceSet geofenceSet – Geofence set to add
Sample Code
//To create a geofence set we need at least two coordinates
List<Coordinate> coordList = new ArrayList<Coordinate>();
double latitude = 40.364992;
double longitude = -74.632334;
Coordinate coordA = new Coordinate(latitude, longitude);
latitude = 40.338631;
longitude = -74.639373;
Coordinate coordB = new Coordinate(latitude, longitude);
latitude = 40.352369;
longitude = -74.689154;
Coordinate coordC = new Coordinate(latitude, longitude);
latitude = 40.368558;
longitude = -74.670615;
Coordinate coordD = new Coordinate(latitude, longitude);
//adding all coordinates in the list.
coordList.add(coordA);
coordList.add(coordB);
coordList.add(coordC);
coordList.add(coordD);
try {
//Create Geofence set it need the name of geofence set.
String geofenceSetName = "Geofence Name";
GeofenceSet setToAdd = new GeofenceSet(geofenceSetName);
//This is taking getPolygon() method if there are more than 2 coordinates
// else it should be getCircle() method for 2 coordinates.
if (coordList.size() == 2)
setToAdd.addGeofence(Geofence.getCircle(coordList.get(0), coordList.get(1)));
//or
// setToAdd.addGeofence(Geofence.getCircle(coordA, coordB));
else if (coordList.size() > 2)
setToAdd.addGeofence(Geofence.getPolygon(coordList));
GeofenceMgr.addGeofenceSet(setToAdd);
} catch (GeofenceException e) {
e.printStackTrace();
}
GeofenceMgr.addGeofences
Overview | |
---|---|
Description | Adds a list of geofences to an existing geofence set. |
Supported on Android Since Version | 9.6.0.821 |
Type | Method |
Package | com.alk.cpik.geofence |
Syntax
Void addGeofences(String setName, List fenceList);
Parameters
String setName – The name of the existing geofence set to which to add the fences. List fenceList – The list of fences to add to the set.
Sample Code
try {
List<Geofence> fencesToAdd = new ArrayList<Geofence>();
List<Coordinate> coordListA = new ArrayList<Coordinate>();
double latitude = 40.364992;
double longitude = -74.632334;
Coordinate coordA = new Coordinate(latitude, longitude);
latitude = 40.338631;
longitude = -74.639373;
Coordinate coordB = new Coordinate(latitude, longitude);
latitude = 40.352369;
longitude = -74.689154;
Coordinate coordC = new Coordinate(latitude, longitude);
latitude = 40.368558;
longitude = -74.670615;
Coordinate coordD = new Coordinate(latitude, longitude);
//adding all coordinates in the list.
coordListA.add(coordA);
coordListA.add(coordB);
coordListA.add(coordC);
coordListA.add(coordD);
//adding coordinateList in fenceList. There is more the three coordinates it
// will create a polygon
fencesToAdd.add(Geofence.getPolygon(coordListA));
latitude = 40.362349;
longitude = -74.632111;
coordA = new Coordinate(latitude, longitude);
latitude = 40.338153;
longitude = -74.639125;
coordB = new Coordinate(latitude, longitude);
fencesToAdd.add(Geofence.*getCircle*(coordA, coordB));
//get all existing geofence sets in copilot
List<GeofenceSet> geofenceSets = GeofenceMgr.getGeofences();
if (geofenceSets.size() > 0) {
//choosing first geofence set name in which we are going to add the fence
String geofenceSetName = geofenceSets.get(0).getName();
GeofenceMgr.addGeofences(geofenceSetName, fencesToAdd);
} else {
System.out.println("There is not geofence set available");
}
} catch (GeofenceException e) {
e.printStackTrace();
}
GeofenceMgr.getGeofenceSet
Overview
Method
com.alk.cpik.geofence
Syntax
GeofenceSet getGeofenceSet(String setName)
Parameters
String setName – The name of the geofence set to get
Return Value
GeofenceSet – A Geofence set representing the set with the given name.
Sample Code
// getting the list of Geofence sets
List<GeofenceSet> geofenceSetsList = GeofenceMgr.getGeofences();
if (geofenceSetsList.size() > 0) {
//choosing the first geofence set name from list
String geofenceSetName = geofenceSetsList.get(0).getName();
//calling getGeofenceSet(String)
GeofenceSet geoSet = GeofenceMgr.getGeofenceSet(geofenceSetName);
if (geoSet != null) {
System.out.println("Sets Name : " + geoSet.getName());
System.out.println("Sets ActiveState : " + (geoSet.isPersistent() ? " is Persistent" : " is Not Persistent"));
System.out.println("Sets ActiveState : " + geoSet.getActiveState());
System.out.println("Sets BorderWidth : " + geoSet.getBorderWidth());
System.out.println("Sets BorderColor : " + geoSet.getBorderColor());
System.out.println("Sets Notification : " + geoSet.getNotification());
//for all values
System.out.println("Sets info : " + geoSet.toString());
}
} else {
System.out.println("There is no geofence set available");
}
GeofenceMgr.getGeofence
Overview
Method
com.alk.cpik.geofence
Syntax
Geofence getGeofence(String setName, String fenceName)
Parameters
String setName – The name of the existing geofence set.
String fenceName – The name of the existing geofence.
Return Value
Geofence representing the desired geofence
Sample Code
List<GeofenceSet> geofenceSetsList = GeofenceMgr.getGeofences();
if (geofenceSetsList.size() > 0) {
//choosing the first geofence set Name
String geofenceSetName = geofenceSetsList.get(0).getName();
GeofenceSet geoSet = GeofenceMgr.*getGeofenceSet*(geofenceSetName);
List<Geofence> fencesList = geoSet.getGeofenceList();
if (fencesList.size() > 0) {
//choosing first fence from fenceList
String GeofenceFenceName = fencesList.get(0).getName();
Geofence fence = GeofenceMgr.getGeofence(geofenceSetName, GeofenceFenceName);
if (fence != null) {
System.out.println("geofence Name : " + fence.getName());
System.out.println("geofence Shape : " + fence.getShape());
System.out.println("geofence Label : " + fence.getLabel());
System.out.println("geofence coordinatesList : " + fence.getPoints().toString());
//for all values
System.out.println("geofence info : " + fence.toString());
}
}
else {
System.out.println("There is no geofence for set " + geofenceSetName);
}
GeofenceMgr.getGeofences
Overview
Method
com.alk.cpik.geofence
Syntax
List getGeofences()
Return Value
List - All of the sets of fences currently in CoPilot.
Sample Code
// Print every geofence and every geofence set in CoPilot
List<GeofenceSet> setsList = GeofenceMgr.getGeofences();
for (GeofenceSet set : setsList) {
System.out.println("Geofence Set: " + set.getName());
for (Geofence fence : set.getGeofenceList()) {
System.out.println("geofence Name : " + fence.getName());
System.out.println("geofence Shape : " + fence.getShape());
System.out.println("geofence Label : " + fence.getLabel());
System.out.println("geofence coordinatesList : " + fence.getPoints().toString());
System.out.println("\\tGeofence: " + fence.getName());
}
}
GeofenceMgr.deleteGeofences
Overview
Method
com.alk.cpik.geofence
Syntax
Void deleteGeofences(String setName, List fenceList);
Parameters
setName – The name of the geofence set to delete. If this is an empty string and fenceList is empty or null, all geofences will be deleted.
fenceList – The list of names of fences to delete. If this list is empty or null, and setName is valid, everything in that set will be deleted. If this list has multiple elements, each fence in the list in setName will be deleted.
Sample Code
// Delete existing fence from the existing set
List<GeofenceSet> geofenceSetsList = GeofenceMgr.getGeofences();
if (geofenceSetsList.size() == 0) {
System.out.println("There no Geofence set available");
return;
}
// taking fence list form first Geofence Set
List<Geofence> fenceList = geofenceSetsList.get(0).getGeofenceList();
if (fenceList.size() == 0) {
System.out.println("There no fence is available for Geofence set " + geofenceSetsList.get(0).getName());
return;
}
List<String> deleteList = new ArrayList<String>();
//taking first fence from the list
deleteList.add(fenceList.get(0).getName());
//Deleting first fence from first Geofence set.
GeofenceMgr.deleteGeofences(geofenceSetsList.get(0).getName(), deleteList);
// Delete all fences from First Geofence set
List<String> deleteList2 = new ArrayList<String>();
GeofenceMgr.deleteGeofences(geofenceSetsList.get(0).getName(), deleteList2);
// Delete all geofence sets and all Geofences from CoPilot
List<String> deleteList3 = new ArrayList<String>();
GeofenceMgr.deleteGeofences("", deleteList3);
}