Geofencing on the surface, comprises drawing a stationary geometric boundary around an area on a map. This action creates programmatically a set of simple or complex global coordinates which represent a shape. A boundary represents a "fence," which surrounds the area. For Backendless, the boundary and area become meaningful when a Geopoint crosses the boundary or stays within the area.
Geofences work with Geopoints. A Geopoint is the most elementary Geolocation concept in Backendless. It is a point (latitude and longitude coordinate pairs) on the map that is accessible via API and allowed to move (change coordinates), i.e., a user carrying a mobile device. In addition to the coordinates, the Geopoint includes metadata in context for the Geopoint.
The Geofence Designer¶
Geofence Designer is a feature of the Geolocation service available under Geolocation > Geofencing. It is a "design time" tool for drawing Geofences on an interactive global map and associating them with events and actions, which can be triggered based on the location of registered Geopoints. Backendless integrates the designer with Google MapsTM, enabling the developer to design precise Geofence positions, locations, and shapes.
The Design Tool includes line, rectangle, and circle drawing tools (the cursor changes from hand to crosshairs when selected) for creating Geofence boundaries. Boundaries can be geometrically symmetrical or irregular shapes and have no minimum or maximum size constraints. In use cases, a Geofence conceptually "fences in" a city block, a shopping center, a sports stadium, or perhaps a mall; even smaller geographic areas are possible such as the shoe department in a retail store.
The Line Tool¶
To define an irregular Geofence, the line tool draws editable line segments and control points. For example, in the United States, the shape of Nevada is irregular. To create this shape, select the line tool to start drawing lines around it.
Place the cursor on the map where the first control point should be and click. Drag the cursor to the next place and Click again. The first line segment appears. Repeat these steps until you have nearly completed the shape of your boundary. (It's not a Geofence just yet.) Click the cursor on the last control point (which was the first one set). Backendless detects a closed shape and enables a new Geofence.
NOTE: If you accidentally close the Geofence before completing the drawing, the New Geofence dialog box appears. If you click Cancel, the Geofence will be removed. To keep the Geofence, click Save, then re-edit the shape as needed.
Immediately after the shape closes, a popup appears prompting you to name the Geofence. Enter a name in the Geofence Name text box. Since this example uses the state of Nevada, it makes sense to name it Nevada. Click Save to enable the Geofence. (We will refer to this example again.)
The result is a new item row in the List of Geofences. The Geofence area is filled with green, and the item row is highlighted in yellow when a Geofence is selected on the map or on the list. See the image below.
The Rectangle Tool¶
The Rectangle Tool is self-describing. A fence can be drawn quickly around a square or rectangular area. After the Geofence is named and saved, the shape aspect can be adjusted by dragging a line segment or corner control point. Like the line tool, parameters can be entered in a dialog immediately after the shape is drawn. Should you need to edit the shape, an undo tool appears and to restore the previous edit.
The Circle Tool¶
The Circle Tool is also self-describing. A circle can be drawn quickly around an area, repositioned, and resized. Like the line tool, parameters can be entered in a dialog immediately after the shape is drawn.
Deleting a Geofence¶
A Delete button is positioned directly below the interactive map. For each selected checkbox next to the Geofence name, the Delete button removes those Geofences. Once a Geofence is deleted, it cannot be restored.
List of Geofences and Locator Tool¶
A map filled with Geofences can appear cluttered, especially if the design comprises numerous shapes across several remotely located areas. Backendless organizes the boundary data and actions in a table format below the map, the List of Geofences. The table contains a row for each Geofence along with parameter controls.
From left to right, the second column shows the Geofence name, which is hyperlinked to the Update Geofence dialog. The Geofence locator icon is next to the Geofence hyperlink (see image below). The tool repositions the map view to an optimal zoom-level, from which the Geofence boundary can be easily viewed, accessed, and edited.
Geofence and Geopoints Events¶
Geofences and Geopoints are integrated entities of Geolocation. As such, Backendless tracks three specific events:
- When a Geopoint enters a Geofence, crosses the boundary, On Enter action executes.
- When a Geopoint stays inside a shape for a preconfigured amount of time, On Stay actions executes.
- When a Geopoint exits the Geofence, it crosses the boundary and is outside the shape, On Exit action executes.
Geopoint Qualification Criteria: Exclusion/Inclusion¶
Tracking every Geopoint within a Geofence is not desirable in every case. A Geofence plan could specify tracking only Geopoints of a certain nature, for example, visitors or preferred customers.
Qualification Criteria, which identifies the types of Geopoints Backendless traces and tracks for a specific geogence, can be defined in the Update Geofence dialog. The Geofence hyperlink opens the dialog. A criterion, in this case, is a special string entered in the Geopoint Qualification Criteria text box. (The string format is the SQL 92 syntax, regular SQL as relates to a database query WHERE clause.) For example, if tracking only visitors, the SQL would need something like
usertype is a Geopoints metadata property.
visitor is the metadata property value.
Events and Actions¶
Detecting, tracing, and tracking geopoints in relationship to a geofence establish the event clockwork for execution of developer defined actions. An event occurs as a Geopoint transports into and out of or stays in a Geofence. An action is a set of parameters the developer selects to perform a function, such as deliver a message to a mobile device or add a record to a database.
Three event types are organized in columns in the List of Geofences. The events types are:
- On Enter - a Geopoint crosses the Geofence boundary into the defined area
- On Stay - a Geopoint remains in the Geofence area for at least a specified period
- On Exit - a Geopoint crosses the Geofence boundary out of the defined area
For each of the above events, a developer can select an action and specify parameters to be executed from Backendless. There are four action types:
- Push notification
- Publish-subscribe (pub/sub) message
- Send a custom event
- Call a URL
The scenarios for choosing an action are wildly different; however, they drive the action and parameter choices the developer makes. When an action type is selected for an event, a dialog appears where action parameters can be entered. The fields in the dialog are specific to the action type.
Whenever an action is configured, visual elements indicate whether the parameters are complete. A gear icon and green checkmark indicate proper configuration, where as a red X in place of the checkmark indicates improper configuration. The configuration can be edited by clicking the gear to reopen the currently assigned action dialog.
Push Notification Action¶
All three Geofence events can trigger this action. Push Notification, in basic form, is a message sent to a mobile device associated with a Geopoint or to a group of devices registered with a channel. The Configure Push Notification Actiondialog provides flexible parameter options:
- Content Configuration - configure Push Notification content look and feel for Android, iOS, or Windows Phone.
- Message Headers - allows header name and header value.
- Delivery - to individual Geopoints or those registered to a channel.
Send a Pub/Sub Message Action¶
This action sends a publish/subscribe message. The developer enters the message parameters in the Configure Pub/Sub Message Action dialog. (Learn more about Message Publishing.) The dialog contains the following fields:
- Channel name - the name for a channel. Backendless creates the channel if it doesn't exist.
- Topic name - the name of a topic used for filtered delivery.
- Message headers - optional. Use the key=value format. Comma delimited.
- Message body - written in JSON. The body of the message to be delivered.
| A probation officer (PO) issues an ankle bracelet to a probationer. He needs to set area from which the probationer cannot leave, such as restricted to travel only within a state. The PO would set up a Geofence outlining Colorado's state-line borders. For that Geofence, he would set the action event On Exit to send a notification to the application on his device that would provide metadata about the probationer such as location, the probationer's photo, phone number, address, etc.
| | --- | --- |
Call URL Action¶
This action executes an HTTP command on the specified URL. Supported commands are GET, POST, or PUT. The developer configures the call in the Configure Call URL Action dialog. The dialog contains the following fields:
- Command - choice of GET, POST, or PUT
- URL - a fully formed internet protocol URL.
- Request headers - any of the HTTP header types in the form of key=value.
- Body - text message for calling the URL.
Send Custom Event¶
Provides a means for enabling Geofencing processing logic to execute your custom server-side code deployed to Backendless. Send Custom Event issues an event that you define in the Send Custom Event dialog box. See Custom Events under Business Logic. Backendless acts as a functional intermediary for your custom event handler which contains business logic specific to the application such as sending out an email or saving a record to a database.
Is Active - Geofence Monitoring¶
Is Active is the final column in the List of Geofences. It indicates whether server-side Geofence monitoring can be activated. When monitoring is ON, Backendless tracks any movements of the Geopoints in relation to the corresponding Geofence. The list below shows item content:
- Missing Actions - look for red X next to the edit action gear. An action is improperly configured.
- ON/OFF Toggle - click to switch either on or off. ON activates the server-side monitoring for the selected Geofence.
When an action is properly configured, i.e. complete, the Is Active toggle for the selected Geofence appears. When set to ON, a popup provides cautionary information and a checkbox option, which applies actions to Geopoints located within the Geofence at the time when the monitoring is turned on (i.e. the toggle is being set to ON). See the image below.
Once server-side monitoring is activated by setting the Is Active toggle to ON, a play button appears next to the gear icon. This button executes the action on-demand for any Geopoints within the Geofence. (This function can be useful when debugging.)
View Geopoints in a Geofence¶
For any Geofence that is currently active (i.e. is under server-side monitoring), a checkbox option displays Geopoints located within the Geofence. Geopoints located within the Geofence are represented by a marker for Google Maps inside the Geofence.
The frequency of refresh on the screen is controlled by the refresh interval. The data is being refreshed every 10 seconds. You can force a refresh by clicking the refresh button. See the image below.