WayFinder with Vault and Push

A further upgraded WayFinder app that sends push notifications whenever you are in range of a beacon.

Purpose

"WayFinder with Vault and Push" takes our previous "WayFinder with Vault" app and adds the ability to receive push notifications from ContextHub whenever you are in range of a beacon. This sample app shows the power of the contextual engine to respond to events generated by the device to triggered

Setup

If you haven't already, go through "WayFinder with Vault" to setup beacons, contexts, and vault data on the server which will be used again in this demo. We will also be using the same 3 beacons to demonstrate push, however testing push notifications on "beacon_in" and "beacon_out" events is much easier using an app like Locate for iBeacon instead of real beacons (unless you can adjust the range, most default to 50 meters):

• UUID: B9407F30-F5F8-466E-AFF9-25556B57FE6D

• Major: 100
• Minor: 1
• Name: LOBBY

• UUID: B9407F30-F5F8-466E-AFF9-25556B57FE6D

• Major: 100
• Minor: 2
• Name: IDEAWALL

• UUID: B9407F30-F5F8-466E-AFF9-25556B57FE6D

• Major: 100
• Minor: 3
• Name: TEAMROOM

You will need to create your own ContextHub account for this sample app, so log into the portal and have an app ID ready to use. If you have already created an app id from "WayFinder with Vault", you can use the same id. This sample app will modify the contextual rules created from the previous to generate push notifications sent to your device any time a "beacon_in" event is triggered. Also, when a "beacon_out" event is triggered from the last beacon, it will send another push notification to your device.

Push notifications are more challenging to set up than what was required in previous sample apps due to the complexity and security needed to talk to Apple's push notification serviers (APNS). If you follow the instructions carefully, you should get everything working.

1.The first step in setting up push notifications is generating a .p12 file which has both your private key and certificate needed by APNS. We will be doing this twice as the development APNS (and associated keys/certs) are separate from the production APNS (with different keys and certs). There are several guides on the Internet to generate a .p12 file correctly, with (this one)[https://parse.com/tutorials/ios-push-notifications] from Parse having clear images as a guide in case you get lost. When exporting in Keychain, make sure you select both the private key and certificate to export into a single file as ContextHub needs both. Save the file as "Certificates.p12". 2. With a .p12 file in a folder, navigate using Terminal into that folder and run the following command: openssl pkcs12 -in Certificates.p12 -out certificate.pem -nodes -clcerts. This will generate a certificate.pem which you can open up in any text editor like TextEdit to be copy and pasted into the Settings page of your ContextHub app. The code should look something like this: Bag Attributes friendlyName: Apple Production IOS Push Services: YOUR-BUNDLE-ID-HERE and end like this -----END RSA PRIVATE KEY-----

3. Paste the text you got from the certificate.pem into the appropriate certificate box (either sandbox/development or production). You can verify that you have created the correct keys and certs by the presence of the phrase Apple Development IOS Push Services for sandbox and Apple Production IOS Push Services for production.
4. Now it's as easy as writing a context rule to send a push notification any time there is a "beacon_in" event. Go to "Contexts" in the ContextHub developer portal, click on the "beacon_in" event you created in "WayFinder with Vault", and put in the following line of code (replacing the "true" from earlier): push.sendToTags("device-wayfinder", "You have entered the range of a beacon"). Then click save.
5. Lastly, we'll write the rule to send a push when a "beacon_out" event is sent, but only from the 3rd beacon. In the "beacon_out" context, paste in the following code: if (event.data.beacon.minor == "3") { push.sendToTags("device-wayfinder", "You have left the range of beacon 3") }

This code looks inside the event object generated from the beacon_out event to see what minor value was present. Look at the documentation for each of the objects to read more about what you can do within a context.

Project: In the project you've cloned from GitHub, you'll need to change a few project settings to make sure you're app will be in correct working state:

1. Open the project in Xcode and select the Project tab (Shortcut: Command-1), then select your project to bring up it's setting in the main pane.
2. In the general tab, make sure that the bundle ID is the same one you used to generate your certificates and public/private keys from before. Most importantly, you're bundle ID cannot have any wild-cards.
3. In the "Capabilities" tab, turn on "Background Modes" and check "Remote notifications" to enable the correct entitlements.

Now everything is setup to run your demo!

Demo

Launch and run the app from your device. Here's how it works:

1. The device will respond to the presence of beacons and advance screens just like before.
2. Information can be changed in the vault and the app restart also like before.
3. Most importantly, push messages will be sent whenever a specific beacon is in range to a device and when the last beacon goes out of range. It's easiest to simulate "beacon_in" and "beacon_out" events using an app like Locate iBeacon than real beacons due to their range (over 50 meters by default).

Code

Building on top of "WayFinder with Vault", the critical part of this "WayFinder with Vault and Push" sample app is being able to send push notifications from the server and receive them on the device:

1. In application:didFinishLaunchingWithOptions:, make sure to put the following 3 lines of code before you call [ContextHub registerWithAppId:]: #ifdef DEBUG [[ContextHub sharedInstance] setDebug:TRUE]; #endif

This will conditionally enable at compile time the debug flag needed in order to determine which APNS ContextHub should talk to in order to succesfully send push notifications.

2. Call [application registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeNewsstandContentAvailability ]; to register for notifications. This will present a popup to the user about push notifications. If they choose no at this screen, it will not pop up again and the user will need to go to Notifications in Settings.app to re-enable push notifications.
3. Add the following two methods to your app delegate: application:didFailToRegisterForRemoteNotificationsWithError: and application:didRegisterForRemoteNotificationsWithDeviceToken: The first is called in case registering for push notifications did not succeed and the second if it did succeed with a push token.
4. You then need to register the push token with ContextHub by calling [[CCHPush sharedInstance] registerDeviceToken:alias:tags:completionHandler:]. Device token is the NSData token received from the success method call in step 3, alias is a shorter way to reference a device or group of related devices (from say the same owner) and tags are a way to arbitrarily group devices together.
5. Lastly, respond to push notifications in a method called application:didReceiveRemoteNotification:fetchCompletionHandler: within your app delegate making sure to call [[CCHPush sharedInstance] application:application didReceiveRemoteNotification:userInfo completionHandler:completionHandler] before your own code in order to allow ContextHub to process some background notifications. If a push wasn't meant for ContextHub to do background processing, your completion handler will be called to respond to the notification.

That's it!

Note: Current demo is set up such that a response from a beacon is triggered when it is either "near" the device (6-12 inches) or "immediate" to the device (within 6 inches). It takes approximately 2-3 seconds to notice a transition in state from far (within 50 ft) to other states (near or immediate).