Download Report

What’s geoAlgorithm?
There are many libraries that can help us recover the location of a given device but what makes
geoAlgorithm special is that it evaluates the behavior of the device in order to determine when is
the best moment to fetch locations and when not to so that the impact on battery life is as little as
possible thanks to our algorithm.
This library is designed so that it’s easily coupled with any app allowing you to configure the
criteria of the updates by declaring intervals for situations where the user is moving inside a good
or bad precision. This customization is optional so if you decide to use the default options you will
still be ready for almost any scenario.
Requirements
The minimum required Android API version is 2.3 (API 9) and it’s currently compatible with every
Android version published so far starting from API 9 to API 22 (Android 5.1).
This library requires Google Play Services, so you’ll need to import such API. In order to do so, if
you’re using Eclipse all you have to do is import the JAR file located in your android sdk folder, and
if you’re using Android Studio you’ll only need to add this code to your project’s build.gradle and
gradle will fetch the latest version of Google Play Services:
dependencies {
compile 'com.google.android.gms:play-services:+'
}
1
In order to integrate this library to your Project you’ll have to add the supplied JAR to your
project’s “libs” folder and if you’re using Android Studio you’ll also have to declare this library in
your build.gradle file this way:
dependencies {
compile fileTree(dir: 'libs', include: ['*.jar'])
…
…
compile 'com.google.android.gms:play-services:7.0.0'
compile files('libs/testapp-release_dex2jar.jar')
…
…
}
Also, it is necessary to declare the following permissions in your AndroidManifest.xml file:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission
android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
2
Configuration
Location updates are set via Broadcast messaging so you’ll need to declare the following
BroadcastReceiver:
<receiver
android:name="com.geoalgorithm.library.receivers.LocationReceiver"
android:enabled="true" />
On the other hand, despite being optional it’s recommended the use of one of the library’s
optional receiver in order to intercept the following IntentFilters:
<receiver
android:name="com.geoalgorithm.library.receivers.ConnectivityReceiver">
<intent-filter>
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
<action android:name="android.net.wifi.WIFI_STATE_CHANGED" />
<action android:name="android.location.PROVIDERS_CHANGED"/>
</intent-filter>
</receiver>
This will allow the library to know when there are connectivity changes.
Usage and examples
3
Periodic locations:
Initialization:
This library is very simple to use. First you must initialize the library itself, this can be achieved in
two ways. First would be calling the following method:
AlgorithmControlTower.init(<CONTEXT>, <YOUR_API_KEY>);
This way the library would initialize with default values which stablish a refresh frequency for
every 5 minutes under good accuracy environments, and 60 minutes under bad accuracy
environments.
The second way to initialize the library would be by calling the following method:
AlgorithmControlTower.initWithOptions(getApplicationContext(),
<YOUR_API_KEY>, new AlgorithmOptions(60 * 60 * 1000, 5 * 60 * 1000, 100,
true));
In here we will customize both frequencies but also we’ll stablish a minimum optimal accuracy and
whether we want to stop updates when we’re offline.
According to this example, 60 min for bad accuracy environments, 5 for good, both in milliseconds,
100 mts for minimum accuracy (this is the default value for this parameter), and true to enable
updates only when online (default value is false).
NOTE: In both cases the initialization must be perform with your API key supplied during the
registration process. If during the initialization there’s a problem with your API key, a
RuntimeException will be thrown indicating the nature of the error, but during the recovery of
location you will receive a message and not an exception. In order to print such message you must
enable debug logging.
Receiving location updates:
4
Once the library is initialized we can fetch location updates by declaring receivers, this can be
achieved by creating a class that inherits BroadcastReceiver or by instancing BroadcastReceiver
during runtime. In both cases when the library sends the received location it will carry a Boolean
inside the Intent object indicating if it has an actual location or not in case an error happened. This
will allow us to face scenarios where the device is not receiving locations successfully (such as
receiving null locations).
If we want to implement our own BroadcastReceiver that runs in background, we could do it this
way:
public class MyReceiver extends BroadcastReceiver{
@Override
public void onReceive(Context context, Intent intent) {
if(intent.getExtras().getBoolean(AlgorithmControlTower.HAS_LOCATION_TAG))
{
//Here we fetch the latest location…
Location location = AlgorithmControlTower.getLastLocation(context);
//Insert your code here…
}
}
}
Now we only have to declare the receiver and necessary IntentFilter in your project’s
AndroidManifest.xml :
<receiver android:name="<PATH_TO_YOUR_RECEIVER_CLASS>.MyReceiver">
<intent-filter>
<action android:name="com.geoalgorithm.library.location_received"
/>
</intent-filter>
</receiver>
And that’s it! However, if we want to declare a receiver in an Activity or Fragment we could do so
this way:
@Override
protected void onResume() {
super.onResume();
LocalBroadcastManager.getInstance(this).registerReceiver(mReceiver,
new IntentFilter(AlgorithmControlTower.LIB_INTENT_ACTION));
}
5
private final BroadcastReceiver mReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
if(intent.getAction().equals(AlgorithmControlTower.LIB_INTENT_ACTION)){
if(intent.getExtras().getBoolean(AlgorithmControlTower.HAS_LOCATION_TAG))
{
//Here we fetch the latest location…
Location location = AlgorithmControlTower.getLastLocation(context);
//Insert your code here…
}
}
}
};
We can stop location updates at any time by calling the following method from anywhere inside
your code:
AlgorithmControlTower.stopLocationUpdates();
Single location:
Initializing and fetching locations:
The library allows us to request a single location without the need to enable location updates and
therefore calling neither init nor initWithOptions, instead we’ll use the following method:
AlgorithmControlTower.requestSingleLocation(getApplication(), new
LocationCallback() {
@Override
6
public void onLocationFailed(Location location) {
}
@Override
public void onLocationReceived(Location location) {
}
});
However, you’ll need to instantiate a LocationCalback object which will allow us to work with the
received location without the need of declaring any receivers. Note that this way you won’t need
to call getLastLocation for it’s already being pass as an argument.
Getting the last location:
Finally, it’s also possible to fetch the latest location recovered by this library from anywhere inside
your code. Just like with requestSingleLocation it won’t be necessary to initialize the library nor
declare any receivers but you will need to be certain that the library has a location stored first,
otherwise it will return a blank location (lat:0,lng:0, accuracy:0, etc.). You just have to call this
method:
AlgorithmControlTower.getLastLocation(context);
7