Engine is comprised of the following:
Any instance of Engine is typically making outbound requests either for new tiles (when you enter a previously unvisited area) or configuration updates (once a day, provided the user opens the app). Also, Engine keeps a small buffer of conversion data that is forwarded when full. Circumstance detection and current location queries act against the local places cache, and therefore do not generate outbound requests.
Engine can return a list of candidates for the user’s current location. You can use this list to drive a check-in interface, or to passively tag events or media with a place.
For each candidate, you will receive:
For both Android and iOS, the place candidate call is non-blocking. You must register a callback method to handle the response.
A Circumstance can currently be comprised of:
|at||Any location(s) that Engine is confident that you are currently at. For example at Starbucks or at a concert venue.|
|near||Any locations within approximately 200 meters of of the device’s current location that must be present. For example, near a bar.|
|date/time parting||Days or time brackets the Circumstance should be limited to. For example M-F, 6am-9am|
|hours of operation||Based on hours of operation data in Factual’s Global Places Data, Circumstances can be filtered against currently open/closed businesses. For example, near a store that is open right now.|
Engine will monitor in the background for the device entering any of the specified Circumstances. Upon a positive hit, Engine will invoke a callback function called an Action Handler that you define to perform whatever action you desire.
Because Circumstances can be defined in The Garage, a convention is required for relating each Circumstance to an action handler. This is done through an action id. For example:
|Circumstance||Action Id||Example Action Handler|
|User is at a competing coffee shop near one of your own.||
||Your handler makes a request to the cloud to generate a discount coupon, and uses a push notification to offer it to the user.|
|User is working in an office near your coffee shop on the weekend||
||Same as above|
|User is currently at your coffee shop||
||Your handler checks to see if the user has an existing coupon, and (if so) pops up a dialog asking if they want to make use of it.|
As in the example above, multiple Circumstances can be tied to the same action.