The "Hello ContextHub" sample app that first introduces you to power the ContextHub Android SDK and developer portal
Table of Contents
- Getting Started
- ADB Logcat
- Developer Portal
- Context Rules
- Creating a New Rule
- Using the Vault Object
- Final Words
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.
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.
- Get started by either forking or cloning the Hello ContextHub repo. Visit GitHub Help if you need help.
- Go to ContextHub and find the app id associated with the "Hello World" app. Its format looks something like this:
- Open up the project and put the app id into the
ContextHub.init(this, "YOUR-APP-ID-HERE")method call in the
- In the
src/debug/res/values/google_maps_api.xmlresource file, replace
YOUR-API-KEY-HEREwith your Google Maps API key. See the comments in that file for the help creating the API key.
- 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.
- Build and run the project on your device.
- This sample demo will log events into the debug console to get an idea of the JSON structure posted to ContextHub.
- When the app is launched, it should generate a
location_changedevent 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.
- Use the
ContextHub.addContextEventListener(ContextEventListener listener)method to hook into the events generated by ContextHub.
- Check out the ContextHub documentation for more information about the event pipeline and what you can do with it.
- 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.
- You are brought to the Application home page which will show you the latest events generate from your devices.
- 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 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
- In the "Contexts" tab, click the "New Context" button to start making a new rule.
- Enter a name for this context which will be easy for you to remember. For now, name it "Geofence in".
- Change the event type to
geofence_in. Now any event of type
geofence_inwill 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.
- Simulate a location change in the device by tapping somewhere on the map.
- 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.
- Tap somewhere outside the geofence to change the simulated location. You should see a
geofence_outevent 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.
- Tap inside the geofence to change the simulated location back to where you previously were. You should see a
geofence_inevent trigger as well.
- 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.
- Go back to "Contexts" and click on the
- This page is where you previously created the
- 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.
- 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.
- Restart the emulator again, check and see if a
location_changedevent was generated, then go back to the developer portal to see if the event appeared in "Events".
- Now click on "Vault" under "Application" to see if a "sample" container with an item with event data was created. Each time the
location_changedevent is received by ContextHub, it will create a new item in the vault for you to access based on the rule you just created.
- That's all it takes to create a rule and put data into the vault!
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!