The Herow SDK allows your app to connect to the Herow platform or the AdTag platform.

The documentation is available for both platform.

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 Login, Password, and Company Key to initialize the SDK.
  • A zone, which has been configured on your herow account.
  • An Android Device, with Bluetooth 4.0 and Android 4.0 and above, to be able to interact with BLE beacons.
  • 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/Connecthings/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:4.1.1"

Step 5: Configure the SDK inside the ApplicationQuickStart class

  • Open the ApplicationQuickStart class
  • 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()
                                                        .initContext(this)
                                                        .initUrlType(UrlType.PRE_PROD / UrlType.PROD)
                                                        .initUser("YOUR_SDK_LOGIN", "YOUR_PWD")
                                                        .initCompany("YOUR_COMPANY_KEY");
    herowInitializer.synchronize();
}

Note 1:

The synchronize method allows to set up the SDK with a configuration file downloaded from the Herow platform or AdTag 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.

Note 2:

The HerowInitializer allows you to configure your access to the various Herow platforms and AdTag platforms. Connecthings gives you access to one or several of the following environments:

  • PRE_PROD: The pre-production platform of the Herow platform
  • PRE_PROD_ADTAG: The pre-production platform of the AdTag platform
  • PROD: The production platform of the Herow platform
  • PROD_ADTAG: The production platforms of the AdTag platform

Warning:

You will get two different access keys:

  • An access key to log into the Herow Platform or AdTag platform
  • An access key to use with our mobile SDK. This access key is composed of a login (identifier on Herow or AdTag), a password (API_KEY on Herow or AdTag) and your company name. Please make sure you use the good credentials to connect the SDK to the correct Herow Platform, otherwise your application won't be able to detect zones.

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() {
    [...]
     herowInitializer.addPermissionToAsk(Manifest.permission.ACCESS_FINE_LOCATION);
}

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

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:
<application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:supportsRtl="true"
    android:theme="@style/AppTheme"
    android:name=".ApplicationQuickStart">

</application>

Step 8: with Herow and Geofence

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

Note:

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

Note:

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

Warning:

Think to make your application compliant with the GDPR, otherwise the SDK won't collect any data.

You can refer to our dedicated tutorial

Step 8(Bis): with AdTag and Beacon

Configure a content associated to your beacon

  • Connect you to the AdTag Platform.
  • Find your Beacon
  • Configure a notification content in the SDK Content tab

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. Put the battery back in your beacon (if the battery is on, remove it, and wait few minutes before putting it back)

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

Warning:

Think to make your application compliant with the GDPR, otherwise the SDK won't collect any data.

You can refer to our dedicated tutorial