Skip to content

Geofence

Introduction

The Geofence module is used for running location-based campaigns based on user's entry and exit into a geofence area. This document describes integrating StreetHawk SDK's Geofence module into your application. You will be required to register the geofence of interest into StreetHawk console. Steps for registering geofence in StreetHawk console are described below under Create Your First Geofence Based Campaign section.

Integration steps


Integration of StreetHawk's Analytics module is the prerequisite for this module. Click here for the document 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:geofence:latest.release'
}

StreetHawk geofence uses google dependency 'com.google.android.gms:play-services-location' for Geofence

  • Initialise StreetHawk

Call init as shown below in onCreate function of your application's launcher activity.

import com.streethawk.library.core.StreetHawk;
import com.streethawk.library.geofence.SHGeofence;

...
...

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

Stop Geofence Monitoring

  • Add ACCESS_FINE_LOCATION in AndroidManifest.xml The first step in requesting geofence monitoring is to request the necessary permission. To use geofencing, your app must request ACCESS_FINE_LOCATION. Add this in your AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  • Start Monitoring Geofences.

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

SHGeofence.getInstance(this).startGeofenceMonitoring();

StreetHawk will check for location permission for your app and present users with a custom dialog if user's location permission is denied.

Stop Geofence Monitoring

Use stopGeofenceMonitoring 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 stopGeofenceMonitoring(){
     SHGeofence.getInstance(this).stopGeofenceMonitoring();
    }

Create Your First Geofence Based Campaign

  • Create Geofence in StreetHawk Console

Open StreetHawk console and click on Geofence&Beacons under Growth Campaigns as shown below. Enter Title of the geofence and place the thumb pin at desired location to autofill latitude and longitude of your geofence.

  • Select Geofence filter

Create a new campaign by selecting Campaigns under Growth Campaigns and by clicking the add button. Click on Geofence Filter as shown below. You may opt to select some single geofence or all geofences by clicking on the locations drop down and selecting the geofences for campaigns. You can select the minimum distance for triggering by selecting distance from around drop down menu.

  • Select an action

Proceed to Choose the Engagement Method and select the desired action to be triggered when application user enters the geofence.

  • Set campaign running duration

Schedule your campaign to run over the period of time desired by selecting Real-Time Monitoring option. Please note if the option is not selected, your campaign will fire only once and will target only those users who are present in the geofence at the moment when campaign ran.

  • Save and run campaign

Give a title to your campaign and launch the campaign.