Introduction

BeaconsInSpace makes it easy for you to add a revenue stream from your mobile users without affecting the user experience.

The purpose of this introduction is to provide you with an overview of BeaconsInSpace and the services we provide.

We have two core services that are organized around generating location data and making you money:

  • BeaconsInSpace REST API: our core API that generates beacon detections from your users. The easiest way to use the API is via our iOS SDK or Android SDK.
  • Mission Control: our cloud dashboard for you to view your earnings, access your API key, view location analytics, and integrate with third-party platforms and APIs.

    The cloud dashboard and the API work in tandem. You can start earning revenue in minutes when you sign up.

SDK Overview

The BeaconsInSpace SDK for iOS makes it easy for you to start earning revenue from our beacon network.

At its core, the SDK does the following:
Automatically establishes full beacon detection functionality
Provides your app with access to all beacons in the BeaconsInSpace network
Automatically posts enter and exit events to generate data, analytics, and enable third-party integrations

We built the SDK on Apple Core Location and it currently supports iBeacon.

Add BeaconsInSpace to your iOS app

The guide below will get you setup with full functionality in 5 minutes.

BeaconsInSpace uses Cocoapods for installs. If you would like to manually install our SDK please download the latest version.

Note: For manual installs, after you have added the BeaconsInSpace.framework to your Xcode project, you must navigate to Build Settings > Linking > Other Linker Flags and add "-ObjC".

1. Get setup

Here's what you'll need before installing the SDK:
Your API Key.
Signup for a free account to get your API Key in Mission Control.
1 iPhone (4S or newer) or iPad (3rd gen. or newer) with iOS 7+, to run your app.
1 Mac computer with Xcode.

Note: BeaconsInSpace does not require location background modes, CoreBluetooth, or a Bluetooth permission prompt for the end user. Unless you are using location background modes or CoreBluetooth for a different reason, please do not include them when submitting to the store.

2. Install CocoaPod

To run the CocoaPod, open your terminal and navigate to your apps Xcode project.

If you haven't already created a Podfile for your application, create one with:

pod init
    

Next, open the Podfile for your app and enter:

platform :ios, '9.0'
use_frameworks!
target "YOUR_APP_NAME" do
	pod 'BeaconsInSpace'
end
    

Save the file and run:

pod install
    

This creates an .xcworkspace file for your application. Use this file for all future development on your application.

3. Setup the beacon manager

In the AppDelegate.m put the following in your import statements:

@import BeaconsInSpace;
    
import BeaconsInSpace
    

In the application:didFinishLaunchingWithOptions: method place the following code:

[BeaconsInSpace provideAPIKey:@“YOUR_API_KEY”];
    
BeaconsInSpace.provideAPIKey("YOUR_API_KEY")
    

This sets up the beaconManager, which will automatically connect you with your test beacons and subscription beacons with BeaconsInSpace.

4. Authorize Location Services

BeaconsInSpace uses background location monitoring to detect when users are near a beacon. In order to use location services, go to the info.plist and put in the Key "NSLocationAlwaysUsageDescription", and for the String Value enter the message you'd like to display to users when asking for their location.

The BeaconsInSpace beaconManager will handle asking for permission once this is set.

<key>NSLocationAlwaysUsageDescription</key> <string>Enter your custom message to request location access</string>
    

5. Setup the delegate

To implement the <BeaconsInSpaceDelegate> in the ViewController.m simply add the following to your existing import statements:

@import BeaconsInSpace;
    
import BeaconsInSpace
    

Then, next to your interface header enter the following:

@interface ViewController () <BeaconsInSpaceDelegate>
    
class ViewController: UIViewController, BeaconsInSpaceDelegate {
    

Lastly, in your viewDidLoad method enter the following:

[[BeaconsInSpace beaconManager] addDelegate:self];
    
BeaconsInSpace.beaconManager().add(self)
    

That's all you need to get going with the BeaconsInSpace platform.

6. Confirm the SDK is initialized

You can confirm the SDK has been initialized successfully by viewing "The BeaconsInSpace SDK has been initialized." in the development environment logs. If you see this line of text, you are all set and ready for Step 7.

7. Add the AdSupport.framework

Before you submit your app, please make sure to include the AdSupport.framework in your project. The BeaconsInSpace SDK requires this framework in order to run properly.

8. Submit to the App Store

Before submitting to the App Store please be aware that BeaconsInSpace collects the IDFA. When you get asked, "Does this app use the Advertising Identifier (IDFA)?" on this page, please make sure to check the following three boxes:

  1. “Attribute this app installation to a previously served advertisement”
  2. “Attribute an action taken within this app to a previously served advertisement”
  3. “I, YOUR_NAME, confirm that this app, and any third party…”

Note: please do not check the box labeled ““Serve advertisements within the app” unless you display ads or already have a standard process of checking this box and collecting the IDFA.

Update Your Privacy Policy

Before going live, please update your privacy policy. Consult with your legal team, and include the following sample or something similar:

Sample: We share data we collect about you including unique identification numbers associated with mobile devices or through its API (including, for example, a Unique ID for Advertisers ("IDFA"), Unique ID for Vendors ("IDFV"), Google Ad ID, or Windows Advertising ID), mobile carrier, device processes, device type, model and manufacturer, mobile device operating system brand and model, battery life, and, depending on the user’s mobile device settings, the geographical location data, including GPS coordinates (e.g. latitude and/or longitude) or similar information regarding the location of the mobile device (“User Data”) with our third party partners, that enables us to provide you with information, advertisements, or offers specific to your location and interests.   

By accepting our terms of service, you consent to the collection, storage and processing of your data by our third party partners for the purposes of: (i) providing or improving their services; (ii) enabling third parties to assist us and the retailer and venues (in which the beacons are located) in better serving and understanding our users; and (iii) sharing your data with third parties so they can provide or enable the provision of content, offers or other marketing solutions that may be of interest to you. You also consent to having your data transferred to and processed in the United States or any other jurisdiction in which our third party partners or their parent, subsidiaries, affiliates, service providers or partners maintain facilities. If you do not consent to the collection and transfer of the aforementioned data through the identification of your mobile device, we recommend that you: (a) delete our app or adjust the in-app settings of the app; or (b) opt out of sharing your mobile advertiser ID by limiting ad tracking on the device. For iOS, navigate to your Settings > Select Privacy > Select Advertising > Enable the “Limit Ad Tracking” setting. For Android, open your Google Settings app > Ads > Enable “Opt out of interest-based advertising. For more information on specific opt-out choices, please visit: http://www.networkadvertising.org/mobile-choices.

BeaconsInSpace Class Reference

BeaconsInSpace provides foreground and background beacon detection for all beacons subscribed to the API key set in the class method provideAPIKey:

This category provides additional support for applications that are already receiving location updates.

Methods

Provides your API key to the BeaconsInSpace iOS SDK. This key can be found in your account on Mission Control and can be optionally linked to your app’s bundle id. This must be called before the beaconManager class method, and should not be called again as it will reset your current beacon monitoring session.
Note: If an invalid API Key is provided this will raise an exception.
+ (BeaconsInSpace *)provideAPIKey:(NSString *)apiKey;
    
public class func provideAPIKey(apiKey: String) -> BeaconsInSpace
    
Provides the shared instance of BeaconsInSpace for the BeaconsInSpace SDK for iOS. This object persists throughout the app lifecycle and monitors the nearby beacons registered to the API key set in the class method provideAPIKey:
Note: This method will throw an exception if the API Key has not previously been validated in the class method provideAPIKey:
+ (instancetype)beaconManager;
    
public class func beaconManager() -> Self
    
Adds an object subscribing to the <BeaconsInSpaceDelegate> protocol to the available delegates
- (void)addDelegate:(id<BeaconsInSpaceDelegate>)delegate;
    
public func addDelegate(delegate: BeaconsInSpaceDelegate)
    
Returns the nearest regions to the current user location if currently within a known region. Otherwise returns nil. Regions returned are sorted by distance closest to furthest
- (void)nearestRegions:(NSNumber *)limit withCompletion:(void (^)(NSArray <BISRegion *> *nearbyRegions, NSError * __nullable error))completion;
    
public func nearestRegions(limit: NSNumber, withCompletion completion: ([BISRegion], NSError) -> Void)
    
Parameters
Name
Description

limit

Specifies the number of beacons to be returned by the call. The maximum is 20. count values greater than 20 will return 20 beacons.

completion

Block that returns the nearest BISRegions in an NSArray upon completion of a web call. Returns an empty NSArray if not currently inside a beacon region.

Returns the version for this release of the BeaconsInSpace iOS SDK.
+ (NSString *)sdkVersion;
    
public class func sdkVersion() -> String
    

LocationAware Methods

The BeaconsInSpace+LocationAware.h category provides additional methods for apps that are already utilizing core location and the location updates background capability. For example, if you already rely on an existing SDK that uses CoreLocation and constantly updates a users location, then the LocationAware category may be a good option to save battery.
Provides the BeaconsInSpace class with the current user location. The beaconManager will immediately begin detecting beacons near to your location. Call this method whenever your app receives a location update.
Note: This method will throw an exception if the API Key has not previously been validated in the class method provideAPIKey: If your app does not receive location updates at least every 10 minutes, do not implement this method.
+ (void)updateCurrentLocation:(CLLocation *)location
    
public class func updateCurrentLocation(location: CLLocation!)
    
Parameters
Name
Description

location

The most recent location update received by the application

Returns the nearest regions to the current user location provided as the location parameter. Regions returned are sorted by distance closest to furthest.
- (void)nearestRegions:(NSNumber *)limit currentLocation:(CLLocation *)location withCompletion:(void ( ^ ) ( NSArray<BISRegion*> *nearbyRegions , NSError *__nullable error ))completion    
func nearestRegions(limit: Int, currentLocation location: CLLocation, withCompletion completion: (nearbyRegions: [BISRegion], error: NSError) -> Void) { }
    
Parameters
Name
Description

limit

Specifies the number of regions to be returned. The maximum is 20. Values greater than 20 will return 20 regions.

location

The current user location

completion

Block that returns the nearest regions in an NSArray of BISRegion objects upon completion of the web call.

Protocols

The delegate of a BeaconsInSpace object must adopt the BeaconsInSpaceDelegate protocol. The methods in this protocol allow the delegate to respond to various actions taken by the beaconManager.
To setup the delegate, in viewDidLoad, place the following:
[[BeaconsInSpace beaconManager] addDelegate:self];
    
BeaconsInSpace.beaconManager().addDelegate(self)
    
Instance Methods
Notifies user when a region is entered. Returns information about the entered region. This method is triggered when proximity is less than or equal to enterRegionProximityTrigger:
- (void)didBeginBISVisit:(BISVisit *)visit;
    
optional public func didBeginBISVisit(visit: BISVisit)
    
Parameters
Name
Description

visit

Represents a visit to a region

Notifies user when a region is exited. Returns information about that region as well as the duration of the visit. This will only be called if didBeginBISVisit: is also implemented by the delegate.
Note: This method will only be called if the didBeginBISVisit: has been implemented in the delegate. Also, the response on exit will be delayed by approximately 30 seconds after you no longer detect a beacons signal. This is due to an inherent timing system provided by Apple to eliminate false exit events.
- (void)didCompleteBISVisit:(BISVisit *)visit;
    
optional public func didCompleteBISVisit(visit: BISVisit)
    
Parameters
Name
Description

visit

Represents a visit to a region

Called when the API Key provided in the class method provideAPIKey: has finished authenticating.
- (void)apiKeyDidRegisterWithSuccess:(BOOL)success error:(NSError *__nullable)error
    
optional public func apiKeyDidRegisterWithSuccess(success: Bool, error: NSError?)
Parameters
Name
Description

success

Will equal YES if authentication was successful, otherwise NO

error

Will be nil when success is equal to YES, otherwise will contain an NSError describing why authentication failed

Properties

The <BeaconsInSpaceDelegate> method didBeginBISVisit: will only be called when proximity to the region is less than or equal to enterRegionProximityTrigger:. Defaults to BISProximityFar
@property (nonatomic) BISProximity enterRegionProximityTrigger;
    
public var enterRegionProximityTrigger: BISProximity
    
Parameters

Represents the current proximity of an entity.

typedef NS_ENUM(NSInteger, BISProximity) {
    BISProximityUnknown,
    BISProximityImmediate,
    BISProximityNear,
    BISProximityFar
}
    
public enum BISProximity : Int {
    case Unknown
    case Immediate
    case Near
    case Far
}
    
Name
Description

BISProximityImmediate

Represents a beacon who's RSSI is approximately 0.5 meters away.

BISProximityNear

Represents a beacon who's RSSI is approximately 5 meters away.

BISProximityFar

Represents a beacon who's RSSI is approximately 50 meters away.

BISProximityUnknown

Represents a beacon who's RSSI is no longer detected.

The current BISRegions detected encapsulated in BISVisit objects, which provide the time entered and the total duration of the visit
@property (nonatomic, strong, readonly) NSArray <BISVisit *> *currentVisits;
    
public var currentVisits: [BISVisit] { get }
    

BISRegion Class Reference

Represents a particular physical region. A BISRegion encapsulates information about a physical place including the establishment name, latitude, longitude, and any other information we have available. This class is immutable.

Methods

Returns the distance between two regions’ latitude and longitude measured in the specified units.
- (float)distanceToBISRegion:(BISRegion *)region withDistanceUnit:(BISDistanceUnit)unit;
    
public func distanceToBISRegion(region: BISRegion, withDistanceUnit unit: BISDistanceUnit) -> Float
    
Parameters

BISDistanceUnit represents a unit measurement for calculations relating to distance. The BISDistanceUnit defaults to BISDistanceUnitKilometers.

typedef NS_ENUM(NSInteger, BISDistanceUnit ) {
   BISDistanceUnitFeet,
   BISDistanceUnitMeters,
   BISDistanceUnitKilometers,
   BISDistanceUnitMiles,
};
    
public enum BISDistanceUnit : Int {
    case Feet
    case Meters
    case Kilometers
    case Miles
}
    
Name
Description

region

The region to be compared against.

unit

The unit of measurement for the distance calculation set through the enum BISDistanceUnit

BISDistanceUnitFeet

Represents the imperial unit of length "ft"

BISDistanceUnitMeters

Represents the metric unit of length "m"

BISDistanceUnitKilometers

Represents the metric unit of length "km"

BISDistanceUnitMiles

Represents the imperial unit of length "mile"

Returns the distance between a BISRegion instance and a CLLocation object in the specified units
- (double)distanceToCLLocation:(CLLocation *)location withDistanceUnit:(BISDistanceUnit)unit
    
public func distanceToCLLocation(location: CLLocation, withDistanceUnit unit: BISDistanceUnit) -> Double
    
Parameters

BISDistanceUnit represents a unit measurement for calculations relating to distance. The BISDistanceUnit defaults to BISDistanceUnitKilometers.

typedef NS_ENUM(NSInteger, BISDistanceUnit ) {
   BISDistanceUnitFeet,
   BISDistanceUnitMeters,
   BISDistanceUnitKilometers,
   BISDistanceUnitMiles,
};
    
public enum BISDistanceUnit : Int {
    case Feet
    case Meters
    case Kilometers
    case Miles
}
    
Name
Description

location

The location to be compared against

unit

The unit of measurement for the distance calculation set through the enum BISDistanceUnit

BISDistanceUnitFeet

Represents the imperial unit of length "ft"

BISDistanceUnitMeters

Represents the metric unit of length "m"

BISDistanceUnitKilometers

Represents the metric unit of length "km"

BISDistanceUnitMiles

Represents the imperial unit of length "mile"

Get the capsules that exist for this region
- (void)capsules:(void ( ^ ) ( NSArray<BISCapsule*> *capsules , NSError *__nullable error ))completion
    
public func capsules(completion: ([BISCapsule], NSError?) -> Void)
    
Parameters
Name
Description

completion

Returns an array of BISCapsules or an error

Properties

Name
Type
Description

beaconId

NSString

The Id of the beacon region

city

NSString

The city of the region

country

NSString

The country of the region

establishment

NSString

The name of the establishment where the region is located

establishmentType

NSString

The type of establishment where the region is located

latitude

float

The latitude of the region

longitude

float

The longitude of the region

state

NSString

The state/province of the region

street

NSString

The street address of the region

timezone

NSTimeZone

The time zone of the region

touchpoint

NSString

The area where the beacon is placed inside the establishment

touchpointType

NSArray <NSString *>

An NSArray of NSStrings that classify the region's touchpoint ordered with increasing granularity

verticalPosition

NSString

The floor of the region

zip

NSString

The zip/postal code of the region

BISCapsule Class Reference

BISCapsule provides a simple interface for augmenting places in the real world with custom information. A capsule can be set to one or many regions through the regionDescription property.

Methods

The data to be stored in this capsule
- (instancetype)initWithData:(NSString *)data regionDescription:(BISRegionDescription *)regionDescription;
    
public init(data: String, regionDescription: BISRegionDescription)
    
Parameters
Name
Description

data

The data to be stored in this capsule

regionDescription

The description of the region(s) this capsule is set to

Add a new capsule to the server, or update an existing capsule if any properties have changed since the updatedDate
- (void)updateWithCompletion:(void ( ^ ) ( BOOL success , NSError *__nullable error ))completion
public func updateWithCompletion(completion: (Bool, NSError?) -> Void)
    
Parameters
Name
Description

completion

Block that returns a BOOL indicating success or failure. If failure, error will describe what went wrong

Delete this BISCapsule object permanently
- (void)deleteWithCompletion:(void ( ^ ) ( BOOL success , NSError *__nullable error ))completion
    
public func deleteWithCompletion(completion: (Bool, NSError?) -> Void)
    
Parameters
Name
Description

completion

Block that returns a BOOL indicating success or failure. If failure, error will describe what went wrong

Properties

Name
Type
Description

capsuleId

NSString

Unique identifier string for this capsule. If this is nil, this capsule does not exist on the server.

creationDate

NSDate

UTC date that this capsule was created on the server. If this is nil, this capsule does not exist on the server.

data

NSString

The data to be stored in this capsule. This must be set before calling updateWithCompletion:

regionDescription

BISRegionDescription

The description of the region(s) this capsule is set to. This must be set before calling updateWithCompletion:

updatedDate

NSDate

UTC date of the most recent update to this capsule on the server. If this is nil, this capsule does not exist on the server.

The type of data contained in this capsule specified by the BISCapsuleDataType Enum. When this is equal to BISCapsuleDataTypeUnknown, updateWithCompletion: will return an error.

@property (nonatomic, readonly) BISCapsuleDataType dataType
    
public var dataType: BISCapsuleDataType { get }
    
Parameters
BISCapsuleDataType values represent the possible data types that can be contained in a BISCapsule object
typedef NS_ENUM(NSInteger, BISCapsuleDataType ) {
   BISCapsuleDataTypeUnknown,
   BISCapsuleDataTypeJSON,
   BISCapsuleDataTypeText,
   BISCapsuleDataTypeURL,
   BISCapsuleDataTypeXML,
};
    
public enum BISCapsuleDataType : Int {
    /** Represents null or malformed data*/
    case Unknown
    /** Represents data in JSON format*/
    case JSON
    /** Represents data in plain text format*/
    case Text
    /** Represents data formatted as a URL*/
    case URL
    /** Represents data in XML format*/
    case XML
}
    
Name
Description

BISCapsuleDataTypeUnknown

Represents null or malformed data

BISCapsuleDataTypeJSON

Represents data in JSON format

BISCapsuleDataTypeText

Represents data in plain text format

BISCapsuleDataTypeURL

Represents data formatted as a URL

BISCapsuleDataTypeXML

Represents data in XML format

BISRegionDescription Class Reference

Represents a description of a geographical region(s).

Methods

Returns a BISRegionDescription object whose properties all match the provided BISRegion’s corresponding properties
- (instancetype)initWithRegion:(BISRegion *)region
    
public init(region: BISRegion)
    
Parameters
Name
Description

region

The region that this object will describe

Properties

Name
Type
Description

city

NSString

The city of the region(s)

country

NSString

The country of the region(s)

establishment

NSString

The name of the establishment(s) where the region(s) can be located

establishmentType

NSString

The type of establishment where the region(s) can be located

state

NSString

The state/province of the region(s)

street

NSString

The street address of the region(s)

touchpoint

NSString

The placement of the beacon(s) within the establishment(s)

verticalPosition

NSString

The floor of the region(s)

zip

NSString

The zip/postal code of the region(s)

BISVisit Class Reference

Represents a visit to a specific region at a specific time, with duration. This class is immutable.

Properties

Name
Type
Description

region

BISRegion

The region being visited

startDate

NSDate

The date when the visit began

duration

NSTimeInterval

The duration of the visit in seconds

Your AppDelegate

In your application:didFinishLaunchingWithOptions: method, don't forget to replace @“YOUR_API_KEY" with your API Key.

#import "BISAppDelegate.h"
@import BeaconsInSpace
#import "BISViewController.h"

@interface BISAppDelegate () @property (nonatomic, strong) UINavigationController *navigationController; @end
@implementation BISAppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { BISViewController *viewController = [[BISViewController alloc] init]; self.navigationController = [[UINavigationController alloc] initWithRootViewController:viewController]; self.window = [UIWindow new]; [self.window makeKeyAndVisible]; self.window.frame = [[UIScreen mainScreen] bounds]; self.window.rootViewController = self.navigationController; // Override point for customization after application launch. [BeaconsInSpace provideAPIKey:@"YOUR_KEY_HERE"]; return YES; }
import UIKit
import BeaconsInSpace

@UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool { // Override point for customization after application launch. BeaconsInSpace.provideAPIKey("YOUR_API_KEY") return true }

Your Info.plist file

In order to use location services, go to the info.plist and put in the Key "NSLocationAlwaysUsageDescription", and for the String Value enter the message you'd like to display to users when asking for their location.

The BeaconsInSpace beaconManager will handle asking for permission once this is set.

<key>NSLocationAlwaysUsageDescription</key> <string>Enter your custom message to request location access</string>
    

Your View Controller

The following code will return the establishment when you enter and exit your beacons regions.

#import "BISViewController.h"
@import BeaconsInSpace

@interface BISViewController () <BeaconsInSpaceDelegate>
@end
@implementation BISViewController
- (void)viewDidLoad { [super viewDidLoad]; // Do any additional setup after loading the view, typically from a nib. [[BeaconsInSpace beaconManager] addDelegate:self]; }
- (void)didReceiveMemoryWarning { [super didReceiveMemoryWarning]; // Dispose of any resources that can be recreated. }
- (void)didBeginBISVisit:(BISVisit *)visit { NSLog(@"Visit to %@ began", visit.region.establishment); }
- (void)didCompleteBISVisit:(BISVisit *)visit { NSLog(@"Visit to %@ completed after %.02f seconds", visit.region.establishment, visit.duration); }
import UIKit
import BeaconsInSpace

class ViewController: UIViewController, BeaconsInSpaceDelegate {
override func viewDidLoad() { super.viewDidLoad() // Do any additional setup after loading the view, typically from a nib.
BeaconsInSpace.beaconManager().add(self)
} override func didReceiveMemoryWarning() { super.didReceiveMemoryWarning() // Dispose of any resources that can be recreated. } func didBeginBISVisit(visit: BISVisit) { NSLog("Visit to %@ began", visit.region.establishment) } func didCompleteBISVisit(visit: BISVisit) { NSLog("Visit to %@ completed after %.02f seconds", visit.region.establishment, visit.duration) } }

Android SDK Overview

The BeaconsInSpace SDK for Android makes it easy for you to start earning revenue from our beacon network.

At its core, the SDK does the following:
Automatically establishes full beacon detection functionality
Provides your app with access to all beacons in the BeaconsInSpace network
Automatically posts enter and exit events to generate data, analytics, and enable third-party integrations

Add BeaconsInSpace to your Android app

The guide below will get you setup with full functionality in 5 minutes.

1. Get setup

Here's what you'll need before installing the SDK:
Your API Key.
Signup for a free account to get your API Key in Mission Control.
1 mobile device with Android 15+.
1 computer running Android Studio or equivalent development environment.

2. jCenter or Direct AAR install

Below are the instructions to use jCenter to add the SDK to our project. If you would like to install the AAR, see below.

To install jCenter, first we need to make sure that jCenter is added as a repository resource:

repositories {
    jcenter()
}
    

Then, we'll add the library to our list of dependencies:

dependencies {
    ...
    compile 'com.beaconsinspace.android.beacon:detector:1.3.9'
    ...
}
    

To install the AAR manually: Import the AAR into your project, reference it in your build.gradle, and add the following list of dependencies below. Note, these dependencies are only required if installing AAR manually, and are not needed if compiling from jCenter import.

Note: If you prefer to use a different version of google play services, that is fine so long as it supports and includes the play-services-ads module.

dependencies {
    ...
    compile 'org.altbeacon:android-beacon-library:2.9.2'
    compile 'com.google.android.gms:play-services-ads:10.0.1'
    compile (
	            [group: 'com.fasterxml.jackson.core', name: 'jackson-core', version: '2.4.1'],
	            [group: 'com.fasterxml.jackson.core', name: 'jackson-annotations', version: '2.4.1'],
	            [group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.4.1']
    	)
    ...
}
    

3. Verify Location Permissions

In Android 6.0+ devices location permissions are required. BeaconsInSpace uses location to detect beacons.

Ensure the following imports are at the top of your Main Activity:

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Build;
import android.os.Bundle;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
    

Then place this code in the onCreate method:

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
{
    // Android M permission check
    if(ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
    {
        requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION}, 100);
    }
}
    

4. Bootstrap the SDK

Next, in the onCreate method, we’ll import the SDK and call the static configure method.

import com.beaconsinspace.android.beacon.detector.BISDetector;
    

In this example we are not using a delegate so the third parameter is null:

BISDetector.configure( "YOUR_API_KEY_HERE", getApplicationContext(), null );
    

5. You're Done!

In order to confirm that you have correctly implemented the SDK, you should view the development environment logs and look for "BeaconsInSpace has bootstrapped successfully.". If you see this line of text, you are all set and ready to submit!

Update Your Privacy Policy

Before going live, please update your privacy policy. Consult with your legal team, and include the following sample or something similar:

Sample: We share data we collect about you including unique identification numbers associated with mobile devices or through its API (including, for example, a Unique ID for Advertisers ("IDFA"), Unique ID for Vendors ("IDFV"), Google Ad ID, or Windows Advertising ID), mobile carrier, device processes, device type, model and manufacturer, mobile device operating system brand and model, battery life, and, depending on the user’s mobile device settings, the geographical location data, including GPS coordinates (e.g. latitude and/or longitude) or similar information regarding the location of the mobile device (“User Data”) with our third party partners, that enables us to provide you with information, advertisements, or offers specific to your location and interests.   

By accepting our terms of service, you consent to the collection, storage and processing of your data by our third party partners for the purposes of: (i) providing or improving their services; (ii) enabling third parties to assist us and the retailer and venues (in which the beacons are located) in better serving and understanding our users; and (iii) sharing your data with third parties so they can provide or enable the provision of content, offers or other marketing solutions that may be of interest to you. You also consent to having your data transferred to and processed in the United States or any other jurisdiction in which our third party partners or their parent, subsidiaries, affiliates, service providers or partners maintain facilities. If you do not consent to the collection and transfer of the aforementioned data through the identification of your mobile device, we recommend that you: (a) delete our app or adjust the in-app settings of the app; or (b) opt out of sharing your mobile advertiser ID by limiting ad tracking on the device. For iOS, navigate to your Settings > Select Privacy > Select Advertising > Enable the “Limit Ad Tracking” setting. For Android, open your Google Settings app > Ads > Enable “Opt out of interest-based advertising. For more information on specific opt-out choices, please visit: http://www.networkadvertising.org/mobile-choices.

Your Main Activity without the Delegate

Below is an example of your activity without the optional delegate added. Don't forget to replace “YOUR_API_KEY_HERE" with your API Key.

package com.beaconsinspace.android.beacon.demo;
import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Build;
import android.os.Bundle;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
import com.beaconsinspace.android.beacon.detector.BISDetector;
public class Main extends AppCompatActivity
{
    static private final String TAG = "MAIN_ACTIVITY";
    static private final int LOCATION_PERMISSION_REQUEST_CODE = 100;
    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        /*
         * Run parent
         */
        super.onCreate(savedInstanceState);
        /*
         * Set view
         */
        setContentView(R.layout.mainlayout);
        /*
         * Verify permissions
         */
        if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
        {
            // Android M permission check
            if(ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
            {
                requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION}, LOCATION_PERMISSION_REQUEST_CODE);
            }
        }
        /*
         * Bootstrap BeaconsInSpace Detector
         */
        BISDetector.configure( "YOUR_API_KEY_HERE", getApplicationContext(), null );
    }
}
    

Your Main Activity with the Delegate

Below is an example of your activity including the optional delegate. Don't forget to replace “YOUR_API_KEY_HERE" with your API Key.

We can use the error method to be notified when the SDK is unable to perform as expected. The below example also shows how an alert could be shown to the user to enable their bluetooth or location services:

package com.beaconsinspace.android.beacon.demo;
import android.Manifest;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.pm.PackageManager;
import android.os.Build;
import android.os.Bundle;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;
import com.beaconsinspace.android.beacon.detector.BISDetector;
import com.beaconsinspace.android.beacon.detector.BISDetectorDelegate;
public class Main extends AppCompatActivity implements BISDetectorDelegate
{
    static private final String TAG = "MAIN_ACTIVITY";
    static private final int LOCATION_PERMISSION_REQUEST_CODE = 100;
    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        /*
         * Run parent
         */
        super.onCreate(savedInstanceState);
        /*
         * Set view
         */
        setContentView(R.layout.mainlayout);
        /*
         * Verify permissions
         */
        if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
        {
            // Android M permission check
            if(ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
            {
                requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION}, LOCATION_PERMISSION_REQUEST_CODE);
            }
        }
        /*
         * Bootstrap BeaconsInSpace Detector
         */
        BISDetector.configure( "YOUR_API_KEY_HERE", getApplicationContext(), this );
    }
    /*
     * ENTER BEACON
     */
    @Override
    public void didEnterBISRegion(String beaconId)
    {
        Log.i( TAG, "ENTER BEACON FROM DELEGATE: "+ beaconId );
    }
    /*
     * EXIT BEACON
     */
    @Override
    public void didExitBISRegion(String beaconId)
    {
        Log.i( TAG, "EXIT BEACON FROM DELEGATE: "+ beaconId );
    }
    /*
     * BIS EXCEPTION OCCURRED
     */
    @Override
    public void onBISError( int errorCode, String errorMessage )
    {
        Log.e( TAG, "BIS ERROR OCCURRED: "+ errorMessage );
        if ( errorCode == BISDetector.ERROR_CODE_DEPENDENCIES_DISABLED )
        {
            // Show alert to have user enable
            String enableAllServicesMessage = "Please enable bluetooth, location services, and ensure you are connected to the internet";
            try
            {
                AlertDialog.Builder dialog = new AlertDialog.Builder(this);
                dialog.setMessage( enableAllServicesMessage );
                dialog.setPositiveButton("OK", new DialogInterface.OnClickListener()
                {
                    @Override
                    public void onClick(DialogInterface paramDialogInterface, int paramInt)
                    {
                        // On OK button click
                    }
                });
                dialog.show();
            }
            catch( Exception e )
            {
                Log.e(TAG,"Failed to show alert: "+e.getMessage());
            }
        }
    }
}
    
Term
Definition
beaconId
A unique identifier for a beacon you are subscribed to. The beaconId is returned in every Beacon place details request.
capsule
The information in your Capsule. Data types: JSON, TEXT, XML, URL, or any string. Max size: 1kb (1024 bytes).
capsuleId
A unique identifier assigned to a Capsule when it is created.
city
The city of the establishment where the beacon is located.
country
The country of the establishment where the beacon is located.
dataType
Data type of capsule information (JSON, TEXT, XML, URL)
establishment
The name of the establishment in which the beacon is located.
establishmentType
The establishment classification. Examples include restaurant, school, and zoo.
instanceId
A 6 byte sub-identifier for the Eddystone.
latitude
The latitude where the beacon is located.
longitude
The longitude where the beacon is located.
major
A 2 byte identifier used to distinguish a subset of beacons within the larger network.
minor
A 2 byte identifier used to further distinguish a subset of beacons within the larger network.
namespaceId
A 10 byte standard identifier for the Eddystone.
protocol
The hardware protocol of the beacon.
state
The state of the establishment where the beacon is located.
street
The street address of the establishment where the beacon is located.
timezone
The timezone where the beacon is located.
touchpoint
Area where the beacon is located in a particular establishment. e.g. "Front Door", "Room 202"
touchpointType
The category classification describing the beacons placement. e.g. "Asian Food", "Electronics"
uid
A 16 byte identifier for the Eddystone consisting of namespaceId + instanceId.
uuid
A 16 byte standard identifier used to differentiate networks of beacons.
verticalPosition
The floor of the establishment where the beacon is located. The main floor is always the floor where you enter the establishment.
zip
The zip code of the establishment where the beacon is located.

Questions & Feedback

We got your back!
support@beaconsinspace.com

We also recommend sending questions and feedback via the small chat bubble in the bottom right corner of this page. We usually get back to you within 30 minutes.

Community

Join our #Slack community and chat with us and your fellow community members live!

Security

Security is serious. We are committed to upholding the highest standards to ensure that your data and the applications you're building are secure.

If you have questions on our security protocols please contact us at security@beaconsinspace.com.