BLEep iOS 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 iOS SDK v1.3
1.517 Aug 2014Updated for iOS SDK v1.5
1.67 Oct 2014Updated for iOS SDK v1.6
  1. Introduction
  2. Overall Flow
  3. Note
  4. BLEep iOS 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 iPhone Device 
Minimum iPhone OS SDK Version – iOS 7.0 Tested on
  • Phone 4S and later
  • iPad (3rd generation and later)
  • iPod touch (5th generation)
  • iPad Mini (all generations)

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!

How duration and exit is tracked for individual beacons
While iOS has the method didExitRegion to track when the app has exited a beacon region, there is no way to determine when the app has went out of range of a particular beacon unless all 3 values (UUID, major and minor) are defined for the region. As such, our SDK uses its own method to determine when beacons go out of range.

When a beacon is newly detected, our SDK stores the time of detection. When it continues to be detected, the stored time is unmodified. However, when it stops being detected for a set interval (you can set this with the method setTimeBeforeCountedAsOut:), the time of first detection for this beacon is deleted. When there is a stored time linked to a beacon, that beacon is considered to be still in range, and the difference between the stored time and the current time is calculated to determine the duration of detection.

What to do if the app cannot process trigger at the moment
Imagine you walk past a beacon with your phone in your pocket and it triggers an alert to pop up with the message ‘1’. And then you walk past another beacon which triggers the message ‘2’. If you don’t want the app to close the first message before the user even sees it and then show the second (skipping to ‘2’ immediately), you have 2 options: 1) implement some sort of queue where user can click away the first message before being shown the second, or vice versa if you prefer; 2) don’t allow the app to show the second message before the first is manually dismissed by the user.

If you pick the latter option, the SDK has no way of knowing that the message ‘2’ has not been shown to the user. If you sent the time interval for the message ‘2’ to a day and it is triggered while another message is still being shown, the user will not see the message ‘2’ even if he stands in front of that beacon all day. To fix this, you can call a method to tell the SDK that this communication has not been triggered, so that the time interval condition will not prevent it from being shown later when the message ‘1’ is dismissed:
[[bleepManager sharedInstance] eraseTriggerLog:beacon];

This method will also come in handy when communications are triggered while the user interface is busy, like if the user is filling out a field in the settings page and you do not wish to interrupt with a pop-up.

BLEep iOS detection

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

Add bleepManager(SDK) to the project

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

Add these files to the project (if you wish to use our sample codes to detect beacons instead of your own)

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

  • ImageAds folder (5 files, found in our sample project)
And the following 3rd-party libraries can be freely downloaded from the Internet, but you can just copy the ones found in our sample project:
  • SVWebViewController
  • UIAlertView+Blocks
  • SDWebImage.framework (check https://github.com/rs/SDWebImage for instructions on how to add it to your project)
Add the following under Target -> Build Phases -> Link Binary with Libraries

http://www.rainmaker-labs.com/wp-content/uploads/2014/10/Screen-Shot-2014-10-20-at-12.49.06.png
  • libsqlite3.0.dylib
  • ImageIO.framework
  • SystemConfiguration.framework
  • MediaPlayer.framework
  • AVFoundation.framework

AppDelegate.m


Please add the following at the top:
#import "AdInfos.h"
#import "SVModalWebViewController.h"
#define NO_SET_BUNDLE
#define CALLBACK_STRING @"x-source=BLEEP&x-success=bleepsdkdemo://" //put in the callback URL you configured for your app, if applicable
#define TESTING //use this during development, comment out for deployment

Merge the following with your existing lifecycle callbacks: 

- (BOOL)application:(UIApplication
*)application didFinishLaunchingWithOptions:(NSDictionary
*)launchOptions { 
    [self didFinishLaunchingWithOptionsBleep];
//the following is necessary for the app to work properly in iOS 8. you can call these methods where appropriate   
    [[bleepManager sharedInstance] askForLocPermission];
    if ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)])
        [[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound categories:nil]];
 
    return YES;
}
 
- (void)applicationDidEnterBackground:(UIApplication *)application {
    [self applicationDidEnterBackgroundBleep];
}
 
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [self applicationDidBecomeActiveBleep];
}

Find this line in the AppDelegate in the sample project, and copy everything after it into your own AppDelegate:

#pragma mark - BLEep

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

Then search for and configure the following where you see fit:

[[bleepManager sharedInstance] setApiKey:@"pVdIAuPDX5MM1r8S4mnSwypfqHplyw9apple"];//put in your API
key from BMS

[[bleepManager sharedInstance] setUserId:@"get the user id from your app"];//set the user id when user logs in to your app
[[bleepManager sharedInstance] setShouldOnlyLogNearest:YES]; //override the default values of this and related settings if you wish

and under didFinishLaunchingWithOptionsBleep, we recommend that you put the following code:

//[[bleepManager
sharedInstance] 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
[[bleepManager sharedInstance] 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
[[bleepManager sharedInstance] 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:

[[bleepManager sharedInstance] 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)

[[bleepManager sharedInstance] 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
[[bleepManager sharedInstance] 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
[[bleepManager sharedInstance] resumeBleepDiscovery]; //use this to resume reactions to beacons after pausing

AppDelegate.h (merge with what you have now)

#import <UIKit/UIKit.h>
#import <CoreBluetooth/CoreBluetooth.h>
#import <AVFoundation/AVFoundation.h>
#import <MediaPlayer/MediaPlayer.h>
#import <SDWebImage/UIImageView+WebCache.h>
#import "UIAlertView+Blocks.h"
#import "bleepManager.h"
@interface
DemoKitsAppDelegate : UIResponder <UIApplicationDelegate, bleepManagerDelegate, CBCentralManagerDelegate> {
    UIBackgroundTaskIdentifier backgroundUpdateTaskBleep;
    UIAlertView *alert;
    AVPlayer *audioPlayer;
    CBCentralManager *bluetoothManager;
    MPMoviePlayerViewController *movieViewController;
}
 
@property (strong, nonatomic) UIWindow *window;

Feedback and Knowledge Base