Android (Kotlin)
Spike Android SDK is a library on top of Android HealthConnect that
- helps with the extraction of data.
- pushes data to SpikeAPI and delivers standardized data.
Do note, that according to Google's specification, you should only use SDK while the consuming app is in the foreground. Please make sure that you follow the advice shown here before releasing the app to production, especially the mandatory declaration.
- Android 9.0+
To add the SDK to your project, you have to add the following to your project's build.gradle file in the repositories block.
After that, you have to add the following to your app's build.gradle file in the dependencies block.
First of all, you have to add the required health permissions to your AndroidManifest.xml. That allows you to fully utilize Spike SDK and to read the necessary data from apps that integrate with HealthConnect.
As well as you have to add an intent filter to your activity definition so that you can request the permissions at runtime.
Internally, the Android SDK supports logging on various levels to assist with troubleshooting. However, the SDK expects a concrete logging implementation to be provided externally to avoid imposing additional third-party dependencies on library users. This can be done by implementing the SpikeLogger class and providing it when creating or unpacking a connection.
Below is an example of how to implement a simple console logger.
SpikeDataTypes.activitiesStream SpikeDataTypes.activitiesSummary SpikeDataTypes.breathing SpikeDataTypes.calories SpikeDataTypes.distance
SpikeDataTypes.glucose SpikeDataTypes.heart SpikeDataTypes.oxygenSaturation SpikeDataTypes.sleep SpikeDataTypes.steps
Class | Method | Description |
Spike | createConnection | Creates a new SpikeConnection instance with the given user details. Parameters: appId, authToken, customerEndUserId, logger Returns: An instance of the SpikeConnection class. |
Spike | createConnection | Creates a new connection instance with the given user details that is capable of delivering data to the customer backend via webhooks. Parameters: appId, authToken, customerEndUserId, callbackUrl, logger Returns: An instance of the SpikeWebhookConnection class. |
Spike | unpackConnection | Restores a connection instance from a previously serialised state. A connection cannot be unpacked if a strong reference to a connection with the same session ID already exists. Parameters: connection, logger Returns: An instance of the SpikeConnection or SpikeWebhookConnection class. The method return type should be that of a base class, i.e., SpikeConnection. |
Spike | ensurePermissionsAreGranted | Verifies that platform-specific permissions corresponding to the Spike data types provided are granted. In the event that some permissions are not granted, a platform-specific permissions dialogue will be presented to the end-user. This method should only be invoked from a UI component Parameters: permissions (Set<SpikeDataType>) |
Class | Method | Description |
SpikeConnection | getAppId | Retrieves the unique Spike application identifier. Returns: string |
SpikeConnection | getSpikeEndUserId | Retrieves the unique identifier assigned to the end-user by Spike. Returns: string |
SpikeConnection | getCustomerEndUserId | Retrieves the unique identifier assigned to the end-user by the customer. Returns: string |
SpikeConnection | close | Terminates any ongoing connections with Spike’s backend servers, clears any caches, and removes provided user details and tokens from the memory. Once the connection is closed, it cannot be used, and any method other than close() will throw a SpikeConnectionIsClosed exception. |
SpikeConnection | extractData | Extracts local device data for the current date in the end-user’s time zone. Parameters: dataType(SpikeDataType) Returns: An instance of SpikeData. The concrete type will depend on the data type requested. |
SpikeConnection | extractData | Extracts local device data for the given time range. The maximum allowed single-query time interval is 7 days. If required, data of any longer time period can be accessed by iterating multiple queries of 7 days. Parameters: dataType(SpikeDataType), from(DateTime), to(DateTime) Returns: An instance of SpikeData. The concrete type will depend on the data type requested. |
SpikeConnection | pack | Creates a string representation of the connection state. This method facilitates the persistence of connections. Returns: String |
Class | Method | Description |
SpikeWebhookConnection | getAppId | Retrieves the unique Spike application identifier. Returns: string |
SpikeWebhookConnection | getSpikeEndUserId | Retrieves the unique identifier assigned to the end-user by Spike. Returns: string |
SpikeWebhookConnection | getCustomerEndUserId | Retrieves the unique identifier assigned to the end-user by the customer. Returns: string |
SpikeWebhookConnection | getCallbackUrl | Returns the URL that will receive webhook notifications. |
SpikeWebhookConnection | close | Terminates any ongoing connections with Spike’s backend servers, clears any caches, and removes provided user details and tokens from the memory. Once the connection is closed, it cannot be used, and any method other than close() will throw a SpikeConnectionIsClosed exception. |
SpikeWebhookConnection | extractData | Extracts local device data for the current date in the end-user’s time zone. Parameters: dataType(SpikeDataType) Returns: An instance of SpikeData. The concrete type will depend on the data type requested. |
SpikeWebhookConnection | extractData | Extracts local device data for the given time range. The maximum allowed single-query time interval is 7 days. If required, data of any longer time period can be accessed by iterating multiple queries of 7 days. Parameters: dataType(SpikeDataType), from(DateTime), to(DateTime) Returns: An instance of SpikeData. The concrete type will depend on the data type requested. |
SpikeWebhookConnection | extractAndPostData | Extracts local device data for the current date in the local user time zone and sends it as a webhook notification to the customer’s backend. Parameters: dataType(SpikeDataType) |
SpikeWebhookConnection | extractAndPostData | Extracts local device data for the given time range and sends it as a webhook notification to the customer’s backend. Parameters: dataType(SpikeDataType), from(DateTime), to(DateTime) |
SpikeWebhookConnection | enableBackgroundDelivery | Enables background data delivery for selected data types. No-op on Android (for now). Parameters: dataType(SpikeDataType) |
SpikeWebhookConnection | pack | Creates a string representation of the connection state. This method facilitates the persistence of connections. Returns: String |
The abstract parent of all concrete exceptions.
Thrown if an attempt to unpack a Spike connection is made while a strong reference to the same connection already exists.
Thrown if any method is invoked on SpikeConnection or one of its subclasses after the connection has been closed.
Thrown if the credentials provided are not recognised, i.e. are invalid or expired.
Thrown if duration exceeds the allowed maximum or if ‘from’ date is greater than ‘to’ date. The message will contain a specific cause description.
Thrown if the callback URL is not a valid URL, does not have HTTPS schema, or is not a sub-URL of the main callback URL configured for the application. The exception message will contain a specific reason.
Thrown when a connection cannot be serialised to a packed state. The exception cause will contain the underlying error.
Thrown when Spike SDK is unable to access the data due to permissions not being granted.
Whenever any operation with the Spike backend fails and the error does not fall into any of the above exceptions. The exception cause will contain the underlying error.
Thrown when a connection cannot be deserialised from a packed state. The exception cause will contain the underlying error.