Welcome to the NewAer Proximity Platform SDK for Apple Devices

This SDK allows developers to trigger application behaviors based upon a smartphone, tablet, laptop, or desktop machine having physical interactions with another device in the environment. These devices can be detected without the need of a centralized server, and can be communicated with directly, peer-to-peer.

For information on the NAPlatform, NADevice, and NAMessage classes which are exposed by this SDK, please see the NewAer SDK Reference.

Use of this SDK is governed by NewAer SDK License.

Bluetooth Low Energy Overview

Newaer makes use of Bluetooth Low Energy wireless technology to communicate between devices across multiple platforms. In Bluetooth Low Energy communication, there are two key players: the central and the peripheral. The central scans to see available peripherals to communicate with. In order to be visible to the scanning central devices, a peripheral must advertise. In the Newaer framework, note that any given device can be both advertising its availabilty to other devices and scanning for them as well. Also note that scanning devices can only see advertising devices of the same Newaer Application id . Once a peripheral device is found during scanning, Newaer provides the ability to send a message directly to that device peer-to-peer, without the need of a centralized server. There is no guarantee of message delivery and devices do not need to authenticate with each other in order to send a message.

Supported Hardware and OS

On iOS, the supported hardware and OS version includes: OS version: 7.0+ Models: iPhone 4S, iPhone 5, iPhone 5C, iPhone 5S, iPod Touch 5th generation, iPad 3rd generation, iPad 4th generation, iPad Air, iPad Mini (all)

On OSX, the supported hardware and OS version includes: OS version: OSX 10.9+ Models: Mac Mini (late 2011+), Macbook Air (late 2011+), Macbook Pro (mid-2012+), iMac (mid-2012+), Mac Pro (late 2013+)

Scope

This SDK is available for applications targeting iOS and OSX. Due to the similarities of Cocoa implementations for these platforms, the NewAer Proximity Platform classes and function calls share a common footprint.

Not all devices have the same hardware features and some of the functions from desktop frameworks are absent in mobile frameworks. The documentation is written to describe the combined features across both platforms. Differences are called out where necessary.

Device Types

The SDK supports discovery of a range of devices. The scanning interface groups these devices into five categories:

Scanning Limitations

On iOS, this SDK only supports scanning updates for devices when the application is running in the foreground. If the application moves to the background, you will still receive an initial [NAPlatformDelegate platformDidFindDevice:], but irregular [NAPlatformDelegate platformDidUpdateDevice:] calls. Also note that as of iOS7, 2 iOS devices that are both locked will not be able to discover each other. This is not an issue on Android SDK. Note than when your iOS device is locked, it can still scan for other unlocked iOS devices.

The scanning engines in the SDK have different duty cycles. A [NAPlatformDelegate platformDidCompleteOneScan:] delegate lets you know when a scan cycle has completed. Depending on the scan family and characteristics of your radio environment, this delegate can be called immediately with no devices returned, after one device has been returned, or after a set of devices have been returned over a long time period. This delegate can be used to indicate progress to the user.

Device info

A detected device is expressed as a NADevice instance. NADevices can be enumerated based on the deviceId property. Depending on the device type, the deviceId has different uniqueness characteristics. A deviceId can be unique to:

• session: the deviceId reported by the SDK will not change during a scan session; different devices may observe different deviceIds
• global: the deviceId reported by the SDK will not change during a scan session and different devices will observe the same deviceId

The scanner will report one or more of the following events for each device:

• [NAPlatformDelegate platformDidFindDevice:]: this is the first observation of this device during the current run of the scanner. Calling [NAPlatform stopScanWithDeviceTypes:] will reset the list of devices.
• [NAPlatformDelegate platformDidUpdateDevice:]: a previously detected device has been observed and may have updated information. The updated information could include: signal strength, user info, last seen time, local/server observation, or device name. When a scanner includes raw signal strength information, these updates are limited to 2 per second.
• [NAPlatformDelegate platformDidLoseDevice:]: the device was determined to have gone out of range during the current run of the scanner. Calling [NAPlatform stopScanWithDeviceTypes:] will cause all previously found devices to issue a [NAPlatformDelegate platformDidLoseDevice:] event. Devices can go out of range for a variety of reasons: radio interface disabled, loss of network connectivity, signal too weak, or device has not been seen recently.

Devices with the NATYPE_NEWAER scan type have an additional property available called [NADevice deviceInfo]. This user info blob is empty unless set by the SDK developer. The blob is exchanged during the discovery phase and is updated just prior to each [NAPlatformDelegate platformDidFindDevice:] event. This allows the app developer to send and receive a small payload to every discovered device without having to wait for it to be reported and then having to queue and respond to messages.

The optional [NAPlatformDelegate platformDidRequestDeviceInfoFrom:] delegate is called when a remote device has begun its discovery and is requesting a user info blob. The function should return as quickly as possible to ensure the remote device discovery phase is not unnecessarily long. Device info can be a maximum of 90 bytes. When this delegate is called, the remote peer device info is not yet known. It is not possible to send a different payload depending on the remote device ID. You should use NAMessage instead.

Messaging

The SDK supports direct communication with peers devices that are discovered with the NATYPE_NEWAER scan type. To receive a message, a device must have issued a [NAPlatform startAdvertisingWithDeviceTypes:name:] call with NATYPE_NEWAER type. To send a message, a device must have issued a [NAPlatform startScanWithDeviceTypes:] call with the NATYPE_NEWAER type. Messages can be sent and received until the corresponding [NAPlatform stopScanWithDeviceTypes:] or [NAPlatform stopAdvertisingWithDeviceTypes:] call is made.

Messages are sent in the clear with no guarantee of delivery. NewAer SDK devices do not need to authenticate with each other in order to send messages. The SDK user will need to create authentication, encryption, and reliability mechanisms if they are needed for a particular application. If you are using the remote proximity scanner, note that messages can only be sent to devices that are discovered locally.

Dependencies

All applications created with the NewAer Proximity Platform SDK must obtain an application ID. You can obtain an application ID by visiting the NewAer Developer Portal and registering your bundle ID (more information in the example below). The application ID is used for license validation and for enabling the discovery of devices running your application(s).

iOS Dependencies

This SDK requires your application to target devices running iOS 7.0 or above. It requires your application to link with the following frameworks:

• CFNetwork
• Security
• MobileCoreServices
• CoreBluetooth
• CoreLocation
• SystemConfiguration
• UIKit
• Foundation

OSX Dependencies

This SDK requires your application to target devices running OSX 10.9 or above. It requires your application to link with the following frameworks:

• CoreServices
• IOBluetooth
• CoreWLAN
• Security
• SystemConfiguration

Open Source Packages and Licenses

This SDK makes use of the following open source components. You may be required to include copies of their licenses and credit to the responsible parties with your application:

• AFNetworking (https://github.com/AFNetworking/AFNetworking))
• PubNubClient (https://github.com/bountylabs/pubnubclient))
• Reachability (https://github.com/tonymillion/Reachability))

These components have been modified from their original version with a namespace prefix. For example the Reachability class has been renamed NAReachability. This allows you to use your own version of these components without having to worry about versions that the NewAer SDK may use internally.

For your convenience, we have included the referenced licenses in the docs/3rdParty directory.

Using the Example App to Test the SDK

This SDK includes a sample application called newaer-sdk-proximity-example. This application demonstrates proper initialization of the SDK, starting and stopping of scans, implementation of find and lose device delegates, the send message function, and receive message delegates.

Please refer to the source code and the NewAer SDK Reference for more details.

Scanning between MacOS & iOS

The first test to try is to advertise using your iOS device and scan to discover it using MacOS. Open newaer-workspace-apple/newaer-sdk-proximity-ios.xcworkspace, plug in your iOS device & set to the newaer-sdk-proximity-example-ios scheme &run. You should see the example app screen w/ 3 switches along the bottom. Switch on ‘Advertise’ to begin broadcasting your availability to other Newaer devices scanning with the example app.

Now that we are advertising, we want to set up another device to scan for the same Newaer application id. On MacOS, open newaer-workspace-apple/newaer-sdk-proximity-osx.xcworkspace in xcode & set to the newaer-sdk-proximity-example-osx scheme & run. Check the ‘Newaer’ checkbox under Scan to begin searching for any other devices advertising using the same application id. In a few seconds, you should notice that it found your iOS device :

Now, let’s try the opposite scenario. In MacOS, uncheck scan, under Newaer, and check advertise. You can relaunch the app if you want to start with a fresh log :

In your iOS project, turn off the ‘Advertise’ switch and turn on the Scan switch. In a few seconds, you should see your MacOS device :

Send a Message

Now that we can scan and detect advertising devices, let’s send a message, shall we? Let’s go ahead and advertise again on your MacOS Newaer example app session. In your iOS example app, turn on scan and you should detect your MacOS device. In the lower left switch from ‘Log’ to ‘List’. You should see your MacOS device in the table view @ the top of the screen :

Select your MacOS device from the list, and press ‘send message’. A dialog menu will pop up, enter your message and press ‘Send’.

Now, return to your MacOS project. You should see your message pop into the log within 30 seconds after sending it using your iOS device :

Scanning for Beacons

Simulating a beacon on an iOS device

On your iOS device, download BLEBeacon, this will allow to to simulate an iBeacon. Open the app & press the ‘+’ button to add a new Beacon Profile. Assign the Beacon a UUID to advertise – here, I choose 2a6b70e5-f974-4d42-911e-d44eff379b96 on Major 25, Minor 80 :

Now, let’s try to scan for our Beacon from another iOS device. In order for the Newaer SDK to be able to see your Beacon, you must add your Beacon id to the list of registered beacons using the following call:

[[NAPlatform sharedNAPlatform] registerBeaconIds:@[ @“2a6b70e5-f974-4d42-911e-d44eff379b96” ]];

In the example app, go to ViewController.m & edit / add your Beacon Id to the registerBeaconIds call in ViewDidLoad :

Now, let’s try to scan for the Beacon using our MacOS example app. Click the “advanced…” button and make sure Beacon scanning is enabled.

If you scan for Beacons, you should see it show up in UI :

Note that for multiple Beacons of the same UUID to be recognized, that must have varying Major & Minor numbers. You can simulate this behavior somewhat using the BLEBeacon App by adding additional Beacons, but note that only one can advertise at a time. So, to simulate multiple Beacons, you will have to cycle them on & off, round robin to test them all with your scanning device.

Scanning for Actual Beacons

The process of scanning for actual Beacons is the same as above. Just note that you must register the beacon uuids that you want to scan for using the [NAPlatform registerBeaconIds:] method. Also, note again that each unique Beacon that you wish to scan for of the same uuid needs to have a varying major / minor number combination.

Using the SDK with your own application

Note : Use of the Newaer SDK requires a Newaer Application Key. Read on to discover how to register for one and insert it into your app

Register Using the Newaer Developer Portal

1. Visit the Newaer Developer Portal @ https://newaer.com/developer-portal/

1. Click Don't have an account?
2. Fill in username and email
3. Click Sign up!
4. You will receive an email with a temporary password
5. Follow the link, enter your username and password
6. You should see the Developer Portal home screen, as shown below :

Getting an Application ID

1. Visit https://newaer.com/developer-portal/
2. Login (or sign up for an account, if you did not already register)
3. Click Register A New Application
4. Fill in your project information : Name, Platform (Android / iOS / MacOS / Windows), Package Name (i.e. my.app.package)

5. Click Edit an Existing Application to see a list of your existing Newaer apps & ids

6. Copy your new application id

App Integration

1. Download the latest version of the SDK for each relevant platform, located under ‘Get the Code’ in Developer Portal

   

2. Install the Newaer SDK into your project

   • Copy newaer-sdk-proximity/ios/build/Release into your project
   • Add libnewaer-sdk-proximity.a to your build phases/link binary with libraries
   • Add to the library search path in build settings: ${PROJECT_DIR}/newaer-sdk-proximity/ios/build/Release

   • Add to the user header search path in build settings: ${PROJECT_DIR}/newaer-sdk-proximity/ios/build/Release/include

     

3. Add supporting frameworks

   • iOS
     • CoreLocation, CoreBluetooth, CFNetwork, Foundation, MobileCoreServices, Security, SystemConfiguration, UIKit
       
   • OSX
     • CoreServices, CoreWLAN, IOBluetooth, Security, SystemConfiguration
       

Quick Start

1. Need to first initialize before you can start scanning / advertising Pass in the delegate who will deal with responses

     [NAPlatform initializeWithApplicationId:@"YOUR_APPLICATION_ID" packageName:@"YOUR_PACKAGE_NAME" delegate:self];
   

2. Wait for the [NAPlatformDelegate platformInitComplete] delegate to fire. This ensures that the SDK is initialized and ready to begin scanning or advertising. If you attempt to scan or advertise before this delegate fires you will receive errors.

    // Initialization complete
    - (void)platformInitComplete
    {
        // Okay to start scanning or advertising
    }
   

3. Implement required delegates:

    // Registration Failure 
    - (void)registrationFailed:(NARegistrationFailureType)error {
    }
   
    // Scan failure
    - (void) platformScanFailed:(NADeviceType) type 
    }
   
    // Advertise failure
    - (void) platformAdvertiseFailed:(NADeviceType) type {
    }
   
    // Scan type changed availability
    - (void) platformDidChangeSupportedType:(NADeviceType) type status:(NADeviceTypeStatus)status {
    }
   

4. Implement optional delegates:

    // Device Found
    - (void)platformDidFindDevice:(NADevice *)device {
    }
   
    // Device Lost
    - (void)platformDidLoseDevice:(NADevice *)device {
    }
   
    // Device updated
    - (void)platformDidUpdateDevice:(NADevice *)device {
    }
   
    // Message received
    - (void)platformDidReceiveMessage:(NAMessage *)message from:(NADevice *)device {
    }
   

5. Start scanning.

    [[NAPlatform sharedNAPlatform] startScanWithDeviceTypes:@[[NSNumber numberWithInt:NATYPE_NEWAER]]];
   

6. Begin Advertising. If name is nil, the device name is used.

    [[NAPlatform sharedNAPlatform] startAdvertisingWithDeviceTypes:@[[NSNumber numberWithInt:NATYPE_NEWAER]] name:nil ];
   

7. Send a message to a deviceId that you received from a [NAPlatformDelegate platformDidFindDevice:]

    [[NAPlatform sharedNAPlatform] sendMessage:message to:deviceId];
   

FAQ

When does the SDK prompt for any user permissions? The SDK can be initialized without any user permissions. This is usually done in your AppDelegate or ViewController. You can send commands to NAPlatform once the platformInitComplete delegate has been called. You can also call [NAPlatform isInitialized] to determine if the SDK is intialized.

The SDK will prompt for user permissions in the following cases: 1. Calling startScanWithDeviceTypes with NATYPE_BEACON will present a CoreLocation alert requesting access to location information. Use the NSLocationAlwaysUsageDescription in your plist file to customize this message. 2. Calling startAdvertisingWithDeviceTypes with NATYPE_BEACON or NATYPE_NEWAER with bluetooth-peripheral background mode specified in your plist file will present a CoreBluetooth alert requesting sharing data as a bluetooth peripeherals while in the background.

My application key fails verification? What do I do?

You can get more detailed information about the cause of your application key failure by implementing the [NAPlatformDelegate registrationFailed:] delegate.

If you get the message NAPLATFORM_DEVELOPER_KEY_INVALID, doublecheck that you are initializing your NAPlatform object properly with

[NAPlatform initializeWithApplicationId:@“YOUR_APPLICATION_ID” packageName:@“YOUR_PACKAGE_NAME” delegate:self];

Doublecheck that your Newaer application id matches what is shown in the Developer Portal. Also, ensure that your bundle id matches what was entered in the developer portal.

Why are my startScan and / or startAdvertise call failing?

You must wait for [NAPlatformDelegate platformInitComplete] to be called before you issue startScan / startAdvertise / sendMessage commands.

What version of iOS are supported?

Newaer SDK is only supported for iOS devices using Bluetooth Low Energy technology. This includes all iOS 7.0+ Models of iPhone 4S, iPhone 5, iPhone 5C, iPhone 5S, iPod Touch 5th generation, iPad 3rd generation, iPad 4th generation, iPad Air, iPad Mini (all)

What versions of OSX are supported?

Newaer SDK is only supported for Mac devices using Bluetooth Low Energy technology. This includes Mac OSX 10.9+ Models: Mac Mini (late 2011+), Macbook Air (late 2011+), Macbook Pro (mid-2012+), iMac (mid-2012+), Mac Pro (late 2013+)

As a developer, I’m using AFNetworking, Reachability, or library X do I need to worry? Is this thing compatible with Cocoapods?

Yes, Newaer will not conflict with any of your 3rd Party Libraries, whether loaded from Cocoapods or otherwise

How quickly should I see a device?

A scan can take up to 7 seconds to complete. A successful scan will trigger the [NAPlatformDelegate platformDidStartScan:] delegate, whie a failure will trigger [NAPlatformDelegate platformScanFailed:status:]. After each scan cycle completes, [NAPlatformDelegate platformDidCompleteOneScan:] will also be triggered.

How quickly should a device disappear when it goes out of range?

Newaer will wait 60 seconds after a device disappears before issuing a delegate call to [NAPlatformDelegate platformDidLoseDevice:]. This is to prevent ‘flapping’ of find / lose events due to low signal strength when devices are at the edge of detection.

What is the range of device discovery for each type?

The range differs depending on device and power level, up to approximately 300 feet.

How do I know how close a peer device is?

Proximity can be inferred by the signalStrength property on NADevice, which can be used to infer relative distance based on it delta over time. But signal strength alone is a relative measure and not an accurate indicator of exact distance. Currently, there is no means to accurately measure precise distance between devices within the Newaer framework.

Here is a sample graph of signal strength vs. distance for an iOS device advertising to another iOS device

How long does it take to send a message to another device? Are the messages guaranteed to be delivered?

Time can vary according to multiple factors including how many peers are nearby. Typical message sending times are in the neighborhood of 15 to 20 seconds.

Do I have to do anything special for iOS 8?

Yes, you must add NSLocationAlwaysUsageDescription to your application’s plist file and provide a description that will be displayed when the user is prompted for permissions to use Bluetooth.

What is the remote scanning switch?

The NewAer SDK features a remote proximity service that can help determine which devices are nearby more effectively. This feature sends all NewAer device, iBeacon, and WiFi access point observations to a server. The server compares the observations from multiple devices running your application and determines if any devices that haven’t been discovered yet should be available. For example, if two devices running your app discover the same WiFi access point but do not discover each other directly, the remote proximity scanner will tell your application that those devices should be visible.

In the example application, those devices will appear in the device list with a cyan background. For best use of the remote proximity service, you should enable scanning for all device types.

What is the ranging switch?

Some applications require more frequent updates of devices, such as when the application is trying to do something when a device gets nearer or farther away. When the ranging switch is enabled, the SDK provides updates for NATYPE_NEWAER and NATYPE_BEACON devices more frequently (once a second). When the ranging switch is disabled, the SDK provides updates every 30 seconds.

The ranging mode requires more battery and should only be used for short periods. Regardless of the setting of this switch, the ranging mode is disabled when your application goes to the background.

Advanced/Background/Power modes

How do I get the SDK to report events when my app is in the background?

In order for your application to use BTLE while running in the background, it must declare that it supports a Core Bluetooth background execution mode in its .plist file. Two entries should be added under ‘Required background modes’, ‘App communicates using CoreBluetooth’ and ‘App shares data using CoreBluetooth’

Note that if your app is in the foreground and a device is nearby, you will get a [NAPlatformDelegate platformDidFindDevice:] event for the device followed by a stream of [NAPlatformDelegate platformDidUpdateDevice:] events, every 500ms as long as that device is in range. If your app is in the background you will only get the initial [NAPlatformDelegate platformDidFindDevice:] until you bring the app to the foreground. We do not generate any notifications on the screen. You can choose to notify the user if you want or just record their unique identifier and send it to your server.

The NewAer SDK supports a more advanced background mode that allows your application to receive events more frequently and receive events when one or more devices near each other are locked. For more information on this mode, please refer to NewAer Advanced Background Mode Application Note.

How can I get my app to launch into the background when it is killed and I’m using beacon scanning?

When scanning a Beacon, an app will get automatically relaunched if it gets killed while actively scanning for a Beacon. You must have initiated [NAPlatformDelegate platformDidStartScan:] and have not yet issued a [NAPlatformDelegate platformDidStopScan:]. The app will get automatically relaunched, Newaer will do its initialization and your app will be returned to the state of scanning for beacons.

How much battery will it use if I scan for type NewAer, Beacon, or Wearable?

Here is a graph of battery power vs. scan time for various devices

More Information

More information on the BTLE 4.0 spec

More information on Apple’s Core Bluetooth Programming Guide