CSSensePlatform Class Reference

Inherits from	NSObject
Declared in	CSSensePlatform.h

Overview

This is the high-level interface for the iOS sense platform library. CSSensePlatform uses only class methods so there is never an instance of the CSSensePlatform. Instead, whenever

[CSSensePlatform initialize];

is called, this initializes a CSSensorStore object (a singleton) which coordinates most of the behavior in the app including local and remote persistency. Next to that, the CSSensePlatform provides functions for logging in, logging out, and registering a user, storing data in sensors, and retrieving data from sensors.

Initialization

`+ initialize`

Initializes the sense platform. This creates an instance of the CSSensorStore object.

+ (void)initialize

Declared In

CSSensePlatform.h

`+ initializeWithApplicationKey:`

Initialize the Sense Platform

+ (void)initializeWithApplicationKey:(NSString *)applicationKey

Parameters

`applicationKey`	the application key to identify this application to Common Sense

Declared In

CSSensePlatform.h

User management

`+ registerUser:withPassword:withEmail:`

+ (BOOL)registerUser:(NSString *)user withPassword:(NSString *)password withEmail:(NSString *)email

Parameters

`user`	the username
`password`	the plain text password
`email`	the user’s email address

Return Value

Wether the registration succeeded

Discussion

There are no specific requirements for the user (username) or password. Username cannot exist yet as a CommonSense user though. The email address does not have to be unique. The returning boolean indicates if registration was successfull. If it was, the user is automatically logged in (the developer does not have to do this anymore) and the credentials are stored in the settings.

Note that if registration fails, there is no way for the developer or end-user to know why it failed. This could be because of a username that is already in use, because of a problem on the cloud side, or because of a missing internet connection (among others).

Declared In

CSSensePlatform.h

`+ loginWithUser:andPassword:`

Set the credentials to log in on Common Sense (Deprecated: use loginWithUser:andPassword:andError instead)

+ (BOOL)loginWithUser:(NSString *)user andPassword:(NSString *)password

Parameters

`user`	Username used to identify the user (this does not necessarily have to be an email address)
`password`	The password connected to the user account (not hashed yet)

Discussion

This sets the credentials in the settings and logs in at commonsense cloud. If the login is successfull the kCSGeneralSettingUploadToCommonSense is enabled.

Note that if login fails, there is no way for the developer or end-user to know why it failed. This could be because of a wrong username / password combination, because of a problem on the cloud side, or because of a missing internet connection (among others).

Declared In

CSSensePlatform.h

`+ loginWithUser:andPassword:andError:`

Set the credentials to log in on Common Sense

+ (BOOL)loginWithUser:(NSString *)user andPassword:(NSString *)password andError:(NSError **)error

Parameters

`user`	Username used to identify the user (this does not necessarily have to be an email address)
`password`	The password connected to the user account (not hashed yet)
`error`	error

Return Value

whether the login succeeded

Discussion

This sets the credentials in the settings and logs in at commonsense cloud. If the login is successfull the kCSGeneralSettingUploadToCommonSense is enabled.

Returns a descriptive error if the login process fails.

Declared In

CSSensePlatform.h

`+ loginWithUser:andPasswordHash:`

Set the credentials to log in on Common Sense (Deprecated: use loginWIthUser:andPasswordHash:andError instead)

+ (BOOL)loginWithUser:(NSString *)user andPasswordHash:(NSString *)passwordHash

Parameters

`user`	username
`passwordHash`	md5 hased password

Return Value

whether the login is succsesful or not

Discussion

This sets the credentials in the settings and logs in at commonsense cloud. If the login is successfull the kCSGeneralSettingUploadToCommonSense is enabled.

Declared In

CSSensePlatform.h

`+ loginWithUser:andPasswordHash:andError:`

Set the credentials to log in on Common Sense

+ (BOOL)loginWithUser:(NSString *)user andPasswordHash:(NSString *)passwordHash andError:(NSError **)error

Parameters

`user`	username
`passwordHash`	md5 hased password
`error`	error

Return Value

whether the login is succsesful or not

Discussion

This sets the credentials in the settings and logs in at commonsense cloud. If the login is successfull the kCSGeneralSettingUploadToCommonSense is enabled.

Returns a descriptive error if the login process fails.

Declared In

CSSensePlatform.h

`+ logout`

Logout This removes credentials from the settings and stops the uploading to CommonSense.

Add a data point for a sensor that belongs to this device, using a JSON encoded string.

+ (void)addDataPointForSensor:(NSString *)sensorName displayName:(NSString *)displayName description:(NSString *)description dataType:(NSString *)dataType stringValue:(NSString *)value timestamp:(NSDate *)timestamp

Parameters

`sensorName`	the sensor name
`displayName`	the display name of the sensor
`description`	the deviceType/description of the sensor
`dataType`	the data type for the data of the sensor.
`value`	A JSON encoded data point
`timestamp`	An NSDate object describing the time and date the value object occured. It will be used to organize the storing of the data and to later fetch the data.

Discussion

If the sensor doesn’t exist it will be created. Data will first be stored locally, and is directly available from local storage. After an upload has occured it is also available remotely.

Declared In

CSSensePlatform.h

`+ addDataPointForSensor:displayName:description:dataType:jsonValue:timestamp:`

Add a data point for a sensor that belongs to this device, using a JSONSerializable value object.

+ (void)addDataPointForSensor:(NSString *)sensorName displayName:(NSString *)displayName description:(NSString *)description dataType:(NSString *)dataType jsonValue:(id)value timestamp:(NSDate *)timestamp

Parameters

`sensorName`	the sensor name
`displayName`	the display name of the sensor
`description`	the deviceType/description of the sensor
`dataType`	the data type for the data of the sensor.
`value`	The data object. Can be any JSONSerializable object (e.g. NSDictionary,NSArray, NSNumber, NSString).
`timestamp`	An NSDate object describing the time and date the value object occured. It will be used to organize the storing of the data and to later fetch the data.

Discussion

If the sensor doesn’t exist it will be created. Data will first be stored locally, and is directly available from local storage. After an upload has occured it is also available remotely.

Declared In

CSSensePlatform.h

`+ addDataPointForSensor:displayName:description:deviceType:deviceUUID:dataType:stringValue:timestamp:`

Add a data point for a sensor using a JSON encoded string object for the value, for a specific device.

+ (void)addDataPointForSensor:(NSString *)sensorName displayName:(NSString *)displayName description:(NSString *)description deviceType:(NSString *)deviceType deviceUUID:(NSString *)deviceUUID dataType:(NSString *)dataType stringValue:(id)value timestamp:(NSDate *)timestamp

Parameters

`sensorName`	the sensor name
`displayName`	the display name of the sensor
`description`	the deviceType/description of the sensor
`deviceType`	the type of the device the sensor should be attached to (nil for no device)
`deviceUUID`	the uuid of the device the sensor should be attached to (nil for no device)
`dataType`	the data type for the data of the sensor.
`value`	A JSON encoded data point
`timestamp`	An NSDate object describing the time and date the value object occured. It will be used to organize the storing of the data and to later fetch the data.

Discussion

If the sensor doesn’t exist it will be created. Data will first be stored locally, and is directly available from local storage. After an upload has occured it is also available remotely.

Declared In

CSSensePlatform.h

`+ addDataPointForSensor:displayName:description:deviceType:deviceUUID:dataType:jsonValue:timestamp:`

Add a data point for a sensor using a JSONSeriazable data object for the value, for a specific device.

+ (void)addDataPointForSensor:(NSString *)sensorName displayName:(NSString *)displayName description:(NSString *)description deviceType:(NSString *)deviceType deviceUUID:(NSString *)deviceUUID dataType:(NSString *)dataType jsonValue:(id)value timestamp:(NSDate *)timestamp

Parameters

`sensorName`	the sensor name
`displayName`	the display name of the sensor
`description`	the deviceType/description of the sensor
`deviceType`	the type of the device the sensor should be attached to (nil for no device)
`deviceUUID`	the uuid of the device the sensor should be attached to (nil for no device)
`dataType`	the data type for the data of the sensor.
`value`	The data object. Can be any JSONSerializable object (e.g. NSDictionary,NSArray, NSNumber, NSString).
`timestamp`	An NSDate object describing the time and date the value object occured. It will be used to organize the storing of the data and to later fetch the data.

Discussion

If the sensor doesn’t exist it will be created. Data will first be stored locally, and is directly available from local storage. After an upload has occured it is also available remotely.

Declared In

CSSensePlatform.h

`+ getDataForSensor:onlyFromDevice:nrLastPoints:`

Retrieve a number of values of a sensor from Common Sense.

+ (NSArray *)getDataForSensor:(NSString *)name onlyFromDevice:(bool)onlyFromDevice nrLastPoints:(NSInteger)nrLastPoints

Parameters

`name`	The name of the sensor to get data from
`onlyFromDevice`	Wether or not to only look through sensors that are part of this device. Searches all sensors, including those of this device, if set to NO
`nrLastPoints`	Number of points to retrieve, this function always returns the latest values for the sensor.

Return Value

an array of values, each value is a dictionary that describes the data point

Discussion

This only looks at remote data, not at locally stored data. You can be sure that the data that is returned is for the specific user account. Can only be used if the user is logged in.-

Declared In

CSSensePlatform.h

`+ getLocalDataForSensor:from:to:`

Retrieve all the sensor data stored locally between a certain time interval.

+ (NSArray *)getLocalDataForSensor:(NSString *)name from:(NSDate *)startDate to:(NSDate *)endDate

Parameters

`name`	The name of the sensor to get the data from
`startDate`	The date and time at which to start looking for datapoints
`endDate`	The date and time at which to stop looking for datapoints

Return Value

an array of values, each value is a dictonary that descirbes the data point

Discussion

Sensor data is stored in an SQLite table and can be retrieved by sensor and date. There are a few limitations on the storage:

It is kept for 30 days. Data older than 30 days is removed.
A maximum of 100 mb is kept. Users are likely to remove the app if there would be more storage space used. This should normally be ample for 30 days of data.
The total amount of storage is limited if the disk space of the device is smaller than what is needed by the.

These limitations are treated in a first in first out way. Hence, older data is removed first.

Warning: Sensordata is not stored in a user specific format. Hence, when the user logs out or the app starts to being used by a different user on the same device, the old settings and data remains accessible to the new user.

Declared In

CSSensePlatform.h

`+ getLocalDataForSensor:from:to:andOrder:withLimit:`

Retrieve all the sensor data stored locally between a certain time interval with a limit on the number of points that get returned.

+ (NSArray *)getLocalDataForSensor:(NSString *)name from:(NSDate *)startDate to:(NSDate *)endDate andOrder:(NSString *)order withLimit:(int)nrOfPoints

Parameters

`name`	The name of the sensor to get the data from
`startDate`	The date and time at which to start looking for datapoints
`endDate`	The date and time at which to stop looking for datapoints
`order`	Whether the returning datapoints are ordered in an ascending or descending way. Valid values are ‘ASC’ and ‘DESC’
`nrOfPoints`	Limit to the nr of points that will be returned. This will take into account the ordering to select only the latest (descending) or first (ascending)

Return Value

an array of values, each value is a dictonary that descirbes the data point

Discussion

Sensor data is stored in an SQLite table and can be retrieved by sensor and date. There are a few limitations on the storage:

It is kept for 30 days. Data older than 30 days is removed.
A maximum of 100 mb is kept. Users are likely to remove the app if there would be more storage space used. This should normally be ample for 30 days of data.
The total amount of storage is limited if the disk space of the device is smaller than what is needed by the.

These limitations are treated in a first in first out way. Hence, older data is removed first.

Declared In

CSSensePlatform.h

`+ removeLocalData`

Remove all sensor data that are stored locally

+ (void)removeLocalData

Discussion

Warning: This can be used to solve the issue that sensor data is not stored in a user specific format. Hence, applications that only stores the data locally could have issues when the user is changed (when login/logout occurs). In that case, the data from previous user will be shown to the next user.

Declared In

CSSensePlatform.h

`+ getLocalDataForSensor:andDeviceType:from:to:`

Retrieve all the sensor data stored locally between a certain time interval.

+ (NSArray *)getLocalDataForSensor:(NSString *)name andDeviceType:(NSString *)deviceType from:(NSDate *)startDate to:(NSDate *)endDate

Parameters

`name`	The name of the sensor to get the data from
`deviceType`	The name of the device type to get the sensors and data from
`startDate`	The date and time at which to start looking for datapoints
`endDate`	The date and time at which to stop looking for datapoints

Return Value

an arrat of values, each value is a dictonary that descirbes the data point

Declared In

CSSensePlatform.h

Permissions

`+ requestLocationPermissionWithDelegate:`

Ask the CSSensePlatform to request location permissions from the user. This will ask the user for kCLAuthorizationStatusAuthorizedAlways permissions, meaning the app can always obtain location updates. The function will present the location permission dialog to the user, asynchronously. After the user responds to this dialog by either granting or denying the permissions, the corresponding callback on the provided delegate will be called. Make sure the delegate implements the protocol! The reason we need a delegate object that implements predefined callback functions is that the permission request dialog is presented asynchronously to the user. That means that we would lose any callback context provided to this function. Using an object implementing a protocol, we can temporarily store a reference to the object and callback later when the user granted or denied the permissions. IMPORTANT: This function will do nothing on iOS < 8. IMPORTANT: If the user denies permission, the app will not run in the background until the user explicitly grants permission to the app in the iOS settings screen.

+ (void)requestLocationPermissionWithDelegate:(id<CSLocationPermissionProtocol>)delegate

Parameters

`delegate`	Object implementing the CSLocationPermissionProtocol protocol. A weak reference to this object will be stored, so don’t destroy it before the callback is called. Typically this will be a ViewController object.

Declared In

CSSensePlatform.h

`+ locationPermissionState`

Request the current location permission status for the app. This function will return one of three possible values: - kCLAuthorizationStatusNotDetermined: there is no permission status yet. In this case the permission should be asked from the user using requestLocationPermissionWithDelegate, or it will be done automatically once sensing is started. - kCLAuthorizationStatusDenied: the user has denied location permissions. In this case the app will not be able to run in the background, and the only way to remedy this is for the user to explicitly grant permission in the iOS -> settings screen. - kCLAuthorizationStatusAuthorizedAlways: the app has obtained the required permissions, no action needed.

+ (CLAuthorizationStatus)locationPermissionState

Declared In

CSSensePlatform.h

Miscellaneous

`+ getDeviceId`

Returns a unique identifier for the device.

+ (NSString *)getDeviceId

Return Value

Unique identifier for the device

Discussion

Note that Apple has made some changes to the way devices can be identified. From a privacy perspective they have decided to not create device specific identifiers anymore, but instead deliver app specific identifiers. This means that when a certain user removes the app and reinstalls, it might give a different identifier than before. The identifier will still be unique, but subsequent installs cannot be linked anymore using the device ID.

Declared In

CSSensePlatform.h

`+ giveFeedbackOnState:from:to:label:`

Give feedback on a state sensor so that it can be used to learn.

+ (void)giveFeedbackOnState:(NSString *)state from:(NSDate *)from to:(NSDate *)to label:(NSString *)label

Parameters

`state`	The state to give feedback on.
`from`	The start date for the feedback.
`to`	The end date for the feedback.
`label`	The label of the Feedback, e.g. ‘Sit’

This function isn’t operational. (Deprecated: This function is not operational anymore. If it is working for you that is dumb luck; don’t count on it.)

+ (void)synchronizeWithBloodPressureMonitor:(bpmCallBack)callback

Parameters

`callback`	I don’t know what this is .. ^JJ

Declared In

CSSensePlatform.h

`+ applyIVitalitySettings`

Setup the platform for use with iVitality (Deprecated: This function will be removed in future version)

+ (void)applyIVitalitySettings

Declared In

CSSensePlatform.h