> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spikeapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK Usage Guide

> Start getting Spike data in 3 steps using Spike SDK for Android platform.

## Step 1: Create a Spike Connection

To set up the Spike SDK create `SpikeConnectionV3` instance with your Spike application id, application user id and signature unique to each of your application users (more on generating signatures [here](/api-docs/authentication)):

```kotlin theme={null}

val spikeConnection = SpikeConnectionAPIv3.createConnection(
    applicationId = 1000,
    signature = "signature",
    endUserId = "user-id",
    context = context
)
```

## Step 2: Ask User for Permissions

If you want to read data from Android Health Connect, you have to ensure the user gives your app permissions.
First, you have to check if Health Connect is available on users' phone:

```kotlin theme={null}
val hcAvailability = spikeConnection.checkHealthConnectAvailability()
```

where

```kotlin theme={null}
public enum class HealthConnectAvailabilityStatus(public val value: String) {
    /**
     * The Health Connect SDK is unavailable on this device at the time. This can be due to the
     * device running a lower than required Android Version. Apps should hide any integration
     * points to Health Connect in this case.
     */
    NOT_INSTALLED("NOT_INSTALLED"),

    /**
     * The Health Connect SDK APIs are currently unavailable, the provider is either not installed
     * or needs to be updated. Apps may choose to redirect to package installers to find a suitable
     * APK.
     */
    UPDATE_REQUIRED("UPDATE_REQUIRED"),

    /**
     * The Health Connect SDK APIs are available.
     */
    INSTALLED("INSTALLED"),
}

```

If an update is required, you can use Spike helper to open Play Store for user to install Health Connect:

```kotlin theme={null}
spikeConnection.openHealthConnectInstallation()
```

If Health Connect is installed, you can get permissions that are needed and a list of already provided permissions:

```kotlin theme={null}
// HC integration has to be enabled in Spike SDK connection before
// using further methods for reading data or managing permissions:
spikeConnection.enableHealthConnectIntegration()

val permissionManager = spikeConnection.getHealthConnectPermissionManager()
val requiredPermissions = permissionManager.getPermissions(
    statisticsTypes = setOf(StatisticsType.STEPS, StatisticsType.DISTANCE_TOTAL)
)

val grantedPermissions = permissionManager.getGrantedPermissions()

```

If you have missing permissions, you can ask Android to present the user with a modal asking user for permission to read the data. Example for Compose:

```kotlin theme={null}
val permissionLauncher = rememberLauncherForActivityResult(
    permissionManager.getRequestPermissionResultContract(),
    onResult = {
        
    }
)
```

<Note>
  Please note that users might only grant partial permissions. In such cases, it’s up to you to decide whether your app can function effectively
  with limited access. The Spike SDK itself will still operate even without full permissions; however, it may result in no data being returned in
  certain scenarios. Conversely, if your app has been granted additional permissions beyond the minimum required for specific data types, we may
  enhance certain entries by incorporating data sourced from other types (e.g., identifying manually entered data).
</Note>

<Info>
  You can now use `StatisticsFilter(providers = listOf(Provider.HEALTH_CONNECT))` to specifically retrieve data from Health Connect. Alternatively, you can omit the providers parameter entirely and allow Spike to choose the most suitable data source based on your request.
</Info>

## Step 3: Get Data

<Note>
  The maximum permitted query date range is 90 days
</Note>

There are four types of data you can retrieve from Spike:

* **[Statistics](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3/-spike-connection-a-p-iv3/get-statistics.html)** are calculated values derived from records.
* **[Activities](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3/-spike-connection-a-p-iv3/get-activities.html)** are data about user's activities or workouts.
* **[Sleep](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3/-spike-connection-a-p-iv3/get-sleep.html)** is data about user's sleep.
* **[Records](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3/-spike-connection-a-p-iv3/get-records.html)** consist of the raw data points collected from user devices or applications.

### Statistics

Get daily statistics for steps and total distance from health Connect:

```kotlin theme={null}
val dailyStatistics = spikeConnection.getStatistics(
    types = setOf(StatisticsType.STEPS, StatisticsType.DISTANCE_TOTAL),
    from = LocalDate.now().minusWeeks(1).atStartOfDay(ZoneId.systemDefault()).toInstant(),
    to = Instant.now(),
    interval = StatisticsInterval.DAY,
    filter = StatisticsFilter(providers = listOf(Provider.HEALTH_CONNECT))
)
```

Reference:

* [StatisticType](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-statistics-type/index.html)
* [StatisticsInterval](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-statistics-interval/index.html)
* [StatisticsFilter](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-statistics-filter/index.html)
* [Statistic](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-statistic/index.html)

### Records

Get all records we have from Garmin provider:

```kotlin theme={null}
val records = spikeConnection.getRecords(
    types = setOf(MetricType.STEPS_TOTAL, MetricType.CALORIES_BURNED_TOTAL),
    from = LocalDate.now().minusWeeks(1).atStartOfDay(ZoneId.systemDefault()).toInstant(),
    to = Instant.now(),
    filter = StatisticsFilter(providers = listOf(Provider.HEALTH_CONNECT))
)
```

Reference:

* [MetricType](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-metric-type/index.html)
* [StatisticsFilter](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-statistics-filter/index.html)
* [Record](https://spike_api.gitlab.io/spike-android-sdk/sdk/com.spikeapi.apiv3.datamodels/-record/index.html)