Sections ▾

iOS

Registration and Setup

Registration

On ContextHub, you create a separate app for each of your mobile applications. Each app has its own application id which you will use to register with the ContextHub iOS SDK. Each account on ContextHub can have multiple application ids for multiple apps. This lets you accommodate both testing and production versions of your app with the same account.

Sign Up

Sign up for ContextHub by either creating a username/password or using your GitHub credentials.

Push Notifications

Push notifications let you send foreground messages which your users will be alerted to as well as background notifications which trigger your app to run for up to 30 seconds. Combined with elements that trigger events, this allows for increased functionality that forms the foundation of most apps that use ContextHub. Here’s how to use it:

Registering

Registering for push involves telling the device what kind of notification types you wish to use (badge, alert, sound). That triggers a request to the user asking for permission for those alerts (which they can deny), then Apple Push Notifications gives you a token which CCHPush uses along with an associated alias and set of tags to tell ContextHub which devices to get which messages.

Setting Up

Setting up push involves creating an NSDictionary which the pre-specified keys to send the message you want. Keys are optional based on what kind of message you would like to send (foreground of background) and additional information can be sent along with the push. The total message must be under 256 bytes or it will not be delivered.

Sending to Device(s)

Sending to a device is as simple as sending an array of device IDs along with the NSDictionary containing the message you want sent. The push message will then get queued to be processed in a first-in, first-out basis on the server.

Sending to Alias(es)

Sending to an alias is similar to sending to a device, where ContextHub will figure out which alias maps to a device to send out a message. Remember that unlike device IDs, aliases are not requiring to be unique, so sending a message to “iPhone” will send to all devices with that alias. It is therefore recommended to pick an alias that is unlikely to be confliciting at the global scope of your app (hashed usernames are a good choice).

Sending to Tag(s)

Sending to tags are also similar to sending to devices and aliases where CCHPush takes an array of tags to send a message to. Tags also are not required to be unique, and since a device can have multiple tags, it is possible for a device to receive multiple messages if you send the same message to multiple tags. Keep this in mind when building the logic in your app if that is undesired behavior.

Receiving

Receiving a message is as simple as defining a completion handler with your custom code and passing that to CCHPush to be called at the appropriate time. You can pull out information from the notification such as message or custom data, and act on it appropriately. This method will get called even if your app isn’t running if the push is a background push (presence of “aps.content-available” key with a value of 1). Since ContextHub has background pushes that keep CCHSensorPipeline in sync, use this pattern to ensure that your app always has the latest data about element services that generate events.

Events

Events are generated in ContextHub through the CCHSensorPipeline class which allows your application to turn on and off what elements a device is aware of and will then flow up to ContextHub for processing. You can listen in on a variety of events including beacon_in, beacon_out, and beacon_changed events, geofence_in and geofence_out events, and then location_changed and motion_changed events.

Note: In order to conserve battery life, only events which are subscribed to will generate events in ContextHub (with exception of location_changed)

Protocols

ContextHub provides control over events being processed through two protocols: CCHSensorPipelineDataSource and CCHSensorPipelineDelegate. This allows you to determine which events should, will and have been posted to the ContextHub server as additional control points. You will also have the ability to add custom payloads to your events which you can use in your context rules written in the ContextHub developer portal. Below is how to setup these two protocols in your application.

Subscribing

Subscribing to a tag turns on the sensor pipeline to start generating events from elements with that tag. This allows you complete flexibility in having many geofence and beacon elements present in the ContextHub portal, but have only a few specific elements trigger events within your application on a user’s device. Below is how to subscribe to a tag with the SDK:

Observing

In order to listen to events being generated from ContextHub, you have the option of observing whether a method should be called if an event will be posted, has been posted, or was canceled. You do this by adding an observer to NSNotificationCenter which will call your method(s) immediately after ContextHub raises the appropriate notification. Not all of these notifications need to be observed in a single application, pick and choose the one that best fills your needs.

Handling

Finally, you’ll start getting notifications sent to your method about events. Your method signature will have a simple structure as written below, with the event present in the object property of the notification for you to inspect. Note that all events will pass as notifications to this method, so you’ll need to inspect the event to distinguish between for example a geofence_in event from a beacon_out event.

Unsubscribing

Unsubscribing to a tag is very similar to subscribing, and turns off the sensor pipeline to notifications from elements with that tag. Be sure to also stop observing posted notifications at the appropriate time in your app to prevent potential bugs and crashes.

Data Distribution

Vault lets you save data to the server which all devices and context rules can access. Combined with element services, it allows beacons and geofences to have state. Here’s how to use CCHVault:

Creating

Creating a vault item is simple. Vault items need to be JSON-serializable NSDictionary items so they can be saved properly in ContextHub. In general, values stored are strings, arrays, and dictionaries, which allows for an arbitrary nesting of values. Below is an example of creating a vault item, then processing the response to extract the metadata given to you from ContextHub:

Response

Once a vault item is created, a dictionary response is returned with two keys, data and vault_info. data contains your data which you meant to save in ContextHub. vault_info stores some metadata about your vault information and contains information like the id, tags, created_at, and updated_at timestamps. Here’s the structure of a vault item that was created above:

Retrieving by Tags

Retrieve a group of vault items from ContextHub by passing a tag to CCHVault. Adding more tags to the same method call filters only items that have all tags on the same vault item.

Retrieving by ID

Retrieve a specific vault item from ContextHub by passing a vault ID present either in the ContextHub developer portal or given to you as a dictionary response from the SDK at the keypath “vault_info.id”.

Retrieving by Matching KeyPath/Value

Retrieve a group of vault items that have match a value for a given keypath, by passing a keypath, value and tags which ContextHub should search through. You’ll receive an array of responses which match the given keypath/value combination in the data key of the response.

Updating

Updating a vault item requires passing back a structure similar to the one returned to you from create/retrieve calls with both data and vault_info keys. ContextHub does an entire replacement of the vault item with your new data, so you must pass the entire structure, not a patch to an existing structure currently on the vault. This is to prevent errors from happening when multiple devices attempt to access the same record. ContextHub then updates the vault item, and triggers pushes to devices interested in vault item with that specific tag.

Deleting

Deleting a vault item is similar to updating, and requires passing a strecture similar to one returned to you from create/retrieve calls with bot data and vault_info keys. The vault item is deleted from ContextHub, then triggers pushes to devices interested in vault item deletions with those specific tags.

Subscriptions and Tags

Subscriptions send your app background notifications whenever a contextual element like a beacon, geofence or vault item has been updated on the server so you can respond to it in real-time. Here’s how to use the CCHSubscriptionService:

Subscribing

Subscribing to a tag is simple. Pass the tag you are interested in to CCHSubscriptionService along with the elements you are interested in as options (CCHOptionBeacon, CCHOptionDevice, CCHOptionGeofence, CCHOptionVault, or nil to get all of them) to be subscribed to any creation, update, or deletion of elements with that tag.

Retrieving

Retrieve all the tags you are subscribed to for each service by calling [CCHSubscriptionService getSubscriptionsWithCompletion:] then accessing the appropriate key in the dictionary.

Unsubscribing

Unsubscribing from a tag is similar to subscribing by passing in a tag and options (same as above) so your application is no longer notified about creation, updates, or deletion of items of elements with that tag.

Using Location

Location services on iOS allow your application to use cellular, WiFi, GPS, and Bluetooth radios to determine a user’s location with varying levels of accuracy based on your need. iOS uses these technologies to allow for location tracking while your app is running as well as region monitoring with beacons and geofences. Below are the specific details for interacting with geofences and beacons.

Using these services requires explicit permission as of iOS 8. ContextHub will request this permission on your behalf as soon as a geofence or beacon has been set up to be monitored. You need to provide values for either the NSLocationAlwaysAuthorization or NSLocationWhenInUseAuthorization keys in your Info.plist to explain to users why Location Services is needed in your application. NSHipster provides a great overview of these changes for you to read.

Beacons

Beacons are Bluetooth 4.0 Low Energy devices that allow devices to detect proximity to objects within 50 meters. This gives you the ability to give context-sensitive information to your users in areas where GPS, WiFi, and cellular towers cannot pinpoint a user’s exact location, such as deep inside buildings or underground. Here’s how to use CCHBeaconService to interact with beacons:

Creating

Creating a beacon contextual element in ContextHub is simple. Every beacon has a UUID (32 digit hexadecimal character, a major value (ranging from 1-65535), and a minor value (also ranging from 1-65535). UUIDs you use should be unique so beacons from other user’s do not interfere with your app. A combination of these three values should be unique for every beacon you have. You can also create a standard CLBeaconRegion class from the response for use in your app. After creation,[CCHSensorPipeline synchronize:] must be called if you do not have to push enabled so the sensor pipeline is ready to generate beacon events.

Retrieving by Tag

Retrieve a group of beacons from ContextHub by passing a tag to CCHBeaconService. Adding more tags to the same method call filters only beacons that have all tags on the same beacon.

Retrieving by ID

Retrieve a specific beacon from ContextHub by passing a beacon ID present either in the ContextHub developer portal or given to you as a dictionary response from the SDK at the key “id”.

Updating

Updating a beacon requires passing back a structure similar to the one returned to you from create/retrieve calls. ContextHub then updates the beacon, and triggers pushes to devices interested in beacons with that specific tag.

Deleting

Deleting a beacon is similar to updating, and requires passing a structure similar to one returned to you from create/retrieve calls. The beacon is deleted from ContextHub, then triggers pushes to devices interested in beacon deletions with those specific tags.

Geofences

Geofences are pre-defined areas of interest that allow your application to be notified when a device has entered or exited that region. Here’s how to use CCHGeofenceService to interact with geofences:

Creating

Creating a geofence contextual element in ContextHub is simple. Every geofence is defined by a latitude and longitude indicating their center and a radius in meters to create the perimeter. You can also create a standard CLCircularRegion class from the response for use in your app. After creation, [CCHSensorPipeline synchronize] must be called if you do not have to push enabled so the sensor pipeline is ready to generate geofence events.

Retrieving by Tag

Retrieve a group of geofences from ContextHub by passing a tag to CCHGeofenceService. Adding more tags to the same method call filters only geofence that have all tags on the same geofence.

Retrieving by ID

Retrieve a specific geofence from ContextHub by passing a geofence ID present either in the ContextHub developer portal or given to you as a dictionary response from the SDK at the key “id”.

Updating

Updating a geofence requires passing back a structure similar to the one returned to you from create/retrieve calls. ContextHub then updates the geofence, and triggers pushes to devices interested in geofence with that specific tag.

Deleting

Deleting a geofence is similar to updating, and requires passing a structure similar to one returned to you from create/retrieve calls. The geofence is deleted from ContextHub, then triggers pushes to devices interested in geofence deletions with those specific tags.

Devices

Devices in ContextHub currently represent the iOS and Android smartphones capable of interacting with the ContextHub server through provided SDKs and/or REST APIs. Each device has a unique identifier representing the device, as well as non-unique alias, tags, and tag_string used for identification and push notifications, plus other fields in the additional_info field describing specific device name and type information. last_profile is also available, which contains the last device profile from an event sent to the ContextHub server. Below are the methods you can use on the CCHDevice object to retrieve devices as well as update device alias and tags for your current device.

Device ID

Device ID is a unique 32-hexadecimal character string which persists throughout an app install and uniquely identifies a device in ContextHub. When used with push services enabled, it allows developers to abstract away more transient push tokens which are subject to change at any time. This is a read-only variable, it cannot be changed by the developer, and only changes in response to all applications with the first two subdomains of the bundle id from a developer being deleted from a user’s device. See Apple’s documentation on identifierForVendor for more information.

Retrieving by ID

Retrieve a specific device from ContextHub by passing a device ID present either in the ContextHub developer portal or given to you as a dictionary response from the SDK at the key “id”.

Retrieving by Alias

Retrieve a group of devices from ContextHub by passing an alias to CCHDevice.

Retrieving by Tag

Retrieve a group of devices from ContextHub by passing a tag to CCHDevice. Adding more tags to the same method call filters only devices that have all tags on the same device.

Setting Alias/Tag

Sets the alias and tag for the current device in ContextHub.

Logging

ContextHub allows for you to log specific events to the server from the iOS SDK to assist you in developing and monitoring your applications. The method of interaction is simple, allowing you to send a simple message and JSON object to the server.

Note that ContextHub does not cache these log requests, you must have an active Internet connection for them to be received.