Documentation

Reveal Mobile provides a native mobile audience SDK that allows developers to provide targeted audiences to their ad network based on a user’s location, beacon interactions and installed applications.

Reveal Mobile requires an account with the Reveal system and a valid API key. Click here to sign up for an API key, and use sdk.revealmobile.com.

Reveal Mobile iOS SDK

(Version 1.3.18 published 03/24/17)

Version License

Reveal Mobile is a native mobile SDK that allows developers to provide tailored personas to their ad network based on a user’s location, beacon interactions and installed applications.

Swift NOTE: The prebuilt framework version does not support Swift due to legacy compatibility constraints. The easiest way to use the framework in Swift is to install from Cocoapods. We can provide pre-built framework versions supporting iOS 8+ only if Cocoapod installation is not suitable for your implementation.

A NOTE about our use of Background Modes: In order to detect iBeacons, we follow Apple’s documentation for UIBackgroundModes. In order to detect Eddystone beacons, which can’t use the iBeacon methods, we follow Apple’s documentation for using Bluetooth-central. Our customers use both iBeacon and Eddystone formats, so we must use both approaches. In order to save battery life, all Bluetooth related scanning is only turned on after all startup tasks are finished and then only in short intervals. We only use Bluetooth-central for beacon detection to tailor location-based content and advertising, and do not use it to connect to other Bluetooth devices.

Usage

Simple Setup

Objective-C

#import <Reveal/Reveal.h>
// Setup the Reveal Mobile SDK pointed at production with no debug features
Reveal *theSDK = [[Reveal sharedInstance] setupWithAPIKey:<YOUR API KEY>];
[theSDK start];

Swift

import Reveal
// Setup the SDK with your API key
Reveal.sharedInstance().setup( withAPIKey: "<YOUR API KEY>", andServiceType: .production )
// Setup the Reveal Mobile SDK pointed at production with no debug features
Reveal.sharedInstance().start()

Testing Setup

Objective-C

Reveal *theSDK = [[Reveal sharedInstance] setupWithAPIKey:<YOUR API KEY>];
// Turn on optional debug logging
theSDK.debug = YES;
// Setup a list of beacon UUID's for testing. This list will override the list from the server if set.
theSDK.debugUUIDs = @[ @"<YOUR BEACON UUID>"];
// Start the SDK. The SDK will contact the server for further config info
// and start monitoring for beacons.
[theSDK start];

Swift

import Reveal
// Turn on optional debug logging
Reveal.sharedInstance().debug = true
// Setup the SDK with your API key
Reveal.sharedInstance().setup( withAPIKey: "<YOUR API KEY>", andServiceType: .production )
// Setup the Reveal Mobile SDK pointed at production with no debug features
Reveal.sharedInstance().start()

Background transmission of beacons

To sending beacon bumps while the app is in background, enable the background fetch capability and add the following to your App delegate file:

Objective-C

- (void) application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[[Reveal sharedInstance] backgroundFetchWithCompletionHandler: completionHandler];
}

Swift

func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
{
Reveal.sharedInstance().backgroundFetchWithCompletionHandler( completionHandler );
}

Accessing the Personas

Objective-C

// Get personas to send to ad network. Personas array is an array of NSString* objects.
NSArray* personas = [Reveal sharedInstance].personas

Swift

// Get personas to send to ad network. Personas array is an array of NSString* objects.
var result = Reveal.sharedInstance().personas

Accessing the personas is a lightweight call to the SDK that does not involve a network request. You should call for personas everytime you build an ad view in order to get the most current available list of personas.

DFP Integration

If using DoubleClick (DFP), ensure these personas pass to the “reveal” custom targeting key in DFP as a custom parameter. Reveal Mobile will work with your ad trafficking team to create the custom targeting key in DFP. Below is sample code you can insert into your ad call to DFP. Please, make sure you revise this code sample to fit your existing ad call! For additional reference beyond the sample code, refer to Google’s documentation on custom targeting.

GADAdSize adsize = GADAdSizeFromCGSize(CGSizeMake(300, 250));
DFPBannerView* ad = [[DFPBannerView alloc] initWithAdSize:adsize];
GADRequest* request = [GADRequest request];
// get Reveal personas and add to AdNetworkExtras
GADExtras *extras = [[[GADExtras alloc] init] autorelease];
NSMutableDictionary *additionalParameters = [[[NSMutableDictionary alloc] init] autorelease];
NSArray* personas = [Reveal sharedInstance].personas;
NSString *persona_list = [personas componentsJoinedByString:@","];
[additionalParameters setObject:persona_list forKey:@"reveal"];
extras.additionalParameters = additionalParameters;
[request registerAdNetworkExtras:extras];
// get Location and add to request
CGFloat lat;
CGFloat lon;
CGFloat accuracy;
// populate these variables with the location information from CoreLocation, 
// then call setLocationWithLatitude:longitude:accuracy:
[request setLocationWithLatitude:lat longitude:lon accuracy:accuracy];
// make the request
[ad loadRequest:request];

Capturing app openings

Reveal Mobile sends information about the user location on each time the application becomes active. This is done using the following code in the applicationDidBecomeActive: function in your AppDelegate

Objective-C

// Send current information to the Reveal servers
[[Reveal sharedInstance] restart];

Swift

// Send current information to the Reveal servers
Reveal.sharedInstance().restart()

Project setup

Since Reveal Mobile monitors your users’ locations, it is important to communicate clearly to the end user why your application asks for their location. We suggest setting the following values in your Info.plist file. You are free to change the wording, ours is only a suggestion. The first key is for iOS 8.0 support and the latter is for legacy systems.

Key Value
NSLocationAlwaysUsageDescription We use your device’s location to tailor content and advertising within the app.
Privacy – Location Usage Description We use your device’s location to tailor content and advertising within the app.

You will also need to add Apple’s Core location and Core Bluetooth frameworks to your project and select the “Uses Bluetooth LE accessories” option under the background modes capability.

To support background notification of beacons, you will also need to enable the “Background fetch” fetch capability.

Requirements

Reveal Mobile requires at least iOS 7.0 to run. Beacon scanning requires a Bluetooth LE capable device to operate.

For beacon scanning to function correctly in iOS, Apple requires the “Always” location permission. Apple built beacon scanning directly into the operating system, which allows beacon detection to occur while the app is in the background and not currently open. Using the “While Using the App” setting for location permission isn’t sufficient for beacon detection. You must add the “Always” permission, and we recommend this be the default location permission requested.

For reference, here is Apple’s documentation on beacon scanning. Here’s where Apple discusses using Location Services in the background, with the relevant text copied below.

Using Location Services in the Background:

Most location services are meant to be used while your app is in the foreground but some can also run in the background. In some cases, location events can even cause your app to be relaunched to process an event. To run most location services in the background, you need to enable the location updates background mode in the Capabilities tab of your Xcode project. For services that launch your app, you need to request (and be granted) “Always” authorization from the user.

Reveal Mobile requires an account with our system and a valid API key. You may request a production key from the Reveal Mobile team at support@revealmobile.com.

Installation

Simple Integration

Reveal Mobile is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "Reveal"

Manual Integration

Reveal Mobile can be added as a framework. First, download the iOS Framework here. After adding Reveal.framework to your project, you need to link your project against the following system frameworks (CoreLocation, CoreBluetooth, AdSupport).

Authors

License

Reveal Mobile is available under the MIT license. See the LICENSE file for more info.

Version Log

1.3.18 – 03.24.17 – Improved beacon data and GPS data collection including dwell time

1.3.15 – 1.3.17 – Internal Testing releases

1.3.14 – 02.20.17 – Improved permissions control

1.3.13 – 01.27.17 – additional Wifi functionality added

1.3.12 – 01.05.17 – Greater control over operating with background permissions

1.3.11 – 12.22.16 – Standardize beacon data collection

1.3.10 – 12.06.16 – Support for Swift and batch events

1.3.9 – 09.28.16 – Hot fix for non-critical iOS 10 warning

1.3.8 – 09.27.16 – Support for iOS 10

1.3.7 – Internal testing release

1.3.6 – 07.27.16 – Improved beacon detection. Make location timeouts configurable via server.

1.2.30 – 01.3.5 – Internal testing releases

1.2.29 – 05.23.16 – Fixed bug with iOS 7.1 support and Titanium app developers

1.2.28 – 04.27.16 – Restored connection type and UUID parameters to response

1.2.27 – 04.26.16 – Fixed issue with returning beacon bumps in background

1.2.26 – 04.24.16 – Fixed intermittent location issues on startup

1.2.25 – 04.21.16 – Synced iOS and Android handling of securecast codes

1.2.24 – 04.19.16 – Fixed startup location retrieval

1.2.23 – 04.18.16 – Fixed Cocoapod warnings

1.2.21-.22 – Internal testing

1.2.20, 04.09.16 – Additional support for securecast beacons

1.2.18-.19 – Testing

1.2.16 -.17 – 03.29.16 – Support for securecast beacons and BuddyBuild

1.2.15 – Internal testing

1.2.14, 03.22.16 – Fixes intermittent crashes when using stopRangingBeaconsInRegion

1.2.10 – 01.2.13 – Internal testing to rebuild CocoaPods integration

1.2.9, 02.25.16 – Bug fix for location permissions

1.2.8, 02.18.16 – Detect additional beacon types and classes

1.2.7, 02.11.16 – Eddystone beacon detection, normalize iOS & Android data

1.2.6, 01.22.16 – Improving beacon detection with location permissions

1.2.3, 12.17.15 – Additional controls around location permissions

1.2.2, 12.15.15 – Adding caching of personas, improved server communication, match version with Android

1.1.8, 08.13.15 – Updated location fetching away from significant changes only and to a more finely grained query

1.1.7, 08.03.15 – Added controls to support scanning for beacons independent of other app functions

1.1.6, 06.02.15. Updated support for app installation evaluation

1.1.5, 05.09.15. Improved battery life

Reveal Mobile Android SDK

(Version 1.3.21 published 03/24/17)

Reveal Mobile is a native mobile SDK that allows developers to provide tailored personas to their ad network based on a user’s location, beacon interactions and device details.

Usage

The Reveal Mobile setup should happen only once when the application launches. You need to subclass android.app.Application (adding the appropriate AndroidManifest.xml information to use your subclass) and adding your code in the onCreate() method.

Simple Setup

public class BaseApplication extends Application {
...
@Override
public void onCreate() {
    super.onCreate();

    // Setup the Reveal Mobile SDK pointed at production with no debug features
    Reveal reveal = Reveal.getInstance();
    reveal.setAPIKey("<YOUR API KEY>");

    //Start Reveal Mobile service. This will start start discovering beacons.  The Reveal Mobile SDK requires you to pass in the Application variable to receive boot loading broadcasts
    reveal.start(this);
    ...
}

Accessing the Personas

In order for your app to deliver ads using Reveal Mobile audience data, you must pass the personas to your ad server.

// Get personas to send to ad network.  Personas array is an array of String objects.
List<String> personas = Reveal.getInstance().getPersonas();

Accessing the personas is a lightweight call to the SDK that does not involve a network request. You should call it to get the most current available list of personas every time you build an ad view.

DFP Integration

If using DoubleClick (DFP), ensure the personas pass to the “reveal” custom targeting key in DFP as a custom parameter. Reveal Mobile will work with your ad trafficking team to create the custom targeting key in DFP. Below is sample code you can insert into your ad call to DFP. Please, make sure you revise this code sample to fit your existing ad call! Here’s Google’s documentation to help out.

import com.google.android.gms.ads.mediation.admob.AdMobExtras;

AdView adview = new AdView(activity);
adview.setAdSize(size);
adview.setAdUnitId(unit);

adview.setLayoutParams(new FrameLayout.LayoutParams(LayoutParams.MATCH_PARENT, size.getHeightInPixels(activity)));

AdRequest.Builder ab = new AdRequest.Builder();

// add reveal
String revealApiKey = activity.getString(R.string.revealApiKey);
if (revealApiKey != null && revealApiKey.length() > 0) {
    List<String> personas = Reveal.getInstance().getPersonas();

    Bundle b = new Bundle();
    b.putString ("reveal", StringUtils.join(personas, ","));

    ab.addNetworkExtras(new AdMobExtras(b));
}

// add location
double lat;
double lon;
float accuracy;

// populate lat, lon, accuracy with location information from the system

Location loc = new Location ("");
loc.setLatitude(lat);
loc.setLongitude(lon);
loc.setAccuracy(accuracy);

ab.setLocation (loc);

AdRequest adrequest = ab.build();
adview.loadAd(adrequest);

Capturing app openings

Reveal Mobile sends information about the user location each time the application comes back from the background. This is difficult on the Android platform due to Activities being tracked independently.  In order to properly determine if an android app is in the foreground we recommend you use a library such as Foredroid. Or if you would prefer to create your own solution, this link may be helpful.

Once you have the proper recognition of the application coming back from the background, add the following code to your function that is called when the application comes back on screen.

// Send current information to the Reveal servers.  
Reveal.getInstance().restart(getApplicationContext());

Independent Beacon Scanning

Should your usage of the SDK require disabling of beacon detection, the appropriate flag to set to false is:

setIsBeaconScanningEnabled

If your usage of the SDK requires the ability to disable beacon detection while the app is in the background, the appropriate flag to set to false is:

setIsBackgroundScanningEnabled

Project setup/Installation

Reveal Mobile can be setup automatically using our Maven dependency or manually using our downloadable dependency.  The following sections will go through these methods.

Setup via Maven/Gradle

Add the following dependencies to your application module’s gradle file (if not already present):

dependencies {   
compile 'com.stepleaderdigital.reveal:reveal:+@aar'  
compile 'com.android.support:appcompat-v7:+'   
compile 'com.google.android.gms:play-services-location:+'   
compile 'org.altbeacon:android-beacon-library:2.8.1' 
}

Manual Setup

Reveal Mobile is available as an Android .jar file. Place this .jar file in your libs directory and then follow the instructions below. If you are not using Maven Central or a similar dependency repository, you need to add this AltBeacon .jar file along with the Google Play service and app compatibility libraries mentioned below to your libs directory.

If you are using the manual integration, then you will need to add these entries to your application module’s Manifest for beacon scanning to occur.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission-sdk-23 android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Android suggests putting this in the manifest even though false is the default value -->

<uses-feature android:name="android.hardware.bluetooth_le" android:required="false"/>

<application>
        <receiver android:name="org.altbeacon.beacon.startup.StartupBroadcastReceiver" >
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
                <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
                <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
            </intent-filter>
        </receiver>
        <service
            android:name="org.altbeacon.beacon.service.BeaconService"
            android:enabled="true"
            android:exported="false"
            android:isolatedProcess="false"
            android:label="beacon" />
        <service
            android:name="org.altbeacon.beacon.BeaconIntentProcessor"
            android:enabled="true"
            android:exported="false" />
    </application>

Location Permission Requests (Targeting SDK > 23 only)

In apps targeting Android SDK level 23 and above (6.0+), developers must explicitly request permissions from the user that Android deems “dangerous”, such as location. Since the Reveal SDK requires the “ACCESS_FINE_LOCATION” permission, implementers targeting SDK level 23+ must request this permission from the end users before the Reveal SDK can properly function. We suggest following Android’s guide to request permissions and handle the results here: http://developer.android.com/training/permissions/requesting.html. The Reveal SDK will function if location access is denied, but it will not be able to determine the information needed to make a profile of the user for ad targeting.

Requirements

Reveal Mobile requires at least Android 4.3 to run. Beacon scanning requires a Bluetooth LE capable device to operate.

Authors

License

Reveal Mobile is available under the MIT license. See the LICENSE file for more info.

Version Log

  • 1.3.21 – Improved beacon and GPS data collection including dwell time
  • 1.3.20 – Internal testing
  • 1.3.19 – 02.28.17 – Support for Google Play Services 10 and above
  • 1.3.15 – 18 – Internal testing
  • 1.3.14 – 02.07.17 – Quick fix for intermittent crash when wifi switching between routers
  • 1.3.13 – 02.06.17 – Additional WiFi functionality added
  • 1.3.12 – 12.29.16 – Fix non-fatal crashes
  • 1.3.11 – 12.22.16 – Standardize beacon data and fix non-fatal crashes
  • 1.3.10 – Internal Testing
  • 1.3.9 – 12.06.16 – Collect batch events
  • 1.3.8 – Internal Testing
  • 1.3.7 – 11.09.16 – fixed sdk_version returning empty on API calls
  • 1.3.6 – 11.03.16 – Improved beacon scanning
  • 1.3.5 – 08.16.16 – Handle location permission exception on Android 6+ devices
  • 1.3.4 – 08.12.16 – Support for new beacon types
  • 1.3.3 – 08.10.16 – Fixed issue on loadFoundBeacons and issue on double decode
  • 1.3.2 – 08.03.16 – Fixed environmental variable issue
  • 1.3.1 – 07.27.16 – Improved beacon detection. Make location timeouts configurable via server.
  • 1.3.0 – Internal testing
  • 1.2.20 – 06.03.16 – Support for different background scanning modes
  • 1.2.19 – 05.13.16 – Pass SDK version in info request
  • 1.2.18 – 04.28.16 – Updated Google Play Services 8.4.0 and Android 6.0 permissions
  • 1.2.17 – 04.19.16 – Fixed beacon aging issue
  • 1.2.16 – 04.18.16 – Additional support for securecast beacon scanning
  • 1.2.15 – Internal testing
  • 1.2.14, 04.10.16 – Additional support for securecast beacon scanning
  • 1.2.11-1.2.13 – Testing releases
  • 1.2.10, 03.24.16 – Detect additional beacon types to improve monetization
  • 1.2.9 – Version testing, not an official release
  • 1.2.8 – 02.11.16 – Normalized data between iOS & Android, detect additional beacon types
  • 1.2.7 – 01.21.16 – Resolved location conflict with Google Play Services and beacon bumps
  • 1.2.5 & 1.2.6 – Internal versions for testing
  • 1.2.4 – 12.30.15 – Removed unnecessary permissions
  • 1.2.3 – 12.17.15 – Fixed bug with background beacon scanning
  • 1.2.2 – 12.15.15 – Added persona caching, improved server communication, Eddystone support
  • 1.2.1 – 11.12.15 – Improved stability of SDK when ranging for beacon transmission values
  • 1.1.10 – 10.02.15 – Backwards compatability for older Android API version support
  • 1.1.9 – 09.05.15 – Updated advertiser ID routine
  • 1.1.8 – 08.25.15 – Additional flags included to support independent scanning of beacons and apps
  • 1.1.7 – 08.03.15 – Added controls to support scanning for beacons and apps independently
  • 1.1.3 – 06.15.15 – Improved support for Titanium developers to recognize different classes of app startups
  • 1.1.2 – 06.02.15 – Support for AltBeacon standard
  • 1.1.1 – 02.11.15 – Improved beacon scanning and battery life

Update Your Privacy Policy

Per industry best practices, please update your privacy policy after deploying the Reveal Mobile SDK. Include the following language, or something similar after consulting with your legal team, in the relevant section of your privacy policy, which should link directly to Reveal Mobile’s privacy policy:

Our mobile app makes use of 3rd-party services to collect anonymous mobile data in order to serve more relevant advertisements. If you wish to understand more about what data is collected and why, or to opt-out, please visit this site.

Disclaimer: The use of software made available on this website is done at your own discretion and risk and with agreement that you will be solely responsible for any damage to your computer system or loss of data that results from such software. You are solely responsible for adequate protection and backup of the data and equipment used in connection with any of the software obtained from this website, and we will not be liable for any damages that you may suffer in connection with downloading, installing, using, modifying or distributing such software. No advice or information, whether oral or written, obtained by you from us or from this website shall create any warranty for the software.