Hello ContextHub!

The "Hello ContextHub" sample app that first introduces you to power the ContextHub Android SDK and developer portal

Table of Contents

1. Purpose
2. ContextHub
3. Getting Started
4. ADB Logcat
5. Developer Portal
6. Context Rules
7. Creating a New Rule
8. Using the Vault Object
9. Final Words

Purpose

Today's world is full of devices and sensors just waiting to be tapped into. Meaningful events happen all the time, when we get home from work, approach an interesting painting, or visit our favorite coffee shop. ContextHub takes those meaningful events in our lives and transforms them into powerful triggers your apps can respond to turn apps into experiences for your end users.

ContextHub

In this sample application, we use ContextHub introduce the relationship between devices triggering events on the server by setting up geofences on a map. ContextHub takes care of setting up and monitoring geofences to generate events that the server can listen and respond to and then save those events in a vault to be accessed later.

Getting Started

1. Get started by either forking or cloning the Hello ContextHub repo. Visit GitHub Help if you need help.
2. Go to ContextHub and find the app id associated with the "Hello World" app. Its format looks something like this: 13e7e6b4-9f33-4e97-b11c-79ed1470fc1d.
3. Open up the project and put the app id into the ContextHub.init(this, "YOUR-APP-ID-HERE") method call in the HelloContextHubApp class.
4. In the src/debug/res/values/google_maps_api.xml resource file, replace YOUR-API-KEY-HERE with your Google Maps API key. See the comments in that file for the help creating the API key.
5. On a physical Android device (Google Play Location Services tends to work best on a real device), go to Settings > Developer Options and check the "Allow mock locations" setting.
6. Build and run the project on your device.

ADB Logcat

1. This sample demo will log events into the debug console to get an idea of the JSON structure posted to ContextHub.
2. When the app is launched, it should generate a location_changed event in the console which you can look at. You are able to access information about the event like device name, device ID, latitude, longitude, and speed.
3. Use the ContextHub.addContextEventListener(ContextEventListener listener) method to hook into the events generated by ContextHub.
4. Check out the ContextHub documentation for more information about the event pipeline and what you can do with it.

Developer Portal

1. The real power of ContextHub comes from collecting and reacting to events posted from devices onto the server. Go back to the developer portal and click on your app "Hello ContextHub" to access its data.
2. You are brought to the Application home page which will show you the latest events generate from your devices.
3. Click on the Contexts link. This will take you to the "Contexts" page which controls how the ContextHub server responds to events generated from devices. To the left you'll see "Contexts", which are rules which allow actions to be triggered depending on event data. To the right, you'll see your latest events triggered by devices with your app installed.

Context Rules

Context rules let you change how the server will respond to events triggered by devices. Let's go ahead and create a new rule that will save the some data on the server in the vault.

Creating a New Rule

1. In the "Contexts" tab, click the "New Context" button to start making a new rule.
2. Enter a name for this context which will be easy for you to remember. For now, name it "Geofence in".
3. Change the event type to geofence_in. Now any event of type geofence_in will trigger this rule. You can have multiple rules with the same event type, which is why name of events should be descriptive of the rule. You can also have custom event types which you can trigger yourself inside your apps.
4. Below is where you can write a rule telling ContextHub what actions to take in response to an event triggered with a specific event type. This code is Javascript, and you have access to four objects: event, push, vault, and console.
5. Simulate a location change in the device by tapping somewhere on the map.
6. Long press on the map near the current location to create a geofence around it. You should also see a Fence creation event in Logcat.
7. Tap somewhere outside the geofence to change the simulated location. You should see a geofence_out event posted in the console. If you are having issues with events not being generated, make sure you have network connectivity so you can get back responses from ContextHub.
8. Tap inside the geofence to change the simulated location back to where you previously were. You should see a geofence_in event trigger as well.
9. In the ContextHub developer portal, you should be able to see events generated by your device appear under "Events", no code needed!

Using the Vault Object

Now that we've gotten the app to trigger events that both appear on the device and the server, it's time to create a rule that does something with that event.

1. Go back to "Contexts" and click on the location_changed context.
2. This page is where you previously created the geofence_in rule. Now, let's save the event data to the vault using Javascript.
3. Like stated previously, context rules have access to three objects: events, push, and vault. Events contain data about the event which triggered the rule. Push lets you send push notifications to devices. And the vault object lets you persist data on the server for retrieval later. Take a look at the vault object by clicking on it and seeing what methods it has access to.
4. When creating an object in the vault, it's best practice to tag it. You can use tags to hold similar vault items in a group for ease of access. To save the event object with a tag called "sample", type vault.create(JSON.stringify(event), "sample") into the Code editor then click save.
5. Restart the emulator again, check and see if a location_changed event was generated, then go back to the developer portal to see if the event appeared in "Events".
6. Now click on "Vault" under "Application" to see if a "sample" container with an item with event data was created. Each time the location_changed event is received by ContextHub, it will create a new item in the vault for you to access based on the rule you just created.
7. That's all it takes to create a rule and put data into the vault!

Final Words

Hopefully you found the ease of use and power of our platform a compelling reason to use ContextHub an integrate it into your own projects. There are several more sample applications that go into specific detail around using geofences, beacons, push, and contextual rules to create powerful contextual applications!