Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
219 lines (157 sloc) 7.12 KB

Ti.GeoVisits

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.

Before you start

* You need Titanium 3.5.0.GA or greater. * This module has only been tested on iOS7+ and Android 4+

tiapp.xml update

When using this module you need the following added to your tiapp.xml

  1. You need to create a location UIBackgroundModes key
  2. 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>

Setup

  • 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.

Methods

The module contains only four methods. The goal is to keep the function of this module narrow.

isSupported

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");

setDebug

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);

startMonitoring

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();

stopMonitoring

The stopMonitoring method stops the monitoring process. Once monitoring is stopped, the stopped event is fired.

Example

var visits = require('ti.geovisits');
visits.stopMonitoring();

Events

Since Ti.GeoVisits is a primarily a background service, events are used to communicate changes. The following events are available off the root of the module.

started

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));
});

stopped

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));
});

errored

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");
	}		
});

authorized

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");
	}	
});

visited

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"));	
	}	
});

Testing

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.

Important Information

  1. 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.
  2. It does X in my app As this wraps the native iOS components you will need to read the Apple documentation and test yourself.
  3. I need the module to do... I welcome pull requests.
  4. I don't know how to code but need... Most likely this module is not for you.

Licensing

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

Learn More

Twitter

Please consider following the @bencoding Twitter for updates and more about Titanium.

Blog

For module updates, Titanium tutorials and more please check out my blog at bencoding.com.