BLEep Android Integration Guide

RevisionDateDetails
1.01 Nov 2013Document Creation
1.126 Feb 2014Edit for new version of Android SDK
1.217 Apr 2014New version of iOS SDK connected to control panel
1.328 May 2014Formatting Fix
1.410 June 2014Updated for Android SDK v1.3
1.517 Aug 2014Updated for Android SDK v1.5
1.67 Oct 2014Updated for Android SDK v1.6
  1. Introduction
  2. Overall Flow
  3. Note
  4. BLEep Android detection

Introduction

Rainmaker Labs is a mobile solutions specialist that focuses on BLEep (also known as Bluetooth® Low Energy Enhanced Presence) technology. This technology enables smartphonesto have contextual interactions with surroundings in a myriad of ways, unlocking various applications for marketing, healthcare, security, navigation & crowd driving purposes.

SENSE > RESPONSE > CONTENT > ACTION

The technology is primarily applied to deliver content to smartphones when they are within certain vicinity. Content can be skewed to drive immediate actions, which can be fulfilled within the smartphone or a nearby touch point.

Our platform is the only solution able to accurately determine precise geo-location & information such as which level a user is on within an urban building. This information allows us to accurately deliver adaptive triggers and actions

With BLEep technology, it is much more accurate than GPS.

‘Enhanced Presence’ technology allows us to know with precision when, where and which exact user has entered into a designated location.

Support Android Device
Minimum Android SDK Version – Android 4.3 (API Level 18) 
Tested on
  • Samsung (Galaxy S3, S3 Mini, Galaxy S4, S4 Mini, Note 2 and Note 3)
  • HTC (One)   

Overall Flow

http://www.rainmaker-labs.com/wp-content/uploads/2014/10/Screen-Shot-2014-10-20-at-11.38.17.png

The BLEep beacon is installed in a fixed location and broadcasts its signal constantly to all the devices around it. This could range from distances as close as 15cm to as far as 50m away.

The exact maximum range would depend on the environment that BLEep is deployed in.

Fundamentally, Bluetooth® signals are radio waves and as such suffer from the same limitations; and thus could be interfered with or absorbed, thereby limiting the range of detection.

Mobile apps within signal range pick up the Bluetooth® signal and estimate the distance between the device and BLEep by measuring the received signal strength. The closer you are to BLEep, the stronger the signal is. Minimum or maximum signal threshold could be implemented within the device applications to create a minimum detection radius.

Mobile apps could check this received signal strength depending on requirement. The more often the checking, the more stable and robust the signal is, which would enable a better customer experience to be attained.

Note
Integration of BLEep SDKs involves the insertion of sizeable portion of code. We do this to enable you fully control over what happens when a beacon is detected; what BLEep SDK does is essentially screen the beacons according to the triggers you configure on BMS and forward them to your app with the relevant action content where appropriate.

But don’t worry, we have sample code that you can simply copy and paste, and this guide will give you instructions and point out the parts that you may need to configure. Just refer to the sample app source code and comments when lost. If you're still facing problems, don't worry! Chat with us at getbleep.com (available 9am to 6pm (UTC + 08:00), Mondays to Fridays or drop us an email!

BLEep Android detection

For an example, please refer to the demo app. The code in here is all extracted from the demo.

Edit AndroidManifest.xml
Include permissions
<uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Declare these under <application>
Note: replace ‘com.rainmakerlabs.bleepsample’ with your app’s package name
<activity
            android:name=".VideoActivity"
            android:label="@string/app_name"
                                    android:configChanges="orientation|screenSize" >
        </activity>
       
        <service
            android:name=".BleepService"
            android:enabled="true"/>
       
        <receiver android:name=".BleepReceiver">
                            <intent-filter>
                                <action android:name="BLEepProcessIntent_com.rainmakerlabs.bleepsample"></action>
                                <action android:name="BLEepExitOnlyIntent_com.rainmakerlabs.bleepsample"></action>
                                <action android:name="BLEepStateIntent_com.rainmakerlabs.bleepsample"></action>
                            </intent-filter>
                        </receiver>
 
        <service
            android:name="com.rainmakerlabs.bleepservice.BLEepService"
            android:enabled="true"/>
        <service
            android:name="com.radiusnetworks.ibeacon.service.IBeaconService"
            android:enabled="true"
            android:exported="true"
            android:isolatedProcess="false"
            android:label="iBeacon" >
        </service>
        <service
            android:name="com.radiusnetworks.ibeacon.IBeaconIntentProcessor"
            android:enabled="true">
            <meta-data
                android:name="background"
                android:value="true"/>
        </service>
        <receiver android:name="com.rainmakerlabs.bleepservice.SyncAlarmReceiver">
                            <intent-filter>
                                <action android:name="android.intent.action.BOOT_COMPLETED"></action>
                            </intent-filter>
        </receiver>

Include libraries

1. Copy .jar file into lib Folder
  • androidibeaconservice.jar
  • bleepservice.jar
  • shutterbug.jar (if you’re using our sample code to download and display image

2. Add both .jar files to Java Build Path of project (Right-click project name under Package/Project Explorer, select Properties, Java Build Path, Libraries, then Add JARs…)
3. Add BLEep library into Project Folder
  • import com.rainmakerlabs.bleepservice.BLEepService;
Add classes to your project
  • AdDialog.java
  • BleepService.java
  • BleepReceiver.java
  • BleepActivity.java
  • VideoActivity.java
Add code to your existing activities

Make every activity inherit from BleepActivity instead of Activity

2.     In your splash activity (or the first activity that always appears when your app is launched), put in these functions:

   protected void onCreateForBleep() {
                        bleepSplashCreate();
            }
 
            protected void doAfterServiceConnection() {
                        bleepSplashAfterServiceConnection(); }

3.     In your main activity (the root one), include the bleepMainSomething functions in the relevant activity lifecycle callbacks:

   @Override
            protected void onStart() {
                        super.onStart();
                        bleepMainStart();
            }
 
            @Override
            protected void onStop() {
                        super.onStop();
                        bleepMainStop();
            }
           
            @Override
            protected void onDestroy() {
                        super.onDestroy();
                        bleepMainDestroy();
}

4.     Under BleepActivity.java, search for and configure the following where you see fit:

final static Class<?> rootClass = MainActivity.class;//use the root
class you used in the last step

protected static final boolean isTesting = true;//read the comments in the sample code. Generally, you should put ‘true’ during development and ‘false’ during deployment
protected static final boolean isCustomisable = false; //you would generally want to set this as false to integrate it into your app
BLEepService.setApiKey(contextAct, "pVdIAuPDX5MM1r8S4mnSwypfqHplyw9apple");//put in your API key from BMS
BLEepService. setShouldOnlyLogNearest(true);//override the default values of this and related settings if you wish
BLEepService.setServiceStickiness(android.app.Service.START_STICKY); //if not called, set to Service.START_NOT_STICKY by default. you should use this if you want the service to restart after it is killed by the system, and to allow the app to respond to beacons even after it has been killed from multitasking and across reboots. this is useful, but may drain battery faster. if it is sticky, certain options like autoStart and forceBmsSync may not always work as expected because the service is already running
thisBleepService.setUserId("Guest");//set the user id when user logs in to your app

and under bleepSplashAfterServiceConnection(), we recommend that you put the following code:

//thisBleepService.clearTimeIntervalLogForBeaconDetection();//normal
time interval, related to the 'Time Interval' rule condition. we recommend that
you don't comment this out for deployment purposes, but have included the
method here for your reference if it fits your special use case

thisBleepService.clearEntryTimeIntervalLogForBeaconDetection();//entry time interval, related to the 'Event Type' rule condition (value 'Entry'). we recommend calling this even for deployment. if the user kills the app while detecting a beacon, they will not be able to detect that beacon's 'entry' upon app relaunch unless this method is called
thisBleepService.clearLiveTimeIntervalLogForBeaconDetection();//live time interval, related to the 'Response Type' rule condition (value 'Static'). we recommend calling this even for deployment. if the user kills the app while it is waiting for a response from the server to retrieve the live communication data, it will not be able to re-request a response for the same communication for a while upon app relaunch unless this method is called

and where desired, please use these:

thisBleepService.startBleepDiscovery();//use this when you want to manually start scanning for beacons (either after you have manually stopped scanning, or if you have disabled auto sync)

thisBleepService.stopBleepDiscovery();//use this to manually stop scanning for beacons, say upon logout. may not work if called too soon after startBleepDiscovery or after it is auto started
thisBleepService.pauseBleepDiscovery();//use this when you want to pause reactions to beacons for a while, but don't actually want to stop it. (stopping and starting may take a few seconds or more, but pausing and resuming is practically instant.) detection logs will still work, just that nothing will be reflected in the UI
thisBleepService.resumeBleepDiscovery();//use this to resume reactions to beacons after pausing

Feedback and Knowledge Base