What you will learn

This document describes:

  • How to configure your gradle with our nexus server and our SDK
  • How to configure the SDK in your application

Prerequisites - What you need to get started

  • Your SDK credentials, including an SDK ID and SDK Key on HEROW to initialize the SDK.
  • A zone, which has been configured on your herow account.
  • An Android Device, with Android 4.0 and above.
  • The Android Studio application, which you can download from the Android Developers website.

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/herowio/sdk-tutorial.git
  • In the cloned sdk-tutorial folder, navigate to android>zones>1-QuickStart>Starter

Step 2: Launch QuickStart in Android Studio

  • Launch Android Studio

  • Check that your Android SDK is up-to-date

  • Navigate to Tools > Android > SDK Manager

    • Inside the SDK Platform tab, check that Android 6 has been correctly installed
    • Inside the SDK Tools tab, check that the Android Tools, the Android Support Library, and the various Google Services have all been correctly installed
  • In the Android Studio Wizzard, click on import project

  • Or, if you already are inside an Android Studio project, click on File > Open

  • In the cloned sdk-tutorial folder, navigate to android>zone>1-Quickstart>Starter

Step 3: Configure the project Gradle with our nexus

  • Inside the Gradle section, open the build.gradle project file (named build.gradle(Project: Starter))
  • Add the following code to the allprojects > repositories section:
maven {
     url "https://forge.herow.io/nexus/content/groups/public"
 maven {
     url "https://forge.herow.io/nexus/content/repositories/releases"

Step 4: Configure the project Gradle with our SDK

  • Inside the Gradle section, open the build.gradle app file (named build.gradle(Module: app))
  • Add the appropriate version of the SDK to the dependencies section:
  implementation "com.connecthings.herow:herow-detection:6.2.0"

Step 5: Configure the SDK inside the ApplicationQuickStart class

  • Open the ApplicationQuickStart class
  • Add the needed import instructions
import android.Manifest;
import com.connecthings.herow.HerowInitializer; 
import com.connecthings.util.connection.Url;
  • Configure the HerowInitializer with your SDK credentials & environment in the onCreate method, and launch the synchronization process with the Herow Platform.
public void onCreate() {
    HerowInitializer herowInitializer = HerowInitializer.getInstance()
                                                        .initApp("YOUR_SDK_ID", "YOUR_SDK_KEY");

Note 1:

The synchronize method allows to set up the SDK with a configuration file downloaded from the Herow platform.

The SDK will start the zone detection process only when the file download is complete.

This configuration file is saved in cache, and the SDK checks for updates at regular intervals.


The initContext method must be called from Application.onCreate(). It is mandatory to call it from there, because when the application restart on background only this method will be called. When starting on background, Android system won't call any activities' methods. that's why it's the way to do it properly.

Step 6: Request the location permission

The SDK offers an easy way to request the location permission.

In the AppplicationQuickStart class, use addPermissionToAsk method from the HerowInitializer:

public void onCreate() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {

Note 1:

The permission will be asked as soon as an activity starts.

This is great to quickly test but we recommend you to ask permission when your application needs it.

Note 2:

The SDK provides several methods to manage permissions. You can check our dedicated tutorial

Note 3:

Since Android 10, the Activity Recognition API require a runtime permission. So we disabled it. This permission is not mandatory but if you activate it, it will improve the SDK performance, you can enable it by calling the following method:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { HerowInitializer.getInstance().addPermissionToAsk(Manifest.permission.ACTIVITY_RECOGNITION); }

Step 7: Configure the manifest

  • Open the AndroidManifest.xml file inside the manifest folder
  • Add the name of the customized application class to the application tag:



If your application's targetSdkVersion is below 29, you will need to implement the following lines into your AndroidManifest.xml between the tags.

<service android:name="com.connecthings.taskmanager.services.ForegroundNotificationTaskService" tools:node="replace" />

This is because our SDK uses android:foregroundServiceType for all foreground tasks which is implemented only from Android Q API 29 and it's not backward compatible. See official documentation

By implementing the lines needed, you will override our service's declaration.

Step 8: Add the GDPR compliance support

It's mandatory to make your application compliant with the GDPR, otherwise the SDK won't work.

You can find an example, in the quickstart code sample, which show how to give the optins.

final HerowInitializer herowInitializer = HerowInitializer.getInstance();
// Replace the value of this variable with the user answer to be GDPR compliant.
boolean optinAccepted = true;
herowInitializer.updateOptin(OPTIN.USER_DATA, optinAccepted);
// Commit the optins value
// We notice the Herow server that the SDK is ready to use.

You can refer to our dedicated tutorial to learn everything about it.

Set a campaign on Herow platform

  • Connect you to the Herow Platform.
  • Create a zone at 200m of your office with a radius of 100m.
  • Create a campaign associated to the zone.
  • Don’t forget to launch the campaign !

Generate your first notification

  1. Install the application

  2. Accept the location permission and notification permission

  3. Close your application or leave it running in the background

  4. Go physically with your device in the zone you have just created before, you will receive the notification. This could take few seconds for your device to localize you are into the zone, and send you the notification associated.

  5. Click on the notification that appears on your screen just for fun


To customize the notification aspect you can follow this tutorial.


To increase the efficiency of the SDK, make sure that the device has a good network signal and enable the Wifi.


To get better performance on Android 8 and later, the SDK uses a foreground notification to get location updates. You can learn more about reading the foreground notification tutorial