Skip to content

Android SDK Quickstart

Note

We're sorry, this article hasn't been completed or updated yet. We're working on finishing it as soon as possible. In case of any questions, please reach out to our Support Team.

Setup

Prerequisites

  • A Kontakt.io Proximity Web Panel account
    If you need information about how to sign up for a web panel account or how to sign in for the first time, check out our support article How to sign in to your Kontakt.io Proximity Web Panel

  • Android 2.3 (API Level 9) or higher
    Android BLE support was released in 4.3 Jelly Bean. While Kontakt.io's Android SDK will compile on older versions of the OS, but components that are required for basic beacon functionality cannot be used below 4.3

  • Java 6 or higher

  • Android Studio or Eclipse with ADT

Step 1: Adding the SDK dependency to your project

There are two ways to get the Android SDK ready for use

  • Gradle dependency with Android Studio (recommended)
  • Importing JAR

Gradle

  • Make sure jCenter repository is included in your project's top level build.gradle file located at *myapplication*/build.gradle. This should be done automatically by Android Studio whenever you create new project. Your top build.gradle file should look similar to this:
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:{gradle_version}'
    }
}

allprojects {
    repositories {
        jcenter()
    }
} 
  • Add a dependency to the Kontakt.io Android SDK in your build
    Edit your application build file: *myapplication*/app/build.gradle
dependencies {
    compile 'com.kontaktio:sdk:{version}'
}

Info

The latest SDK version can be checked on GitHub

  • Some configurations may also need an additional exclusion (if you are getting errors during Gradle sync):
 packagingOptions {
     exclude 'main/AndroidManifest.xml'
 }

JAR

This section will run through the steps to install our SDK in Eclipse.

  1. Go to the Kontakt.io Android SDK on GitHub
  2. Click the Download ZIP button
  3. Un-zip the file to a temporary location.
  4. Create an empty directory for your eclipse project.
  5. Create a new libs/ directory in the project directory you've just created.
  6. Copy all of the .jar files from the directory to your new libs/ directory.
  7. Add following libs to your build path:
    • Gson 2.3.1
    • Retrofit 2.0.0
    • Retrofit Gson Converter 2.0.0
    • OkHttp 3

Import your project into Eclipse, and set the build SDK Project > Properties > Android. You'll need to use API 18: Android 4.3 (Jelly Bean) as the minimum SDK.

Step 2: Permissions

Interacting with beacons requires following permissions for different aspects of library:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  • BLUETOOTH - needed for ranging/monitoring devices
  • BLUETOOTH_ADMIN - needed for connecting to devices
  • INTERNET & ACCESS NETWORK STATE - needed for Kontakt Cloud communication

With the latest release of Android called Marshmallow, the permission system has changed significantly. Starting a Bluetooth Low Energy scan requires permission from Location group.

As a result of that one of the following permissions is required:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Info

Beginning in Android 6.0 permissions are not granted when users install the application. Location permission is now considered as dangerous, so user must accept it at runtime.

More information about the new permissions can be found on Google's Android training guide

Step 3: Registering Service

Enable the SDK Proximity service in the application section of the manifest.

<service android:name="com.kontakt.sdk.android.ble.service.ProximityService" android:exported="false"/>

Step 4: Proguard Configuration

If you are using ProGuard in your project add following rules into proguard-rules.pro file

-dontwarn okio.**
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

-keepclasseswithmembers class * {
    @retrofit2.http.* <methods>;
}

-keep class com.kontakt.sdk.** { *; }
-keep interface com.kontakt.sdk.** { *; }

Step 5: Providing API key

The Kontakt.io SDK may be initialized in two ways:

  • Static initialization
  • Dynamic initialization

Note

Providing valid API Key is essential for some of the SDK's features to work:

  • Battery health monitoring
  • Scanning shuffled beacons
  • KontaktCloud interactions

Other SDK's features that do not require cloud communication will still work if you don't provide the API Key.

Static Initialization

  1. Have your Application extend its 'onCreate()' method and include the following initialization code from our SDK:
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        KontaktSDK.initialize(this);
    }
}
  1. Put your API key in AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
 package="com.wpsine.myapplication" >
    ...

    <application ...>
        ...
       <meta-data
               android:name="kontakt.io.API_KEY"
               android:value="@string/kontakt_io_api_key" />
    </application>
</manifest>
  1. Create string resource in values.xml file
<resources>
    <string name="kontakt_io_api_key">YOUR API KEY</string>
</resources>

Dynamic Initialization

Alternatively, you can initialise the Kontakt.io SDK dynamically by passing the API key directly as a String parameter.

Please, notice also that there is no requirement to include the API key in the AndroidManifest.xml.

public class App extends Application {
   @Override
   public void onCreate() {
       super.onCreate();
       KontaktSDK.initialize("YOUR API KEY");
   }
}

Info

Remember to register your custom Application class in AndroidManifest.xml file and use your API key. Please also note that KontaktSDK must be initialized before first usage, but it is not mandatory to do it in Application class.