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.3.0"

Step 5: Configure the SDK in 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()
                                                        .initContext(this)
                                                        .initUrlType(UrlType.PROD)
                                                        .initApp("YOUR_SDK_ID", "YOUR_SDK_KEY");
    herowInitializer.synchronize();
}

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.

Warning:

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: GDPR Opt-ins

It is mandatory for your app to collect your end-users' GDPR optins, otherwise the HEROW SDK won't collect any information.

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
herowInitializer.allOptinsAreUpdated();
// We notice the Herow server that the SDK is ready to use.
herowInitializer.synchronize();

Step 7: Request the Location runtime permission

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

public void onCreate() {
    [...]
    herowInitializer.addPermissionToAsk(Manifest.permission.ACCESS_FINE_LOCATION);
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        HerowInitializer.getInstance().addPermissionToAsk(Manifest.permission.ACCESS_BACKGROUND_LOCATION);
    }
}

Note 1:

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

We recommend you to ask permission when your application needs it. Check our dedicated tutorial to do so.

Note 2:

Since Android 10, the Activity Recognition API require a runtime permission. We disabled it by default.

This permission is not mandatory but if you activate it, it will improve the SDK's performance. To enable it, call the following method:

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

Step 8: 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>

Note:

If your application's targetSdkVersion is below 29, you will need to implement the following 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 9: Configure your Custom ID

Custom ID

The Custom ID is the common user identifier used in your app. Implementing a Custom ID will help you reconciliate data from HEROW with your data from other platforms. We recommend to always hash your Custom ID.

It can be:

  • A unique ID you are using in your login system.
  • An email address.
  • A username.

Setting a Custom ID

To set a custom ID, make the following call as soon as the user logs in:

HerowInitializer.getInstance().setCustomId("hashUserEmail");
If the user logout, you can use the removeCustomId method.

HerowInitializer.getInstance().removeCustomId();`