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 BLE beacon, which has been configured on your account, in order to test interactions with your app.
  • 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>beacon>1-QuickStart>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>beacon>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.adtag.eu/nexus/content/groups/public"
}
maven {
url "https://forge.adtag.eu/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:
compile "com.connecthings.adtag:android-adtag-beacon:2.7"

Step 5: Configure the SDK inside the ApplicationQuickStart class

  • Open the ApplicationQuickStart class
  • Configure the AdtagInitializer with your SDK credentials & environment in the onCreate method, and launch the synchronization process with the AdTag Platform.
AdtagInitializer.initInstance(this)
.initUrlType(UrlType.DEMO / UrlType.PRE_PROD / UrlType.PROD / UrlType.PROD_US)
.initUser("YOUR_SDK_LOGIN",  "YOUR_PWD")
.initCompany("YOUR_COMPANY_KEY").synchronize();

Note 1:

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

The SDK will start the beacon 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 AdtagInitializer allows you to configure your access to the various AdTag platforms. Connecthings gives you access to one or several of the following environments:

  • The Demo platform is ideal for technical Proof of Concept (POC) phases
  • The Pre-production platform is generally used for beta versions
  • The Production & Production US platforms are our live environments, and used when you are ready to publish your application

Warning:

You will get two different access keys for each platform that you can access:

  • An access key to log into the AdTag Platform
  • An access key to use with our mobile SDK, called API_KEY. Make sure you use the API_KEY (login, password, and platform) to connect the SDK to the correct AdTag Platform, otherwise your application will not be able to detect the beacons.

Step 6: 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 7: Test your configuration

  • Check that your Android Device is in Developer Mode
  • Connect it to your computer
  • Start your beacon
  • In Android Studio, click on Play to launch the installation process on your phone

  • On Android 6 and above, when the application starts, a popup asks for permission to access your phone location: grant it!

Tip:

This popup appears because of the FragmentLocationPermision class declared in the activity_main.xml file.

Learn more in the managing location permission tutorial

  • Once the application is running:

  • If you see "BACKEND_SUCCESS, 1 beacon(s) detected, 1 content(s) attached to the beacon in the AdTag Platform", it means your SDK and your beacon are correctly configured. You can move on to the next step.

  • If you see "BACKEND_SUCCESS, 0 beacon(s) detected, 0 content(s) attached to the beacon in the AdTag Platform", check that your beacon is active, and that you have configured the SDK with the correct UUID.

  • If you see "BACKEND_SUCCESS, 1 beacon(s) detected, 0 content(s) attached to the beacon in the AdTag Platform", it means that your beacon is not registered on the AdTag Platform, or no content has been attached to it. You can learn how to associate content to a beacon in the beacon content tutorial.

  • If you see "BACKEND_ERROR, 1 beacon(s) detected, 0 content(s) attached to the beacon in the AdTag Platform", make sure you used the correct credentials to initialize the SDK.

  • Before moving on to the next step, stop the beacon emission process, and wait until you see "0 beacon(s) detected".

Tip:

There are 2 solutions to stop the emission process:

  • You can put the beacon inside a microwave (but don't start it!)
  • You can remove the battery from the beacon (in that case, depending on the model, it can take up to 30 seconds for the beacon to start emitting again after you reinsert the battery)

This allows to simulate a new region entry for the smartphone, and generate a notification.

Step 8: Generate your first beacon notification

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

  2. Remove the beacon from the microwave or reinsert the battery

  3. Wait for a few seconds (maximum 1 minute)

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

Note:

On some phones with Android 6 and above, it is necessary to enable location on the phone to enable beacon detection when the application is in the background.