Skip to main content

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.
Android Support
>=9.6.0.821
iOS Support
>=10.9
Type
Class
Package
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

An enum of how routing through a geofence will be handled by CoPilot. setRouteThroughEvent() must also be set to true if GeofenceActiveState is set to WARN or AVOID.
Android Support
>=9.6.0.821
Type
Enum
Package
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

An enum of notifications sent when the position enters or exits a geofence.
Android Support
>=9.6.0.821
Type
Enum
Package
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

An enum of the possible shapes of a geofence. Geofences are drawn in 2D on the map.
Android Support
>=9.6.0.821
Type
Enum
Package
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

A geofence object. The geofence constructor is not public. To initiate a geofence, call static methods getPolygon() or getCircle().
Android Support
>=9.6.0.821
Type
Object
Package
com.alk.cpik.geofence

Static Methods

Method Name Return Type Description
getPolygon(List pointList)
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

A grouped set of Geofence objects.
Android Support
>=9.6.0.821
Type
Object
Package
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

Adds a geofence set to CoPilot.
Android Support
>=9.6.0.821
Type
Method
Package
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

Returns an existing geofence set.
Android Support
>=9.6.0.821
Type
Method
Package
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

Gets an individual, existing geofence from an existing geofence set.
Android Support
>=9.6.0.821
Type
Method
Package
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

Gets a list of all of the geofence sets currently in CoPilot.
Android Support
>=9.6.0.821
Type
Method
Package
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

Deletes all geofences; a geofence set and its fences; or an individual geofence from CoPilot.
Android Support
>=9.6.0.821
Type
Method
Package
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);
}
Last updated April 25, 2024.
Contents