Ti.GeoVisits allows you to use iOS 8 Visit functionality in your iOS Titanium app. Access to iOS 8 CLVisit functionality.
Ti.GeoVisits raises the "visited" event when the user arrives or departs a new location as determined by iOS.
* You need Titanium 3.5.0.GA or greater. * This module has only been tested on iOS7+ and Android 4+When using this module you need the following added to your tiapp.xml
- You need to create a location UIBackgroundModes key
- You need to have the NSLocationAlwaysUsageDescription key with text expanding what you will be doing in the background
Below is a snippet showing the tiapp.xml updates you will need to make.
<ios>
<plist>
<dict>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
<key>NSLocationAlwaysUsageDescription</key>
<string>Will do something awesome in the background</string>
</dict>
</plist>
</ios>
- You must be running iOS 8 or greater
- You must be using Ti SDK 3.5.0.GA or greater
- Compiled modulle available at dist folder
- Install the Ti.GeoVisits module. If you need help here is a "How To" guide.
- You can now use the module via the commonJS require method, example shown below.
//Add the core module into your project
var visits = require('ti.geovisits');
Now we have the module installed and avoid in our project we can start to use the components, see the feature guide below for details.
The module contains only four methods. The goal is to keep the function of this module narrow.
Indicates of the module is supported
Method returns true or false
Example
var visits = require('ti.geovisits');
var supported = visits.isSupported();
console.log("device is supported? " + (supported)? "Yes" : "No");
Turns on/off debug functionality
Example
var visits = require('ti.geovisits');
console.log("Turn on Debug");
visits.setDebug(true);
console.log("Turn off Debug");
visits.setDebug(false);
The startMonitoring method creates the background process that will monitor when the user visits or leaves a place. Once monitoring has been started, the started event is fired. During the monitoring process the visited event is fired when the device user arrives or departs a "place".
Example
var visits = require('ti.geovisits');
visits.startMonitoring();
The stopMonitoring method stops the monitoring process. Once monitoring is stopped, the stopped event is fired.
Example
var visits = require('ti.geovisits');
visits.stopMonitoring();
The started event is fired when visit monitoring is first enabled.
Example
var visits = require('ti.geovisits');
visits.addEventListener('started',function(e){
console.log(JSON.stringify(e));
});
The stopped event is fired when visit monitoring is stopped.
Example
var visits = require('ti.geovisits');
visits.addEventListener('stopped',function(e){
console.log(JSON.stringify(e));
});
The errored event is fired when visit monitoring encounters an error. The event is provides a category and message. These can be used to determine the root cause of the error generated.
Example
var visits = require('ti.geovisits');
visits.addEventListener('errored',function(e){
console.log(JSON.stringify(e));
if(e.category === "compatibility"){
console.log("the device or configuration is not compatible with the module");
}
if(e.category === "permissions"){
console.log("necessary permissions are missing or disabled");
}
if(e.category === "exception"){
console.log("a general exception happened");
}
});
The authorized event is fired geo location permissions have been granted or changed.
Example
var visits = require('ti.geovisits');
visits.addEventListener('authorized',function(e){
console.log(JSON.stringify(e));
if(e.success){
console.log("We now have the permissions needed to run the module");
}else{
console.log("We are missing the permissions needed to do anything meaningful");
}
});
The visited event is fired the device user arrives or departs from a place.
Example
var visits = require('ti.geovisits');
visits.addEventListener('visited',function(e){
console.log(JSON.stringify(e));
console.log("latitude:" + e.coords.latitude);
console.log("longitude:" + e.coords.longitude);
console.log("horizontalAccuracy:" + e.coords.horizontalAccuracy);
if(e.hasOwnProperty("arrivalDate")){
console.log("arrivalDate:" + String.formatDate(new Date(e.arrivalDate),"long"));
}
if(e.hasOwnProperty("departureDate")){
console.log("departureDate:" + String.formatDate(new Date(e.departureDate),"long"));
}
});
You might ask how do you test this module? The best approach is to use the example app.js and head outside and do some errands. You can use the simulator's location settings, but my testing this did not result in a meaningful test environment.
- When does the visited event fire? Unfortunately Apple determines when a user arrives and departs a "place". In my testing I've found that is when you spent about 10-15 minutes without moving in a location. Your mileage might verify so I encourage you to test and to read the Apple documentation on this feature.
- It does X in my app As this wraps the native iOS components you will need to read the Apple documentation and test yourself.
- I need the module to do... I welcome pull requests.
- I don't know how to code but need... Most likely this module is not for you.
This project is licensed under the OSI approved Apache Public License (version 2). For details please see the license associated with each project.
Developed by Ben Bahrenburg available on twitter @bencoding
Please consider following the @bencoding Twitter for updates and more about Titanium.
For module updates, Titanium tutorials and more please check out my blog at bencoding.com.
