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 your users' location data points.

At its core, the SDK does the following:
Automatically detects location coordinates
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 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 foreground and 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 "NSLocationAlwaysAndWhenInUseUsageDescription" and "NSLocationWhenInUseUsageDescription", and for the String Values 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>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key> <string>Enter your custom message to request location access</string>
<key>NSLocationWhenInUseUsageDescription</key> <string>Enter your custom message to request location access</string>

5. 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 6.

6. 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.

7. 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 to the below:

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, device name, 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.

Android SDK Overview

The BeaconsInSpace SDK for Android makes it easy for you to start earning revenue from your users' location data points.

At its core, the SDK does the following:
Automatically detects location coordinates
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. Add 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.5'
    ...
}
    

To install the AAR manually: Import the AAR into your project, reference it in your build.gradle, and add the following list of dependencies:

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 to the below:

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, device name, 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());
            }
        }
    }
}
    

Questions & Feedback

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.