Mobile SDK

Android (Kotlin)

Current Android (Kotlin) SDK Version: 3.1.6
Android Package can be found here﻿
Features
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.
﻿
Getting Started
Android Requirements
Android 9.0+
Android Setup Guide
To add the SDK to your project, you have to add the following to your project's build.gradle file in the repositories block.
JS
allprojects {
    repositories {
        // Other repositories
        maven {
            url 'https://gitlab.com/api/v4/projects/43396247/packages/maven'
        }
    }
}

allprojects {
    repositories {
        // Other repositories
        maven {
            url 'https://gitlab.com/api/v4/projects/43396247/packages/maven'
        }
    }
}
﻿
After that, add the following to your app's build.gradle file in the dependencies block.
build.gradle
dependencies {
    // Other dependencies
    implementation "com.spikeapi.sdk:spike-sdk:latest"
}
dependencies {
    // Other dependencies
    implementation "com.spikeapi.sdk:spike-sdk:latest"
}
﻿
Add the required health permissions to your android/app/src/main/res/values/config.xml. That allows you to fully utilize Spike SDK and to read the necessary data from apps that integrate with HealthConnect. Please refer to this guide to understand the specific permissions needed.
config.xml
<manifest>
    <uses-permission android:name="android.permission.health.READ_NUTRITION"/>
    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_STEPS"/>
    <uses-permission android:name="android.permission.health.READ_DISTANCE"/>
    <uses-permission android:name="android.permission.health.READ_ELEVATION_GAINED"/>
    <uses-permission android:name="android.permission.health.READ_RESTING_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY"/>
    <uses-permission android:name="android.permission.health.READ_FLOORS_CLIMBED"/>
    <uses-permission android:name="android.permission.health.READ_BASAL_METABOLIC_RATE"/>
    <uses-permission android:name="android.permission.health.READ_SLEEP"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_EXERCISE"/>
    <uses-permission android:name="android.permission.health.READ_SPEED"/>
    <uses-permission android:name="android.permission.health.READ_POWER"/>
    <uses-permission android:name="android.permission.health.READ_OXYGEN_SATURATION"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE"/>
    <uses-permission android:name="android.permission.health.READ_RESPIRATORY_RATE"/>
    <uses-permission android:name="android.permission.health.READ_WEIGHT"/>
    <uses-permission android:name="android.permission.health.READ_HEIGHT"/>
    <uses-permission android:name="android.permission.health.READ_BODY_FAT"/>
    <uses-permission android:name="android.permission.health.READ_LEAN_BODY_MASS"/>
    <uses-permission android:name="android.permission.health.READ_BODY_WATER_MASS"/>
    <uses-permission android:name="android.permission.health.READ_BODY_TEMPERATURE"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE"/>
    <uses-permission android:name="android.permission.health.READ_BONE_MASS"/>
</manifest>
<manifest>
    <uses-permission android:name="android.permission.health.READ_NUTRITION"/>
    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_STEPS"/>
    <uses-permission android:name="android.permission.health.READ_DISTANCE"/>
    <uses-permission android:name="android.permission.health.READ_ELEVATION_GAINED"/>
    <uses-permission android:name="android.permission.health.READ_RESTING_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY"/>
    <uses-permission android:name="android.permission.health.READ_FLOORS_CLIMBED"/>
    <uses-permission android:name="android.permission.health.READ_BASAL_METABOLIC_RATE"/>
    <uses-permission android:name="android.permission.health.READ_SLEEP"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_EXERCISE"/>
    <uses-permission android:name="android.permission.health.READ_SPEED"/>
    <uses-permission android:name="android.permission.health.READ_POWER"/>
    <uses-permission android:name="android.permission.health.READ_OXYGEN_SATURATION"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE"/>
    <uses-permission android:name="android.permission.health.READ_RESPIRATORY_RATE"/>
    <uses-permission android:name="android.permission.health.READ_WEIGHT"/>
    <uses-permission android:name="android.permission.health.READ_HEIGHT"/>
    <uses-permission android:name="android.permission.health.READ_BODY_FAT"/>
    <uses-permission android:name="android.permission.health.READ_LEAN_BODY_MASS"/>
    <uses-permission android:name="android.permission.health.READ_BODY_WATER_MASS"/>
    <uses-permission android:name="android.permission.health.READ_BODY_TEMPERATURE"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE"/>
    <uses-permission android:name="android.permission.health.READ_BONE_MASS"/>
</manifest>
﻿
Add an intent filter to your activity definition so that you can request the permissions at runtime.
XML
<intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
<intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
﻿
To handle Android 14 you also need to add activity-alias to your AndroidManifest.xml It is just a wrapper for the activity that requests permissions so no real activity is necessary.
XML
<activity-alias
    android:name="ViewPermissionUsageActivity"
    android:exported="true"
    android:targetActivity=".MainActivity"
    android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
</activity-alias>
<activity-alias
    android:name="ViewPermissionUsageActivity"
    android:exported="true"
    android:targetActivity=".MainActivity"
    android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
</activity-alias>
﻿
Spike SDK Usage
Initialization
Kotlin
// Prepare your API credentials
private const val AUTH_TOKEN = "aadaa48-33a6-4040-9a88-60edfae3f1e9"
private const val CLIENT_ID = "32485ab8-fb08-4c24-bac9-20daesads1107"
private const val CALLBACK_URL = "your.callback.url"

// 1 Create permissions launcher. In callback, all granted permissions are returned
// For Android 14, it's necessary to do in onCreate 
val permissionLauncher = registerForActivityResult(SpikeConnection.requestReadAuthorization()) {
    // onPermissionResult
}
// For compose, use appropriate remember call
val permissionLauncher = rememberLauncherForActivityResult(SpikeConnection.requestReadAuthorization()) {
    // onPermissionResult
}


// 2. Create a Spike object via setup function
val spikeConnection = SpikeConnection.createConnection(
    context = context,
    appId = CLIENT_ID,
    authToken = AUTH_TOKEN,
    customerEndUserId = UUID.randomUUID().toString(),
    callbackUrl = CALLBACK_URL,
    env = SpikeEnvironment.PROD,
    logger = Logger()
)

// 3. Retrieve the permissions set for the required data type and request access via your preferred method.
val permissions = spikeConnection.getRequiredHealthPermissionsMetadata(dataType)
permissionsLauncher.launch(permissions)

// You can check if all permissions were granted
val allPermissionsGranted = spikeConnection.hasHealthPermissionsGranted(permissions)

// You can manage all permissions and enable what was not enabled
spikeConnection.manageHealthConnect()

// You can check whether HealthConnect is available on the device
val healthConnectAvailability = spikeConnection.getHealthConnectAvailability()

// You can also revoke all permissions in one go if the user wants to
spikeConnection.revokeAllPermissions()
// Prepare your API credentials
private const val AUTH_TOKEN = "aadaa48-33a6-4040-9a88-60edfae3f1e9"
private const val CLIENT_ID = "32485ab8-fb08-4c24-bac9-20daesads1107"
private const val CALLBACK_URL = "your.callback.url"

// 1 Create permissions launcher. In callback, all granted permissions are returned
// For Android 14, it's necessary to do in onCreate 
val permissionLauncher = registerForActivityResult(SpikeConnection.requestReadAuthorization()) {
    // onPermissionResult
}
// For compose, use appropriate remember call
val permissionLauncher = rememberLauncherForActivityResult(SpikeConnection.requestReadAuthorization()) {
    // onPermissionResult
}


// 2. Create a Spike object via setup function
val spikeConnection = SpikeConnection.createConnection(
    context = context,
    appId = CLIENT_ID,
    authToken = AUTH_TOKEN,
    customerEndUserId = UUID.randomUUID().toString(),
    callbackUrl = CALLBACK_URL,
    env = SpikeEnvironment.PROD,
    logger = Logger()
)

// 3. Retrieve the permissions set for the required data type and request access via your preferred method.
val permissions = spikeConnection.getRequiredHealthPermissionsMetadata(dataType)
permissionsLauncher.launch(permissions)

// You can check if all permissions were granted
val allPermissionsGranted = spikeConnection.hasHealthPermissionsGranted(permissions)

// You can manage all permissions and enable what was not enabled
spikeConnection.manageHealthConnect()

// You can check whether HealthConnect is available on the device
val healthConnectAvailability = spikeConnection.getHealthConnectAvailability()

// You can also revoke all permissions in one go if the user wants to
spikeConnection.revokeAllPermissions()
﻿
Getting and using data
Kotlin
//Read your preferred data

// Get data for a data type
val extractedData = spikeConnection.extractData(dataType)

// Get data for a data type for a specific date range
val extractedData = spikeConnection.extractData(dataType, from, to)

// Get data and post it for a data type
val webhookJob = spikeConnection.extractAndPostData(dataType)

// Get data and post it for a data type for a specific date range
val webhookJob = spikeConnection.extractAndPostData(dataType, from, to)

// Data types are defined in SpikeDataTypes class

// Interact with the connection object

// You can close the connection, which makes it unusable after the fact
spikeConnection.close()

// You can retrieve the connection app id
val appId = spikeConnection.getAppId()

// You can retrieve the connection spike user id
val spikeUserId = spikeConnection.getSpikeUserId()

// You can retrieve the connection customer end user id
val customerEndUserId = spikeConnection.getCustomerEndUserId()

// You can retrieve the callback url
val callbackUrl = spikeConnection.getPostbackUrl()
//Read your preferred data

// Get data for a data type
val extractedData = spikeConnection.extractData(dataType)

// Get data for a data type for a specific date range
val extractedData = spikeConnection.extractData(dataType, from, to)

// Get data and post it for a data type
val webhookJob = spikeConnection.extractAndPostData(dataType)

// Get data and post it for a data type for a specific date range
val webhookJob = spikeConnection.extractAndPostData(dataType, from, to)

// Data types are defined in SpikeDataTypes class

// Interact with the connection object

// You can close the connection, which makes it unusable after the fact
spikeConnection.close()

// You can retrieve the connection app id
val appId = spikeConnection.getAppId()

// You can retrieve the connection spike user id
val spikeUserId = spikeConnection.getSpikeUserId()

// You can retrieve the connection customer end user id
val customerEndUserId = spikeConnection.getCustomerEndUserId()

// You can retrieve the callback url
val callbackUrl = spikeConnection.getPostbackUrl()
﻿
Logging
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.
Kotlin
// You can log events to the logger for easier debugging

// Log an event
logger.debug("Event information")

// To be able to use the logger, you have to implement the SpikeLogger interface and pass it in on connection creation
// An example implementation
class Logger : SpikeLogger {
    override fun debug(message: String) {
        Log.d("SpikeLogger", message)
    }
    
    // omitted code
}
// You can log events to the logger for easier debugging

// Log an event
logger.debug("Event information")

// To be able to use the logger, you have to implement the SpikeLogger interface and pass it in on connection creation
// An example implementation
class Logger : SpikeLogger {
    override fun debug(message: String) {
        Log.d("SpikeLogger", message)
    }
    
    // omitted code
}
﻿
Publishing application on Play Store
The SpikeSDK for Android devices integrates with Health Connect for data retrieval. Before publishing the application to the Play Store, application owners are required to complete the Developer Declaration Form available at the following link: Developer Declaration Form﻿
Please make sure that all types are selected from permissions section as shown here﻿
Data types
The following table shows the data types that can be read from HealthConnect API and the permissions that are required to read them.
Spike Data Type
HealthConnect permission
SpikeDataTypes.HEART_RATE
android.permission.health.READ_HEART_RATE
android.permission.health.READ_HEART_RATE_VARIABILITY
android.permission.health.READ_RESTING_HEART_RATE
SpikeDataTypes.DISTANCE
android.permission.health.READ_DISTANCE
SpikeDataTypes.ACTIVITIES_STREAM
android.permission.health.READ_EXERCISE
android.permission.health.READ_STEPS
android.permission.health.READ_DISTANCE
android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.READ_HEART_RATE
android.permission.health.READ_SPEED
android.permission.health.READ_ELEVATION_GAINED
android.permission.health.READ_POWER
android.permission.health.READ_HEART_RATE_VARIABILITY
SpikeDataTypes.ACTIVITIES_SUMMARY
android.permission.health.READ_STEPS
android.permission.health.READ_ACTIVE_CALORIES_BURNED
android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.READ_DISTANCE
android.permission.health.READ_ELEVATION_GAINED
android.permission.health.READ_FLOORS_CLIMBED
android.permission.health.READ_HEART_RATE
android.permission.health.READ_RESTING_HEART_RATE
android.permission.health.READ_BASAL_METABOLIC_RATE
SpikeDataTypes.BREATHING
android.permission.health.READ_RESPIRATORY_RATE
SpikeDataTypes.CALORIES
android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.READ_ACTIVE_CALORIES_BURNED
SpikeDataTypes.GLUCOSE
android.permission.health.READ_BLOOD_GLUCOSE
SpikeDataTypes.OXYGEN_SATURATION
android.permission.health.READ_OXYGEN_SATURATION
SpikeDataTypes.SLEEP
android.permission.health.READ_SLEEP
android.permission.health.READ_HEART_RATE
android.permission.health.READ_HEART_RATE_VARIABILITY
SpikeDataTypes.STEPS
android.permission.health.READ_STEPS
SpikeDataTypes.BODY
android.permission.health.READ_WEIGHT
android.permission.health.READ_HEIGHT
android.permission.health.READ_BODY_FAT
android.permission.health.READ_BONE_MASS
android.permission.health.READ_BLOOD_PRESSURE
android.permission.health.READ_BODY_TEMPERATURE
Classes
SpikeConnection
Class
Method
Description
SpikeConnection
createConnection
Creates a new SpikeConnection instance with the given user details.
Parameters: appId, authToken, customerEndUserId, logger
Returns: An instance of the SpikeConnection class.
SpikeConnection
hasHealthPermissionsGranted
Initiates a check on whether all health permissions have been granted to ensure the proper functioning of the SDK
Returns: True / False
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
getCustomerUserId
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. Optionally time range can be provided.
*On iOS, the maximum allowed single-query time interval is 90 days. If required, data of any longer time period can be accessed by iterating multiple queries of 90 days.
*On Android the earliest date data can be requested for 30 days before permission was given to the user's app to read from HealthConnect. 
There is no limit on how many days in total.
Parameters: dataType, from, to
Returns: An instance of SpikeData. The concrete type will depend on the data type requested
SpikeConnection
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. Optionally time range can be provided.
*On iOS, the maximum allowed single-query time interval is 90 days. If required, data of any longer time period can be accessed by iterating multiple queries of 90 days.
*On Android the earliest date data can be requested is 30 days before permission was given to the user's app to read from HealthConnect. There is no limit on how many days in total.
Parameters: dataType, from, to
SpikeConnection
manageHealthConnect
Opens your device's HealthConnect menu, where you can switch on and off data access for the app as well as delete data.
SpikeConnection
getHealthConnectAvailability
Provides information on whether HealthConnect is available on the device.
SpikeConnection
revokeAllPermissions
Revokes all granted health permissions for the application.
SpikeConnection
﻿
﻿
SpikeConnection
﻿
﻿
Errors and Exceptions
SpikeException
The abstract parent of all concrete exceptions.
SpikeConnectionIsClosedException
Thrown if any method is invoked on SpikeConnection or one of its subclasses after the connection has been closed.
SpikeInvalidCredentialsException
Thrown if the credentials provided are not recognised, i.e. are invalid or expired.
SpikeInvalidDateRangeException
Thrown if duration exceeds the allowed maximum or if ‘from’ date is greater than ‘to’ date. The message will contain a specific cause description.
SpikeInvalidCallbackUrlException
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.
SpikePermissionsNotGrantedException
Thrown when Spike SDK is unable to access the data due to permissions not being granted.
SpikeServerException
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.
Exceptions from HealthConnect Client
An exception can be thrown from HealthConnect Client itself and due to its nature has to be caught on the app side and cannot be wrapped on SDK side.
RemoteException
Thrown when data is requested too often on HealthConnect API. Can also be thrown when there is an internal error in HealthConnect API communication.

Spike Data Type	HealthConnect permission
SpikeDataTypes.HEART_RATE	android.permission.health.READ_HEART_RATE android.permission.health.READ_HEART_RATE_VARIABILITY android.permission.health.READ_RESTING_HEART_RATE
SpikeDataTypes.DISTANCE	android.permission.health.READ_DISTANCE
SpikeDataTypes.ACTIVITIES_STREAM	android.permission.health.READ_EXERCISE android.permission.health.READ_STEPS android.permission.health.READ_DISTANCE android.permission.health.READ_TOTAL_CALORIES_BURNED android.permission.health.READ_HEART_RATE android.permission.health.READ_SPEED android.permission.health.READ_ELEVATION_GAINED android.permission.health.READ_POWER android.permission.health.READ_HEART_RATE_VARIABILITY
SpikeDataTypes.ACTIVITIES_SUMMARY	android.permission.health.READ_STEPS android.permission.health.READ_ACTIVE_CALORIES_BURNED android.permission.health.READ_TOTAL_CALORIES_BURNED android.permission.health.READ_DISTANCE android.permission.health.READ_ELEVATION_GAINED android.permission.health.READ_FLOORS_CLIMBED android.permission.health.READ_HEART_RATE android.permission.health.READ_RESTING_HEART_RATE android.permission.health.READ_BASAL_METABOLIC_RATE
SpikeDataTypes.BREATHING	android.permission.health.READ_RESPIRATORY_RATE
SpikeDataTypes.CALORIES	android.permission.health.READ_TOTAL_CALORIES_BURNED android.permission.health.READ_ACTIVE_CALORIES_BURNED
SpikeDataTypes.GLUCOSE	android.permission.health.READ_BLOOD_GLUCOSE
SpikeDataTypes.OXYGEN_SATURATION	android.permission.health.READ_OXYGEN_SATURATION
SpikeDataTypes.SLEEP	android.permission.health.READ_SLEEP android.permission.health.READ_HEART_RATE android.permission.health.READ_HEART_RATE_VARIABILITY
SpikeDataTypes.STEPS	android.permission.health.READ_STEPS
SpikeDataTypes.BODY	android.permission.health.READ_WEIGHT android.permission.health.READ_HEIGHT android.permission.health.READ_BODY_FAT android.permission.health.READ_BONE_MASS android.permission.health.READ_BLOOD_PRESSURE android.permission.health.READ_BODY_TEMPERATURE

Class	Method	Description
SpikeConnection	createConnection	Creates a new SpikeConnection instance with the given user details. Parameters: appId, authToken, customerEndUserId, logger Returns: An instance of the SpikeConnection class.
SpikeConnection	hasHealthPermissionsGranted	Initiates a check on whether all health permissions have been granted to ensure the proper functioning of the SDK Returns: True / False
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	getCustomerUserId	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. Optionally time range can be provided. On iOS, the maximum allowed single-query time interval is 90 days. If required, data of any longer time period can be accessed by iterating multiple queries of 90 days. On Android the earliest date data can be requested for 30 days before permission was given to the user's app to read from HealthConnect. There is no limit on how many days in total. Parameters: dataType, from, to Returns: An instance of SpikeData. The concrete type will depend on the data type requested
SpikeConnection	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. Optionally time range can be provided. On iOS, the maximum allowed single-query time interval is 90 days. If required, data of any longer time period can be accessed by iterating multiple queries of 90 days. On Android the earliest date data can be requested is 30 days before permission was given to the user's app to read from HealthConnect. There is no limit on how many days in total. Parameters: dataType, from, to
SpikeConnection	manageHealthConnect	Opens your device's HealthConnect menu, where you can switch on and off data access for the app as well as delete data.
SpikeConnection	getHealthConnectAvailability	Provides information on whether HealthConnect is available on the device.
SpikeConnection	revokeAllPermissions	Revokes all granted health permissions for the application.
SpikeConnection
SpikeConnection

Did this page help you?

React Native

Swift