For Developers

Documentation

The Visit SDK allows developers to provide targeted & opted-in audiences to their ad network based on opted-in location data.

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

If you’re a publisher with users inside the European Union, we recommend evaluating the IAB’s Transparency and Consent Framework as a solution to appropriately receive consent for data sharing from EU users.


 

Reveal Mobile iOS SDK

Version 1.3.39 published 03/21/18

Version License

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 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:];
// Allow the SDK to request location permission for you on start, otherwise it defaults to waiting for you to request permission in your app
[theSDK setCanRequestLocationPermission: YES];
[theSDK start];

 

Swift

import Reveal
// Setup the SDK with your API key
Reveal.sharedInstance().setup( withAPIKey: "", andServiceType: .production )
// Allow the SDK to request location permission for you on start, otherwise it defaults to waiting for you to request permission in your app
Reveal.sharedInstance().canRequestLocationPermission = true
// Setup the Reveal Mobile SDK pointed at production with no debug features
Reveal.sharedInstance().start()

Testing Setup

Objective-C

Reveal *theSDK = [[Reveal sharedInstance] setupWithAPIKey:];
// 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 = @[ @""];
// Allow the SDK to request location permission for you on start, otherwise it defaults to waiting for you to request permission in your app
[theSDK setCanRequestLocationPermission: YES];

// 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: "", andServiceType: .production )
// Allow the SDK to request location permission for you on start, otherwise it defaults to waiting for you to request permission in your app
Reveal.sharedInstance().canRequestLocationPermission = true
// Setup the Reveal Mobile SDK pointed at production with no debug features
Reveal.sharedInstance().start()

Background Transmission of Beacons

To send 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

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.

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

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];

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 8.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. We recommend adding the “Always” permission when the use case for your mobile app supports this permission.

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

If your project has Bitcode enabled (which is mandatory on tvOS and iOS), then you need to add a new Run Script build phase to your target with the following script:

“$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/Reveal.framework/fix-framework.sh”

Make sure this script is run after the existing Embed Frameworks build phase.

Calling this script is required for your App Store submissions to pass validation when using Bitcode. While optional for non-Bitcode submissions, you may still add this script as it will somewhat reduce the size of the framework embedded in your app.

Additional Information

Authors

 

License

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

 

Version Log

1.3.39 – 03.21.2018 – Handling exception on case of in-place update of framework when older events are present in the stored archive of past state

1.3.38 – 01.16.2018 – Adoption of new framework building procedure. Changed minimum requirements to only support iOS8+. Bug fix for Titanium products.

1.3.37 – Internal Testing

1.3.36 – 11.10.2017 – Limit transmission of SSID and BSSID

1.3.32 – 1.3.35 – Internal Testing

1.3.31 –  08.23.2017 – Continued improvements on version 1.3.28

1.3.29 – 1.3.30 – Internal Testing

1.3.28 – 08.22.2017 – Cease sending of all device data if location sharing disabled by end user

1.3.27 – 07.14.2017 – Hot fix for location permission request feature

1.3.26 – 07.13.2017 – Changed permission configurations and added flag to support the old behavior

1.3.24-25 – Internal Testing

1.3.23 – 05.31.2017 – Set up of configurable API endpoint

1.3.22 – 05.18.2017 – Fix for improved beacon reporting

1.3.21 – 05.16.2017 – Fix to return correct SDK version in server request

1.3.20 – 05.09.2017 – Improved ability for beacon detection

1.3.19 – Internal testing

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.4.22 published 07/30/18

Usage

Simple Setup

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.

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("");

    //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 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 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);

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 'com.google.android.gms:play-services-ads:+'
}

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 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.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" />
<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" />

<!-- 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="com.stepleaderdigital.reveal.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:enabled="true"
   android:exported="false"
   android:isolatedProcess="false"
   android:label="beacon"
   android:name="com.stepleaderdigital.reveal.BeaconService"
   />

<service android:name="com.stepleaderdigital.reveal.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 Mobile SDK requires the “ACCESS_FINE_LOCATION” permission, implementers targeting SDK level 23+ must request this permission from the end users before the Reveal Mobile 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.

Requirements

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

Additional Information

Authors

License

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

Version Log

1.4.22 – 07.30.2018 – Updating dependencies for Google Play and SDK build version to 26

1.4.21 – 03.07.2018 – Bug fix for intermittent issues

1.4.20 – 01.25.2018 – Code simplifications and fix for specific Samsung devices’ Bluetooth access

1.4.19 – Fix to update batch sending routine on timeout

1.4.18 – Rely upon app settings to determine when to request location

1.4.12 – 1.4.17 – Internal Testing

1.4.11 – 09.15.2017 – Fix crash occurring in certain instances

1.4.9 – 1.4.10 – Internal testing

1.4.8 – 08.25.17 – Cease sending of all device data if location sharing disabled by end user

1.4.7 – Internal testing

1.4.6 – 08.01.17 – Improved crash reporting

1.4.5 – Bug fixes & remote logging capability

1.4.4 – Collect additional device statistics

1.4.3 – 07.18.17 – Handle Android doze mode

1.4.2 – 07.14.17 – Removal of AltBeacon dependency for beacon scanning, and changes to storing of IDFA/AdID

1.4.0-1 – Internal testing

1.3.31 – 06.16.17 – Hot fix for bug with background activity restarting

1.3.27-1.3.30 – Internal testing

1.3.26 – 05.18.17 – Fix for improved beacon reporting

1.3.25 – Fix for Knox security exception

1.3.23 – 24 – Internal Testing

1.3.22 – Fixed crash related to Parcel

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 compatibility 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 opted-in mobile data in order to serve more relevant advertisements, known as interest-based advertising. 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.