switch to developers doc

Getting started - Android

Notification Service with Location and API calls
  1. Woosmap Geofencing
  2. Overview
  3. Pre-requisites
  4. Usage
  5. Simulate Notification
  6. Additional Documentation
  7. Contributing
  8. License

Woosmap Geofencing

Location intelligence is one of the next revolutions to improve and “smoothen” user experience on mobile. Mobile operating systems use and provide multiple location services that might be tricky to handle or tune to achieve advanced location based services on mobile. And users are more and more aware of the capabilities of their mobile devices. During the last two years, we analysed, exploited and followed the evolution of those location services, changes that occurred either on tech side or regulation side.

We are convinced that location is an effective way for App makers to propose tailor made and locally contextualised interactions with mobile users. But knowing the location of a user is not enough. Knowing from what a user is close to or what he is visiting is the important part. So we decided to share our findings and tricks for location collection on mobile to help you focus on this real value of location.

This repository is designed to share samples of codes and a SDK on Android to take the best of location in your mobile apps. We had 3 main focus when developing and sharing this code: take full advantage of location capabilities of mobile devices, doing so in a battery friendly way and be fair with user privacy (see Location permissions).

Woosmap Geofencing SDK and sample app should help you build Rich Push Notifications (highlighted with a Location context), analyse your mobile users surroundings (search for proximity to your assets, competitors, etc) and much more on Android to go a step further on Location Intelligence.

Use case where location matters:

As a banking company, you need to enrich the expense list with local information (logo, shop info, etc)? Use this repo to learn how to leverage locally enriched notification to retrieve local information where your users spend their money.

As a retailer company, you need to be informed when a user is close to one of your stores (or competitors’)? Find in this repo how to collect in background location of your users and build your own geofencing analysis.

As a retailer, insurance, banking or travel company, you need to add local context to your user profiles in your CRM? Build your own process of background location collection in your mobile app and analyze geographic behaviors of your mobile users.

As a retailer, insurance, banking or travel company, you want to be informed when a user is visiting specific POIs you decided to monitor (your own stores, your competitors, specific locations)? Use our SDK/code samples to not just collect location but directly obtain “visit triggers” and build advanced scenarios (e.g. a Bank being able to propose specific loans or services when users visits Real Estate agencies, Car Dealers, etc - an Insurance company proposing travel insurance when users visit airports, car insurance when users visit car dealers, etc)

Overview

Get user location

Collect in background user’s locations and host them in a local database. Call the Woosmap Search API to retrieve closest stores to each location to locally contextualized users journeys.

WoosmapGeofencing

Enrich Notification with user location and POIs (Points of Interest)

Get the location of a user on notification reception, to complete the payload with local information from third parties APIs. In this sample, fetched location is then used to perform a request to the Woosmap Search API to get the closest POIs (Points of Interest) to the location of the user. In addition, a call to Google Static Map is performed to enrich the notification with a map displaying the user’s location and the closest POIs.

Notification Location

Detect Visits (spending time at one place) of your users

Get the location and the time spent when a user is visiting places. Once again use the Woosmap Search API if needed to detect if your users visit you stores, your competitors or POI you may want to monitor.

Visit

Detect Zone of Interest (cluster) of your users

Identify areas of interest for your users (location where they spend time, once or recurrently).

Visit

Classification of Zone of Interest (cluster)

The classification of zones of interest (zois) aims to assign them types. For now, two types are supported “home” (zone where a user is supposed to live) and “work” (zone where a user is supposed to work).

Classification

Calculations for each zoi are performed to determine the number of different weeks that the user has spent there. A zoi is considered to be recurrent if the number of weeks spent in the zone is greater than or equal to the average of the number of weeks spent in all the zones.

The classification of zois is enable by default. For disable that, in your MainActivity, you can change the value in the settings of the SDK as follow:

// Set classification of zoi enable:
WoosmapSettings.classificationEnable = true;

Pre-requisites

Installation

Get Keys

Google map Static

Google map in app

Search API

Search API

User Location

User Location

Usage

The first step that should always be done each time your app is launched (in Foreground AND Background) is to set your Woosmap Private key Search API. This should be done as early as possible in your mainActivity on the method onCreate.

Import and instanciate Woosmap library

Instanciate Woosmap and set keys:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Set Keys
    WoosmapSettings.privateKeyWoosmapAPI = "";
    WoosmapSettings.privateKeyGMPStatic = "";

    // Instanciate woosmap object
    this.woosmap = Woosmap.getInstance().initializeWoosmap(this);


    this.woosmap.setLocationReadyListener(new WoosLocationReadyListener());
    this.woosmap.setSearchAPIReadyListener (new WoosSearchAPIReadyListener ());
    this.woosmap.setDistanceAPIReadyListener (new WoosDistanceAPIReadyListener ());
    this.woosmap.setVisitReadyListener (new WoosVisitReadyListener ());

    // Visit Detection Enable
    WoosmapSettings.visitEnable = true;

    // For android version >= 8 you have to create a channel or use the woosmap's channel
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        this.woosmap.createWoosmapNotifChannel();
    }
}
@Override
public void onResume() {
    super.onResume();
    if (checkPermissions()) {
        Log.d("WoosmapGeofencing", "Permission OK");
        this.woosmap.onResume();
    } else {
        Log.d("WoosmapGeofencing", "Permission NOK");
        requestPermissions();
    }
}

@Override
public void onPause(){
    super.onPause();
    Log.d("WoosmapGeofencing", "BackGround");
    if (checkPermissions()) {
        this.woosmap.onPause();
    }
}

To get Google map in the app, add your GMP SDK android key in the manifest:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.webgeoservices.sample">

    <uses-permission android:name="android.permission.INTERNET" />
    ...
   ...

    <application
      ...
      ...

       <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="GMP_KEY"/>

    </application>

</manifest>

To work properly, you have to instanciate the Woosmap object in the onCreate function and call Woosmap’s onResume and onPause functions.

Configure filters to refresh location and activate visits detection

You can make filters:

The default parameters were determined by testing in real conditions in order to obtain the best data while consuming little battery, you can modify them according to your use cases.

Retrieve User Location

In your mainActivity, create a Listener connect to the interface Woosmap.LocationReadyListener and set a callback to retrieve user current location.

public class WoosLocationReadyListener implements Woosmap.LocationReadyListener
{
    public void LocationReadyCallback(Location location)
    {
        onLocationCallback(location);
    }
}

private void onLocationCallback(Location currentLocation) {
    ...
}

Retrieve POIs from Search API

In your mainActivity, create a listener connected to the interface Woosmap.SearchAPIReadyListener and set a callback to retrieve POIs from the Search API request.

public class WoosSearchAPIReadyListener implements Woosmap.SearchAPIReadyListener
{
    public void SearchAPIReadyCallback(POI poi)
    {
        onPOICallback(poi);
  }
}

private void onPOICallback(POI poi) {
    // get POI
}

Enable or disable Search API request

The Search API request on each location is enable by default. For disable that, in your MainActivity, you can change the value in the settings of the SDK as follow:

WoosmapSettings.searchAPIEnable(true);

If you want call Search API “on demand”, you can launch the request with this method :

// Instantiate the PositionManager
PositionsManager mPositionsManager = new PositionsManager(getContext(), WoosmapDb.getInstance(getContext(), true));

// Launch the request
 mPositionsManager.searchAPI(48.884722,2.401838);

You retrieve the result by the listener explain above.

Retrieve Distance from Distance API

In your mainActivity, create a listener connected to the interface Woosmap.DistanceAPIReadyListener and set a callback to retrieve distance from the Distance API request.

public class WoosDistanceAPIReadyListener implements Woosmap.DistanceAPIReadyListener
{
    public void DistanceAPIReadyCallback(DistanceAPI distanceAPIData);
    {
        onDistanceCallback(distanceAPIData);
  }
}

private void onDistanceCallback(DistanceAPI distanceAPIData) {
    // get Distance

}

Enable or disable Distance API request

The Distance API request on each POI is enable by default. For disable that, in your MainActivity, you can change the value in the settings of the SDK as follow:

WoosmapSettings.distanceAPIEnable(true);

If you want call Distance API “on demand”, you can launch the request with this method :

// Instantiate the PositionManager
PositionsManager mPositionsManager = new PositionsManager(getContext(), WoosmapDb.getInstance(getContext(), true));

// Launch the request
// Set distination coordinate
    List<Pair<Double, Double>> listDestinationPoint = new ArrayList<>();
    listDestinationPoint.add(new Pair(lat, lng));
    mPositionsManager.distanceAPI(48.884722,2.401838,listDestinationPoint);

You retrieve the result by the listener explain above.

Retrieve visit detection

In your mainActivity, create a listener connected to the interface Woosmap.VisitReadyListener and set a callback to retrieve visits.

private void onPOICallback(POI poi) {
    new POITask(getApplicationContext (),this).execute();
}

public class WoosVisitReadyListener implements Woosmap.VisitReadyListener
{
    public void VisitReadyCallback(Visit visit)
    {
        onVisitCallback(visit);
  }
}

private void onVisitCallback(Visit visit) {
    // get visit
}

Retrieve Zone of Interest

ZOIs are built from visits, grouped by proximity. We use the Fast Incremental Gaussian Mixture Model of classification Algorithm FIGMM to build and update our ZOI according to visits recurrency along time.

you can recover the ZOIs generated by making a request in the database.

ZOI[] ZOIList = WoosmapDb.getInstance(mContext, true).getZOIsDAO().getAllZois();

Each ZOI includes the following informations:

public ArrayList<String> idVisits = new ArrayList<>();

public double lngMean;

public double latMean;

public double age;

public double accumulator;

public double covariance_det;

public double prior_probability;

public double x00Covariance_matrix_inverse;
public double x01Covariance_matrix_inverse;
public double x10Covariance_matrix_inverse;
public double x11Covariance_matrix_inverse;

public String wktPolygon;

public long startTime;

public long endTime;

public long duration;

Enable or disable location refresh

The location monitoring is enable by default. For disable that, in your MainActivity, you can change the value in the settings of the SDK as follow:

woosmap.enableTracking(true);

Enable location after a device reboot

Create the BroadcasReceiver

To collect location after a device reboot without having to relaunch the application, you have to create a Broadcast which launches the jobInstantService WoosmapRebootJobService when it receives the BOOT_COMPLETED event.

package com.webgeoservices.sample;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

import com.webgeoservices.woosmapGeofencing.WoosmapRebootJobService;

public class RunOnStartup extends BroadcastReceiver {

    public void onReceive(Context context, Intent intent) {
        if ("android.intent.action.BOOT_COMPLETED".equals(intent.getAction())) {
            WoosmapRebootJobService.enqueueWork(context, new Intent());
  }
    }
}

Add the BroadcastReceiver to the Manifest

Add the permission android.permission.RECEIVE_BOOT_COMPLETED

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

Then, just declare your receiver in the Manifest.xml in the application bloc

<receiver android:name=".RunOnStartup">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>

Simulate Notification

Additional Documentation

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Thank you for your suggestions!

License

Woosmap Geofencing is released under the MIT License. See LICENSE file for details.