We hope you are enjoying the Proximity Events application. Listed below are answers to common questions. If your question is not answered below, please contact us at support@proximityevents.com


Triggers

A Geofence is a virtual perimeter for a geographic location. Once configured, the application is able to monitor the phones location and will trigger an event when the phone enters or exits the virtual perimeter. This is the same technology Apple uses for its Reminders application and other system services and geofences can be monitored with minimal impact to battery life.

A geofence is defined by specifying a location and a radius. The location can be specified by selecting a location on a map or by manually entering the latitude and longitude address for a location. The radius specified as a distance in meters or feet to define a virtual perimeter as a circle around the specified location. A Geofence is typically used to monitor larger locations with a radius range of 350 feet to 1,000 miles.

An iBeacon is similar to a geofence, but it uses different technologies to specify a location and it enables monitoring of smaller micro-locations. It requires an external hardware device to be placed is a location and configured for the particular use case. The device transmits small amount of information using a standard proximity profile using Bluetooth Low Energy technology. Just like a phone can monitor for the presence of a bluetooth handsfree system in a car, the phone can constantly monitor for the presence of pre-configured devices with minimal impact to battery life. and will trigger Enter and Exit events when the virtual perimeter is crossed.

An iBeacon Trigger is defined by specifying a unique Identifier called a UUID that specifies the Vendor that made the Beacon or a unique identified that a user may configure for the device. Two additional fields, Major and Minor identifiers, can be used to differentiate between devices. A common use case would be for a Brand to use a single UUID across all stores and use the major number to identify a specific location and a minor number to specify a room or department. Most iBeacon hardware can be configured to change the power setting for the iBeacon device. This allows enables the user to define how large the virtual perimeter is from the location by adjusting the power level of the device. An iBeacon typical is used to monitor smaller locations in the range of 10 feet to 150 feet.

We do not sell our own iBeacons and you are not tied to a specific vendor to use our application. The application leverages iOS Beacon APIs so it should be compatible with any certified iBeacon device. It is important that you use one that makes the unique identifiers (UUID, Major, Minor) available to you or allows you to configure them with your own custom identifiers. We have done extensive testing with the Estimote iBeacons and would recommend them if you are just getting started. A full review of other beacon vendors can be found here.

The Location Visit Trigger monitors general location events instead of just monitoring a pre-determined location. It takes advantage of the location and motion sensors on the devices and uses an algorithm to detect when you arrive at a new geographic location by detecting when you transition from driving to walking or detecting if you have stopped at a new location for a few minutes. For each location change, an Enter and Exit event can be used as a trigger. By tracking these events in a database, most users can keep a record of the 5-10 places they visit each day and record the enter and exit times. It can also be used to trigger other Actions every time the user enters or exits a new location for an extended visit.

The Location Update Trigger monitors general location events instead of just monitoring a pre-determined location to determine when the device has moved a significant distance from its previous location. It generally detects when the device changes Cell Towers or it uses WiFi to determine your location in a way that has a minimal impact on battery life. While driving, it will trigger a Location Update event every 5-10 minutes. By tracking these events in a database, most users can record a a minimal number of records, but also provide a good summary of the users location throughout the day. It can also be used to trigger other Actions periodically to indicate that the user is traveling.


Actions

Notification Actions can be used to show a notification or alert on the screen and play a sound any time a proximity event occurs. The alert shows the type of alert, the location an the time stamp of the event. The type of notification can be configured in Notification Settings in the Apple Settings app. You can configure the type of alert to show, including a Banner or Alert Style and set if you want it to show on the lock screen. You can also enable or disable sounds for each alert.

Notifications can be turned on if you want to use them as a reminder every time you enter or exit a location. Notifications are also are a great way to test the application to asses the reliability of each type of trigger before you decide to upgrade to premium features. Keep in mind that notifications turn on the screen breifly and can impact the battery life of the phone so once you are comfortable with how they work it is best to only use notifications when needed for a specific purpose.

Database Save Actions can be used to record all of your Proximity Events to a database on the phone. The event history can viewed in the app or exported in a CSV format for offline analysis. For each event, the following fields are saved: Trigger Name, Trigger Type, Trigger ID, Event Type, Event Date and Time, Event Address, Event Latitude and Longitude, Event Location Accuracy, Event ID. In addition, some triggers include Event Arrival and Exit times if applicable.

Although there are many great applications that capture similar information and provide greater user interface to visualize your location data, most of these applications are walled gardens and they do not allow you to get access to your raw location data. By using a combination of both general location triggers and triggers to monitor specific locations of interest, a user can capture a broad data set that records where you have been. This can be used for timekeeping purposes for hourly workers or consultants or the data can be loaded into other application for custom analysis.

A WebHook is an HTTP callback or an HTTP POST that occurs when something happens. The Webhook Action will POST a message to a URL for each Proximity Event. The message includes all of the relevant event data about the event in a JSON format.

Web hooks can be used to export your location data to a third party web application on a real time basis as the events occur. This can be used to trigger home automation or other custom actions online by using web hooks to interact with web based APIs in a web based application

Webhook data is sent using a simple name / value pair format with data from each proximity event. For POST requests, the data is sent in a JSON format. For GET requests, the data is sent in the query string. One way to see the format of data is to point the URL in the settings page to a service like http://requestb.in/ and use the send "test webhook" button to send test requests and then view the output on the requestb.in inspector page. An example of a JSON webhook can be seen below:

{
"trigger_id":"AC1A6E58-F7A1-4EB7-82C1-4F76F9AF9546",
"trigger_type":"Visit",
"trigger_name":"New Location Visits",
"event_id":"F81A6E58-F7A1-4EB7-82C1-4F76F9AF9969",
"event_type":"Geofence:Exit",
"event_date":"2015-01-08T13:52:19-05:00"
"event_latitude":"42.864631",
"event_longitude":"-73.048476",
"event_accuracy_m":"65.000000",
"event_address":"2 Rocky Rd, Boston, MA",
"event_enter_date":"2015-01-08T1:32:13-05:00",
"event_exit_date":"2015-01-08T13:52:19-05:00"
}
				

Definitions for each field are described below:

  • trigger_id = Unique UUID representing the trigger
  • trigger_type = Description of the trigger type. (“Geofence”, “Beacon”, “Visit”, or “Location”)
  • trigger_name = The name used to describe the Trigger. Based on user inputed name for Geofences and Beacons and hard coded to "New Location Visits” for Visits and "New Location Updates” for Location Triggers
  • event_id = Unique UUID representing the event
  • event_type = Combined description of Trigger Type and Event Type separated by a “:" (“Geofence:Enter”, "Geofence:Exit”, “Beacon:Enter”, “Beacon:Exit”, “Visit:Enter”, “Visit:Exit”, Location:Update”)
  • event_date = ISO8601 String representation of the date and time the event triggered
  • event_latitude = String with the Latitude value for where the event triggered
  • event_longitude = String with the Longitude value for where the event triggered
  • event_accuracy_m = String with the reported value of the accuracy of the event location in meters
  • event_address = String represented a geocoded address associated with the event location, if available
  • event_enter_date = ISO8601 String representation of the arrival date and time (Only used for Visit Triggers)
  • event_exit_date = ISO8601 String representation of the departure date and time (Only used for Visit Triggers)



Other

You are in control your location data and we don't have access to it. Location data is stored securely on the phone and it only leaves the device when you explicitly export the data or configure an action like a webhook to send the data to a web server of your choice when proximity events are triggered. For more information, view our privacy policy at http://www.proximityevents.com/privacy/

No, this application was designed with battery life in mind. By leveraging system level iOS location services that are often used by the system or other applications the incremental impact to battery life is often neglegable. Battery impact is dependent on the number and type of triggers and actions configured, so the user should consider the trade-offs for each trigger and action.

System Services - This application does not keep the GPS service on at all times like a navigation application would and it uses system level location events that happen less frequently to trigger an action in the background. To be effective, the application needs location services to be enabled and WiFi and Bluetooth should be turned on at all times so the device can identify your location without the need for GPS. Most users have these services on anyway so the incremental impact to battery life is minimal.

Triggers - A specific trigger’s impact on battery life depend on how often it generates events, but generally the impact is more dependent on the actions and it should be possible to run multiple triggers simultaneously with minimal impact to battery life Geofences and Beacons triggers generate events when you enter or leave a location and the number of events is related to how often you change locations and the number of locations monitored. Location Visits Trigger's generate events any time the system determine you have moved to a new geographic location and stayed in the same place for 5 minutes of longer. Location Change Triggers generate events when you move a significant distance from your previous location. This can often create events every few minutes when you are driving, but few events when you are at rest. For a user who commutes to and from work with a few other small trips these general location triggers can often generate less than 50 events per day which has a minimal impact on battery life, but enables some interesting scenarios for actions. If other applications are enabled for “Always” location tracking, there is often no incremental impact for running these triggers.

Actions - The larger impact to battery life comes from the types of Actions configured for each Trigger. Notifications impact the battery life by turning on the screen quickly. Generally, using notifications for Geofences and Beacons will have minimal impact, but can have more of an impact for the General Location Triggers since the fire more often. The Database Save Action generally has the least impact on battery life. For every event, the system quickly saves the event to the database in the background along with other system level processing. The Webhook Action requires a little more processing in the background than the database actions because it needs to make a network connection for each event. For less frequent triggers the impact is minimal, but Triggers with more frequent events will have a larger impact.

The best way to test the impact is to try the application for your needs and to only turn on the Triggers or Action you need. Many users report that the application only uses < 2% of their overall battery life for most scenarios. Power users who have might have slightly higher impact due to the number of triggers and Actions configured generally feel the trade off is worth it for the actions they are able to automate.

The application is free so that users can test the basic features to evaluate the quality of the application and determine if it meets their needs before paying for premium services. Currently, an in-app purchase is required to unlock some of the more advanced functionality. A user can either unlock specific features a la carte or the can upgrade to the Premium Package to unlock all current and future features with a single purchase.

  • Premium Package - The premium package enables the user to unlock all of the features including all of the “A la carte” features and all future features that may be added in the future.
  • Data Export - The free version of the application allows you to export the last three days of events to test the application, but the upgrade is required to export the complete data set.
  • Webhooks - The free version of the application allows you to text a Webhook Event from the settings screen by configuring the server address and selecting the type of event to simulate. The upgrade is required to be able to configure a web hook action for a trigger to send web hook events in the background.