Skip to content

Locations

Introduction

Location module is used for running location based campaigns based on location of your application's user. Also module can be used for calculating the Work and Home locations of your application's user.

Integration steps


Integration of StreetHawk's Analytics module is the prerequisite for this module. Click here for the documentation on StreetHawk Analytics module.

  • Adding dependencies

For Android Studio as your IDE, add the following code in application's build.gradle under dependencies.

dependencies {
...
...
   compile 'com.streethawk:locations:1.8.22'
}
  • Register location module inside your application

Register location module with StreetHawk SDK and call init as shown below in onCreate function of your application's launcher activity.

import com.streethawk.library.core.StreetHawk;
import com.streethawk.library.locations.SHLocation;

...
...

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Application app = getApplication();
        StreetHawk.INSTANCE.setAppKey("<APP_KEY>");
        StreetHawk.INSTANCE.init(app);
    }
  • Asking user's permission for accessing locations.

Starting with Android MarshMallow (API 23), the application needs to request for user's permission for accessing locations from the device. Following is a sample code snippet for asking the permission. Click here for Android's documentation for permissions.

public class MainActivity extends Activity{
    private final int PERMISSIONS_LOCATION = 0;
    private final String TAG = "DemoApp";
...
...
// Start reporting location to server.
public void StartLocationReporting() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            Log.i(TAG, "Requesting permission");
            if(!checkForLocationPermission(this)) {
                this.requestPermissions(new String[]{Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION},
                        PERMISSIONS_LOCATION);
            }
        } else {
            Log.e(TAG,"Not requesting permission "+Build.VERSION.SDK_INT+" "+Build.VERSION_CODES.M);
        }
    }


/**
     * Check for location permission for Android MarshMallow
     * @param context
     * @return
     */
    private boolean checkForLocationPermission(Context context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            int coarseLocation = context.checkSelfPermission(android.Manifest.permission.ACCESS_COARSE_LOCATION);
            int fineLocation = context.checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION);
            if ((coarseLocation == PackageManager.PERMISSION_GRANTED) || (fineLocation == PackageManager.PERMISSION_GRANTED)) {
                return true;
            } else {
                return false;
            }
        } else {
            return true;
        }
    }

    @Override
    public void onRequestPermissionsResult(int requestCode,
                                           String permissions[], int[] grantResults) {

        switch (requestCode) {
            case PERMISSIONS_LOCATION: {
                // If request is cancelled, the result arrays are empty.
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
// Start StreetHawk location reporting
                    SHLocation.getInstance(this).startLocationReporting();
                } else {

                    Log.e(TAG, "Permission not granted by user");
                }
                return;
            }
        }
    }

Calculate Work and Home Locations only

Use reportWorkHomeLocationsOnly() API if you wish to use location module only to calculate Work and Home locations of your user. Please note that with this approach, you won't be able to run location based campaigns. Following is a code snippet to demonstrate the use of reportWorkHomeLocationsOnly(). You need not call this API if you are already using startLocationReporting().

    @Override
    public void onRequestPermissionsResult(int requestCode,
                                           String permissions[], int[] grantResults) {

        switch (requestCode) {
            case PERMISSIONS_LOCATION: {
                // If request is cancelled, the result arrays are empty.
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
// Start StreetHawk location reporting
                    SHLocation.getInstance(this).reportWorkHomeLocationsOnly();
                } else {

                    Log.e(TAG, "Permission not granted by user");
                }
                return;
            }
        }
    }

Stop Location Reporting

Use stopLocationReporting API to stop SDK to report locations back to StreetHawk server. The API when called also prevents SDK to automatically restart location reporting service when the user turns on his location on the device.

 public void stopLocationReporting(){
     SHLocation.getInstance(this).stopLocationReporting();
    }

Configure frequency of reporting locations

As an application developer, you may want to configure the frequency of location reporting so as to find a balance between accuracy you desire for your user's current location and battery consumption by your application.

{

...
 int UPDATE_INTERVAL_FG = 2;
        int UPDATE_DISTANCE_FG = 100;
        int UPDATE_INTERVAL_BG =  5;
        int UPDATE_DISTANCE_BG = 500;


        SHLocation.getInstance(this).updateLocationMonitoringParams( UPDATE_INTERVAL_FG,  UPDATE_DISTANCE_FG,  UPDATE_INTERVAL_BG,  UPDATE_DISTANCE_BG);

}

where,

Arguments Description Default value
UPDATE_INTERVAL_FG Minimum wait time in minutes before reporting user's location to server when application is in foreground 2 minutes
UPDATE_DISTANCE_FG Minimum distance the user need to move from his previous location before reporting location to server when application is in foreground 100 meters
UPDATE_INTERVAL_BG Minimum wait time in minutes before reporting user's location to server when application is in foreground 5 minutes
UPDATE_DISTANCE_BG Minimum distance the user need to move from his previous location before reporting location to server when application is in background 500 meters