kharmabum/Aura-Demo.md

## Aura-Demo.md

      
    Raw
  

              Aura-Demo.md
            
          
    AURA DEMO

AURA makes it easy to add presence-enabled features to your iOS 8 application. It takes about 10 lines of code to detect encounters between your users in a highly energy efficient and secure manner.
Getting Started

In your target application's XCode project


Add Aura.framework
Add CoreBluetooth.framework
Add -ObjC to your "Other Linker Flags" build setting.
Include Uses Bluetooth LE accessories and Acts as Bluetooth LE accessory within your application target's listed background modes.
Within your AppDelegate.m include:

#import <Aura/Aura.h>
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [Aura startWithClientAppKey:@"YOUR_KEY" secret:@"YOUR_SECRET"];
    ...
    return YES;
}

Create a JBAActor

In JBAActor AURA provides a convenient abstraction that you can use to associate a device with your application's users. When you create an actor you can optionally provide metadata via a dictionary of values as well as your own identifier. Upon being made activeActor, other devices running your application will be able to detect and have access to its metadata and identifier when nearby.
An actor can be modified and made active solely from the device on which it was created; however, multiple actors can share the same metatdata and identifier. You can also query actors by the identifier you provide.
You can create actors with calls to:
    [Aura registerNewActorWithMetadata:myUsersInfo clientIdKey:@"username" activeStatus:YES completion:^(NSError *error, NSString *auraIdentifier) {

        // Success
        if (!error) {
            NSLog(@"New actor %@ (with auraIdentifier %@) set as active", activeActorInfo[@"username"], auraIdentifier);
        }
        // Error
        else {
            NSLog(@"%@", error);
        }
    }];

Enabling and disabling Aura

Per Apple's guidelines, apps integrating AURA must "provide an interface that allows the user to decide when to start and stop the delivery of Bluetooth-related events." For AURA this simply translates to setting or removing the activeActor for the device in response to the user's indicated preference.
Observe JBAEncounter updates:

When two users of your application are in close proximity, AURA generates JBAEncounter instances on each device [1]. Encounters expose an RSSI value for the actor that is periodically updated, which can serve as a rough approximation for distance.
When both actors can no longer detect each other [2], the associated encounter on each device is closed (isOpen == NO). Depending on the physical environment as well as the state of your application and the device's onboard radio, time-to-detection for both opening and closing encounters will vary. However we find most encounters are updated within a minute [3].
You can register multiple callbacks for encounter updates. Each gets invoked whenever a new encounter is opened or a currently active encounter closes. Updates to the RSSI value do not invoke your registered callbacks. All registered blocks are called on the mainthread.
[Aura observeEncounterUpdatesWithBlock:^(JBAEncounter *encounter) {
    NSLog@"Encounter with %@ is %@", encounter.actor..auraIdentifier, encounter.isOpen ? @"open" : @"closed";
}];

1, 2, 3 These benchmarks only hold for apps that have enabled Aura push notifications.
AURA push notifications:

Setting up push notifications for AURA improves the service's reliability and continuity between devices.  All remote notifications sent on AURA's behalf are silent and do not require the presentation of a permissions dialogue to the user. AURA currently integrates with a number of push notification providers but can also deliver updates to custom web hooks that you specify (which should then forward the payload to the device via silent push). The added benefit of custom web hooks is that you can send push notifications with an alert body that will appear in the notification center (provided you've attained appropriate permissions from your user) in response to AURA encounter updates that will be delivered regardless of whether your app is open.
Setup


Include "remote notifications" within your application target's background modes.
Follow this [guide](https:// parse.com/tutorials/ios-push-notifications) to set up push notifications for your application through Parse.
Within AppDelegate.h:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
    [Aura setDeviceToken:deviceToken
         forPushProvider:JBAPushProviderParse
                withInfo:@{@"rest-key": @"YOUR_PARSE_REST_API_KEY",
                           @"application-id": @"YOUR_PARSE_APPLICATION_ID"}
              completion:^(NSError *error) {
                  NSLog(@"%@", error);
    }];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    if (userInfo[@"aura_data"]) [Aura handleRemoteNotification:userInfo completion:^{ completionHandler(UIBackgroundFetchResultNoData); }];
}

FAQ


What happens if I run AURA in the simulator?

Setting an activeActor has no effect.

Is background detection reliable?

It depends on your use case. AURA relies on your application's access to resources that are shared between many process and managed at the system level. Availability is influenced by many factors including device usage patterns unrelated to your application as well as the concentration of nearby actors.  We expect background performance to steadily improve with time and that current performance levels will enable a great deal if not most desired functionality.

What happens in large groups of people?

We don't really know yet.

What devices are supported?

iPhone 4s and up
5th gen iPod touch and up (I think)
... iPads

If actors are tied to a particular device, what happens if my user is logged in on multiple devices?

Create new actors for each device with the same identifier. See advice below on how to best utilize actor metadata.

What if a hacker cracks my client key/secret?

(DRAFT)
TLDR:

Don't put sensitive information (e.g. anything requiring O.Auth) in your actor's metadata
Think of the metadata as a container for a pointer to your user object
Keep track of the actors your app creates

If a hacker extracts your key/secret and creates 'fake' actors, you can reference the auraIdentifiers you've saved in your own datastore to see if they match up.


Make hackers' lives tougher:

http://samdmarshall.com/blog/blocking_code_injection_on_ios_and_os_x.html
https://github.com/orta/cocoapods-keys
https://github.com/UrbanApps/UAObfuscatedString