image

Android Quick Start

Add Veery To Your Build.graddle

In your Android studio project, you should first include the Veery library: In your build.graddle (Module:app) you should add the following lines inside the Android section:

android {
	repositories {
                maven { url 'whatever other maven you required' }
 		maven {
 			url 'https://dl.bintray.com/roofstreet/maven/'
 		}
 	}
 	dependencies {
                compile 'com.google.maps.android:android-maps-utils:0.4+'
		compile 'com.google.android.gms:play-services:9.4.0'
 		compile 'com.roofstreet.android:veery:0.0.16@aar'
 	}
 }

The last version number (“veery:0.0.16” in this example) can be checked here

Then you should select the menu item Tools → Android → Sync Project with Graddle Files

Declare your API_KEY

You should have received the following information in the registration confirmation email.

  • CLIENT_ID : The UUID identifying your company in our systems
  • Developer API KEY : The API key your mobile app will use to register a new mobile user
  • API Secret : The password that authenticate your API_KEY

In your AndroidManifest.xml file you shoud add the following :

<meta-data
    android:name="com.roofstreet.veery.API_KEY"
    android:value="12345678-1234-1234-1234-1234567890AB" />
<meta-data 
    android:name="com.roofstreet.veery.CLIENT_ID"
    android:value="00000000-1234-1234-1234-1234567890AB"/>
<meta-data
    android:name="com.roofstreet.veery.ENVIR"
    android:value="sandbox"/>

The ENVIR parameter could be either “prod” or “sandbox”.

Include The Library

In the MainActivity section of your project you should place the following:

 // Outside of the Activity Class
import android.location.Location;
import com.roofstreet.android.veery.*;

// Inside the Activity Class (as a class member variable - not inside a function)
private final Veery veery = new Veery(this);

This adds a Veery object as a member of your activity and implements it when the activity is completed.

You can do this on any Activity or Context based section. Do it everywhere you require the Veery functions.

Add Firebase messaging to your application

Enable Firebase in your project

If you did not included firebase notifications in your application yet, you should do the following:

In Android Studio, Use the menu item Tools > Firebase > Cloud Messaging > Set up Firebase Cloud Messaging (require Android studio 2.3.3 minimum)

Follow the Android studio tutorial until the last step.

At the end of the tutorial, you should have a new class extending FirebaseInstanceIdServicen and another class extending FirebaseMessagingService.

Include Firebase in your MainActivity.java

import com.google.firebase.iid.FirebaseInstanceId;

Let Veery know when the FCM token refreshes

In your own FirebaseInstanceIdService class, add the following:

public class MyFirebaseInstanceIDService extends FirebaseInstanceIdService {
    Veery veery = new Veery(this);
    @Override
    public void onTokenRefresh() {
        //
        // Let Veery know when the FCM token is refreshed
        //
        veery.setFirebaseToken(FirebaseInstanceId.getInstance().getToken());
        //
    }
}

Verify and transmit messages to Veery

You should add the following to the FirebaseMessagingService class.
This code will transmit the notifications to Veery. If the notification is not a Veery specific message, the veery.firebaseMessageHandler return false.

 
import com.roofstreet.android.veery.Veery; // Add this line to the import block

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    // ...
    // ...
    // Add a Veery object to the class
    //
    Veery veery = new Veery(this);
    //
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        //
        // Check if the message if from the Veery backend and handle all events implied
        //
        if (veery.firebaseMessageHandler(remoteMessage))
            return; // It was a Veery notification, job done
        // ...
        // Here you can do whetever yuou require with your application specific notifications
        //
     }
}

Connect To The Service

In the MainActivity section of your project you should place the following:

@Override
protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	//
	// Connect (and eventually start) the Veery service 
        //
	veery.serviceConnect();
	//
	// The API Key secret received with the Veery API KEY. 
	//
	veery.setApiKeySecret("yourapikeysecret");
	//
	// Let Veery know how to push into the app
        //
        veery.setFirebaseToken(FirebaseInstanceId.getInstance().getToken());
}
 
@Override
protected void onDestroy() {
	super.onDestroy();
	try {
		//…
		//…
		veery.serviceDisconnect();
		//…
		//…
	}
	catch (Throwable t) {
		Log.e("MainActivity::onDestroy", "Failed to unbind from the Veery service", t);
	}
}

You can do this on any Activity or Context based section. Do it everywhere you require the Veery functions.

Tell The Service When Your Activity Becomes Active

In the MainActivity section of your project you should place the following:

@Override
protected void onResume() {
	super.onResume();
	//…
	//…
	veery.serviceResume();
	//…
	//…
}

@Override
	protected void onPause() {
	super.onPause();
	//…
	//…
	veery.servicePause();
	//…
	//…
}

This will activate the high precision GPS-based geolocation when your activities are in the forefront of the user screen, and  low-consumption mode when your app is running in the background.

Note that when the user plugs the mobile device into a source of energy, the geolocation automatically switches to high precision.

Activate the required functionality level

You should activate the necessary functionality level for every mobile user (see the full documentation to check which level is required for the functionalities you want to use).

FOREGROUND : geolocalize the user only when the application is in foreground. The connection with the Veery backend remains inactive

BACKGROUND : geolocalize the user also when the application is in background (this includes FOREGROUND). The connection with the Veery backend remains disabled.

BACKEND : geolocalize the user when the app is in background and in foreground, and communicate the positions with the Veery Backend. This is required for SDK fonctions implying notifications and data completion.

GEOPROFILE : The levels above + the users profiling functions (Predictions, Point of interests, …).

You can do that operation whenever you want to activate the user but you should notice that android will request for required the user rights when called.

//
// Android interactively request for the authorization for Background Location 
//
Veery.activate(Veery.BACKGROUND);

// ...

This call can be made when the application starts (just after veery.serviceConnect()) but also after you have explained to the user why you require the Background Location right.

BACKEND and GEOPROFILE implies backend charges for every mobile where it is executed. Contact us for details.

Request The Current Location

In order to get the current location, you can implement

	Location loc = veery.getCurrentLocation();
	if (loc!=null) {
		// do whatever you need with the Location object
	}

The Location object received is the standard Android Location object: https://developer.android.com/reference/android/location/Location.html

Register For Location Updates

You can create a callback function to get notified when the location has been updated:

veery.requestLocationUpdate(new Veery.LocationUpdate() {
	@Override
	public void onLocationUpdate(Location loc, long age) {
		if (loc!=null) {
			 //
			 // do whatever you need with the Location object
			 //
		}
	}
});

A nice place to do this is in your onCreate or onResume function.