ExerciseClient

interface ExerciseClient


Client which provides a way to subscribe to the health data of a device during an exercise.

Summary

Public functions

ListenableFuture<Void>

Adds an ExerciseGoal for an active exercise.

ListenableFuture<Void>

Clears the callback set using setUpdateCallback.

ListenableFuture<Void>

Ends the current exercise, if it has been started.

ListenableFuture<Void>

Flushes the sensors for the active exercise.

ListenableFuture<ExerciseCapabilities>

Returns the ExerciseCapabilities of this client for the device.

ListenableFuture<ExerciseInfo>

Returns the current ExerciseInfo.

ListenableFuture<Void>

Ends the current lap, calls ExerciseUpdateCallback.onLapSummaryReceived with data spanning the marked lap and starts a new lap.

ListenableFuture<Void>

Enables or disables auto pause/resume for the current exercise.

ListenableFuture<Void>

Sets the batching mode for the current exercise.

ListenableFuture<Void>

Pauses the current exercise, if it is currently started.

ListenableFuture<Void>

Prepares for a new exercise.

ListenableFuture<Void>

Removes an exercise goal for an active exercise.

ListenableFuture<Void>

Resumes the current exercise, if it is currently paused.

Unit

Sets the callback for the current ExerciseUpdate.

Unit

Calls to the callback will be executed using the specified Executor.

ListenableFuture<Void>

Starts a new exercise.

ListenableFuture<Void>

Updates the configurable exercise type attributes for the current exercise.

Extension functions

suspend Void

Adds an ExerciseGoal for an active exercise.

suspend Void

Clears the callback set using ExerciseClient.setUpdateCallback.

suspend Void

Ends the current exercise, if it has been started.

suspend Void

Flushes the sensors for the active exercise.

suspend ExerciseCapabilities

Returns the ExerciseCapabilities of this client for the device.

suspend ExerciseInfo

Returns the current ExerciseInfo.

suspend Void

Ends the current lap, calls ExerciseUpdateCallback.onLapSummaryReceived with data spanning the marked lap and starts a new lap.

suspend Void

Enables or disables auto pause/resume for the current exercise.

suspend Void

Sets the batching mode for the current exercise synchronously.

suspend Void

Pauses the current exercise, if it is currently started.

suspend Unit

Prepares for a new exercise.

suspend Void

Removes an exercise goal for an active exercise.

suspend Void

Resumes the current exercise, if it is currently paused.

suspend Unit

Starts a new exercise.

suspend Void

Updates the configurable exercise type attributes for the current exercise.

Public functions

addGoalToActiveExerciseAsync

Added in 1.0.0
fun addGoalToActiveExerciseAsync(exerciseGoal: ExerciseGoal<*>): ListenableFuture<Void>

Adds an ExerciseGoal for an active exercise.

Goals apply to only active exercises owned by the client, and will be invalidated once the exercise is complete.

Parameters
exerciseGoal: ExerciseGoal<*>

the ExerciseGoal to add to this exercise

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise goal has been added. This returned ListenableFuture fails if the calling app does not own the active exercise.

clearUpdateCallbackAsync

Added in 1.0.0
fun clearUpdateCallbackAsync(callback: ExerciseUpdateCallback): ListenableFuture<Void>

Clears the callback set using setUpdateCallback.

If this callback is not already registered then this will be a no-op.

Parameters
callback: ExerciseUpdateCallback

the ExerciseUpdateCallback to clear

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the callback has been cleared (or verified not to be set).

endExerciseAsync

Added in 1.0.0
fun endExerciseAsync(): ListenableFuture<Void>

Ends the current exercise, if it has been started.

Health Services will flush and then shut down the active sensors and return an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.USER_END to the ExerciseUpdateCallback. If the exercise has ended then this future will fail.

No additional metrics will be produced for the exercise and any on device persisted data about the exercise will be deleted after the summary has been sent back.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise has been ended or fails if the calling application does not own the active exercise.

flushAsync

Added in 1.0.0
fun flushAsync(): ListenableFuture<Void>

Flushes the sensors for the active exercise. This call should be used sparingly and will be subject to throttling by Health Services.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the flush has been completed or fails if the calling application does not own the active exercise.

getCapabilitiesAsync

Added in 1.0.0
fun getCapabilitiesAsync(): ListenableFuture<ExerciseCapabilities>

Returns the ExerciseCapabilities of this client for the device.

This can be used to determine what ExerciseTypes and DataTypes this device supports. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DataTypes or features (such as auto-pause) which are not enabled for the rejected ExerciseType.

getCurrentExerciseInfoAsync

Added in 1.0.0
fun getCurrentExerciseInfoAsync(): ListenableFuture<ExerciseInfo>

Returns the current ExerciseInfo.

This can be used by clients to determine if they or another app already owns an active exercise being tracked by Health Services. For example, if an app is killed and it learns it owns the active exercise it can register a new ExerciseUpdateCallback and pick tracking up from where it left off.

Returns
ListenableFuture<ExerciseInfo>

a ListenableFuture that contains information about the current exercise or fails if the calling application does not own the active exercise

markLapAsync

Added in 1.0.0
fun markLapAsync(): ListenableFuture<Void>

Ends the current lap, calls ExerciseUpdateCallback.onLapSummaryReceived with data spanning the marked lap and starts a new lap. If the exercise supports laps this method can be called at any point after an exercise has been started and before it has been ended regardless of the exercise status.

The metrics in the lap summary will start from either the start time of the exercise or the last time a lap was marked to the time this method is being called.

If there's no exercise being tracked or if the exercise does not support laps then this future will fail.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the lap has been marked successfully or fails if the calling application does not own the active exercise

overrideAutoPauseAndResumeForActiveExerciseAsync

Added in 1.0.0
fun overrideAutoPauseAndResumeForActiveExerciseAsync(enabled: Boolean): ListenableFuture<Void>

Enables or disables auto pause/resume for the current exercise.

Parameters
enabled: Boolean

a boolean to indicate if should be enabled or disabled

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the override has completed. This returned ListenableFuture fails if an exercise is not active for this app.

overrideBatchingModesForActiveExerciseAsync

Added in 1.0.0
fun overrideBatchingModesForActiveExerciseAsync(
    batchingModes: Set<BatchingMode>
): ListenableFuture<Void>

Sets the batching mode for the current exercise.

Parameters
batchingModes: Set<BatchingMode>

BatchingMode overrides for exercise updates. Passing an empty set will clear all existing overrides.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the override has completed. This returned ListenableFuture fails if an exercise is not active for this app.

pauseExerciseAsync

Added in 1.0.0
fun pauseExerciseAsync(): ListenableFuture<Void>

Pauses the current exercise, if it is currently started.

Before transitioning to ExerciseState.USER_PAUSED, Health Services will flush and return the sensor data. While the exercise is paused, active time and cumulative metrics such as distance will not accumulate. Instantaneous measurements such as speed and heart rate will continue to update if requested in the ExerciseConfig.

Note that GPS and other sensors may be stopped when the exercise is paused in order to conserve battery. This may happen immediately, or after some time. (The exact behavior is hardware dependent.) Should this happen, access will automatically resume when the exercise is resumed.

If the exercise is already paused then this method has no effect. If the exercise has ended then the returned future will fail.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise has been paused or fails if the calling application does not own the active exercise.

prepareExerciseAsync

Added in 1.0.0
fun prepareExerciseAsync(configuration: WarmUpConfig): ListenableFuture<Void>

Prepares for a new exercise.

Once called, Health Services will warmup the sensors based on the ExerciseType and requested DataTypes

If the calling app already has an active exercise in progress or if it does not have the required permissions, then this call returns a failed future. If another app owns the active exercise then this call will succeed.

Sensors available for warmup are GPS DataType.LOCATION and HeartRate DataType.HEART_RATE_BPM. Other DataTypes requested for warmup based on exercise capabilities will be a no-op for the prepare stage.

The DataType availability can be obtained through the ExerciseUpdateCallback.onAvailabilityChanged callback. ExerciseUpdates with the supported DataType DataPoint will also be returned in the ExerciseState.PREPARING state, though no aggregation will occur until the exercise is started.

If an app is actively preparing and another app starts tracking an active exercise then the preparing app should expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_SUPERSEDED to the ExerciseUpdateCallback indicating that their session has been superseded and ended. At that point no additional updates to availability or data will be sent until the app calls prepareExercise again.

Parameters
configuration: WarmUpConfig

the WarmUpConfig containing the desired exercise and data types

Returns
ListenableFuture<Void>

a ListenableFuture that completes once Health Services starts preparing the sensors or fails due to missing permissions or the app owning another active exercise.

removeGoalFromActiveExerciseAsync

Added in 1.0.0
fun removeGoalFromActiveExerciseAsync(exerciseGoal: ExerciseGoal<*>): ListenableFuture<Void>

Removes an exercise goal for an active exercise.

Takes into account equivalent milestones (i.e. milestones which are not equal but are different representation of a common milestone. e.g. milestone A for every 2kms, currently at threshold of 10kms, and milestone B for every 2kms, currently at threshold of 8kms).

Parameters
exerciseGoal: ExerciseGoal<*>

the ExerciseGoal to remove from this exercise

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise goal has been removed. This returned ListenableFuture fails if the exercise is not active, and will be a no-op if exerciseGoal has not been added in the past.

resumeExerciseAsync

Added in 1.0.0
fun resumeExerciseAsync(): ListenableFuture<Void>

Resumes the current exercise, if it is currently paused.

Once resumed active time and cumulative metrics such as distance will resume accumulating.

If the exercise has been started but is not currently paused this method has no effect. If the exercise has ended then the returned future will fail.

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise has been resumed or fails if the calling application does not own the active exercise.

setUpdateCallback

Added in 1.0.0
fun setUpdateCallback(callback: ExerciseUpdateCallback): Unit

Sets the callback for the current ExerciseUpdate.

This callback won't be called until the calling application prepares or starts an exercise. It will only receive updates from exercises tracked by this app.

If an exercise is in progress, the ExerciseUpdateCallback is immediately called with the associated ExerciseUpdate, and subsequently whenever the state is updated or an event is triggered. Health Services will cache ExerciseUpdates of an active exercise that are generated while a callback is not active (for example, due to the app getting killed) and deliver them as soon as the callback is registered again. If the client fails to maintain a live ExerciseUpdateCallback for at least five minutes during the duration of the exercise Health Services can decide to terminate the exercise automatically. If this occurs, clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_MISSING_LISTENER to the ExerciseUpdateCallback indicating that their exercise has been automatically ended due to the lack of callback.

Calls to the callback will be executed on the main application thread. To control where to execute the callback, see the overload taking an Executor. To remove the callback use clearUpdateCallbackAsync.

Parameters
callback: ExerciseUpdateCallback

the ExerciseUpdateCallback that will receive updates from Health Services

setUpdateCallback

Added in 1.0.0
fun setUpdateCallback(executor: Executor, callback: ExerciseUpdateCallback): Unit

Calls to the callback will be executed using the specified Executor. To execute the callback on the main application thread use the overload without the Executor.

Parameters
executor: Executor

the Executor on which callback will be invoked

callback: ExerciseUpdateCallback

the ExerciseUpdateCallback that will receive updates from Health Services

startExerciseAsync

Added in 1.0.0
fun startExerciseAsync(configuration: ExerciseConfig): ListenableFuture<Void>

Starts a new exercise.

Once started, Health Services will begin collecting data associated with the exercise.

Since Health Services only allows a single active exercise at a time, this will terminate any active exercise currently in progress before starting the new one. If this occurs, clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_SUPERSEDED to the ExerciseUpdateCallback indicating that their exercise has been superseded and that no additional updates will be sent. Clients can use getCurrentExerciseInfoAsync (described below) to check if they or another app has an active exercise in-progress.

The exercise will be terminated and clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_MISSING_LISTENER (indicating that their exercise has been automatically ended due to the lack of callback) if there is ever a five minute period where no ExerciseUpdateCallback is registered. A notable example is if the process with the registered ExerciseUpdateCallback dies and does not re-register the ExerciseUpdateCallback within five minutes.

Clients should only request ExerciseTypes, DataTypes, goals, and auto-pause enabled that matches the ExerciseCapabilities returned by getCapabilitiesAsync since Health Services will reject requests asking for unsupported configurations.

Parameters
configuration: ExerciseConfig

the ExerciseConfig describing this exercise

Returns
ListenableFuture<Void>

a ListenableFuture that completes once the exercise has been started or fails due to the application missing the required permissions or requesting metrics which are not supported for the given ExerciseType.

updateExerciseTypeConfigAsync

Added in 1.0.0
fun updateExerciseTypeConfigAsync(exerciseTypeConfig: ExerciseTypeConfig): ListenableFuture<Void>

Updates the configurable exercise type attributes for the current exercise.

This can be used to update the configurable attributes for the ongoing exercise, as defined in ExerciseTypeConfig. Minimum Exercise API version for this function is 3.

Parameters
exerciseTypeConfig: ExerciseTypeConfig

a configuration containing the new values for the configurable attributes

Returns
ListenableFuture<Void>

a ListenableFuture that completes when the configuration has been updated.

Extension functions

addGoalToActiveExercise

suspend fun ExerciseClient.addGoalToActiveExercise(exerciseGoal: ExerciseGoal<*>): Void

Adds an ExerciseGoal for an active exercise.

Goals apply to only active exercises owned by the client, and will be invalidated once the exercise is complete.

Parameters
exerciseGoal: ExerciseGoal<*>

the ExerciseGoal to add to this exercise

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

clearUpdateCallback

suspend fun ExerciseClient.clearUpdateCallback(callback: ExerciseUpdateCallback): Void

Clears the callback set using ExerciseClient.setUpdateCallback.

If this callback is not already registered then this will be a no-op.

Parameters
callback: ExerciseUpdateCallback

the ExerciseUpdateCallback to clear

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

suspend fun ExerciseClient.endExercise(): Void

Ends the current exercise, if it has been started.

Health Services will flush and then shut down the active sensors and return an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.USER_END to the ExerciseUpdateCallback. If the exercise has already ended then this call fails with a HealthServicesException.

No additional metrics will be produced for the exercise and any on device persisted data about the exercise will be deleted after the summary has been sent back.

Throws
androidx.health.services.client.HealthServicesException

if exercise has already ended or if Health Service fails to process the call

suspend fun ExerciseClient.flush(): Void

Flushes the sensors for the active exercise. This call should be used sparingly and will be subject to throttling by Health Services.

Throws
androidx.health.services.client.HealthServicesException

if the Health Service fails to process the request

suspend fun ExerciseClient.getCapabilities(): ExerciseCapabilities

Returns the ExerciseCapabilities of this client for the device.

This can be used to determine what ExerciseTypes and DataTypes this device supports. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DataTypes or features (such as auto-pause) which are not enabled for the rejected ExerciseType.

Returns
ExerciseCapabilities

a the ExerciseCapabilities for this device

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

getCurrentExerciseInfo

suspend fun ExerciseClient.getCurrentExerciseInfo(): ExerciseInfo

Returns the current ExerciseInfo.

This can be used by clients to determine if they or another app already owns an active exercise being tracked by Health Services. For example, if an app is killed and it learns it owns the active exercise it can register a new ExerciseUpdateCallback and pick tracking up from where it left off.

Returns
ExerciseInfo

a ExerciseInfo that contains information about the current exercise

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

suspend fun ExerciseClient.markLap(): Void

Ends the current lap, calls ExerciseUpdateCallback.onLapSummaryReceived with data spanning the marked lap and starts a new lap. If the exercise supports laps this method can be called at any point after an exercise has been started and before it has been ended regardless of the exercise status.

The metrics in the lap summary will start from either the start time of the exercise or the last time a lap was marked to the time this method is being called.

Throws
androidx.health.services.client.HealthServicesException

If there's no exercise being tracked or if Health Service fails to process the call

overrideAutoPauseAndResumeForActiveExercise

suspend fun ExerciseClient.overrideAutoPauseAndResumeForActiveExercise(
    enabled: Boolean
): Void

Enables or disables auto pause/resume for the current exercise.

Parameters
enabled: Boolean

a boolean to indicate if should be enabled or disabled

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

overrideBatchingModesForActiveExercise

suspend fun ExerciseClient.overrideBatchingModesForActiveExercise(
    batchingModes: Set<BatchingMode>
): Void

Sets the batching mode for the current exercise synchronously.

Parameters
batchingModes: Set<BatchingMode>

BatchingMode overrides for exercise updates. Passing an empty set will clear all existing overrides.

Throws
androidx.health.services.client.HealthServicesException

if an exercise is not active for this app or Health Service fails to process the call

suspend fun ExerciseClient.pauseExercise(): Void

Pauses the current exercise, if it is currently started.

Before transitioning to ExerciseState.USER_PAUSED, Health Services will flush and return the sensor data. While the exercise is paused, active time and cumulative metrics such as distance will not accumulate. Instantaneous measurements such as speed and heart rate will continue to update if requested in the ExerciseConfig.

Note that GPS and other sensors may be stopped when the exercise is paused in order to conserve battery. This may happen immediately, or after some time. (The exact behavior is hardware dependent.) Should this happen, access will automatically resume when the exercise is resumed.

If the exercise is already paused then this method has no effect. If the exercise has ended then HealthServicesException is thrown.

Throws
androidx.health.services.client.HealthServicesException

if the exercise has ended or if Health Service fails to process the call

suspend fun ExerciseClient.prepareExercise(configuration: WarmUpConfig): Unit

Prepares for a new exercise.

Once called, Health Services will warmup the sensors based on the ExerciseType and requested DataTypes.

If the calling app already has an active exercise in progress or if it does not have the required permissions, then this call throws HealthServicesException. If another app owns the active exercise then this call will succeed.

Sensors available for warmup are GPS DataType.LOCATION and HeartRate DataType.HEART_RATE_BPM. Other DataTypes requested for warmup based on exercise capabilities will be a no-op for the prepare stage.

The DataType availability can be obtained through the ExerciseUpdateCallback.onAvailabilityChanged callback. ExerciseUpdates with the supported DataType DataPoint will also be returned in the ExerciseState.PREPARING state, though no aggregation will occur until the exercise is started.

If an app is actively preparing and another app starts tracking an active exercise then the preparing app should expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_SUPERSEDED to the ExerciseUpdateCallback indicating that their session has been superseded and ended. At that point no additional updates to availability or data will be sent until the app calls prepareExercise again.

Parameters
configuration: WarmUpConfig

the WarmUpConfig containing the desired exercise and data types

Throws
androidx.health.services.client.HealthServicesException

if the calling app already has an active exercise in progress or if Health Service fails to process the call

java.lang.SecurityException

if the calling app does not have the required permissions

removeGoalFromActiveExercise

suspend fun ExerciseClient.removeGoalFromActiveExercise(
    exerciseGoal: ExerciseGoal<*>
): Void

Removes an exercise goal for an active exercise.

Takes into account equivalent milestones (i.e. milestones which are not equal but are different representation of a common milestone. e.g. milestone A for every 2kms, currently at threshold of 10kms, and milestone B for every 2kms, currently at threshold of 8kms).

Parameters
exerciseGoal: ExerciseGoal<*>

the ExerciseGoal to remove from this exercise

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

suspend fun ExerciseClient.resumeExercise(): Void

Resumes the current exercise, if it is currently paused.

Once resumed active time and cumulative metrics such as distance will resume accumulating.

If the exercise has been started but is not currently paused this method has no effect. If the exercise has ended then HealthServicesException is thrown.

Throws
androidx.health.services.client.HealthServicesException

if the exercise has ended or if Health Service fails to process the call

suspend fun ExerciseClient.startExercise(configuration: ExerciseConfig): Unit

Starts a new exercise.

Once started, Health Services will begin collecting data associated with the exercise.

Since Health Services only allows a single active exercise at a time, this will terminate any active exercise currently in progress before starting the new one. If this occurs, clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED, indicating that their exercise has been superseded and that no additional updates will be sent. Clients can use getCurrentExerciseInfo (described below) to check if they or another app has an active exercise in-progress.

The exercise will be terminated and clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_MISSING_LISTENER (indicating that their exercise has been automatically ended due to the lack of callback) if there is ever a five minute period where no ExerciseUpdateCallback is registered. A notable example is if the process with the registered ExerciseUpdateCallback dies and does not re-register the ExerciseUpdateCallback within five minutes.

Clients should only request ExerciseTypes, DataTypes, goals, and auto-pause enabled that matches the ExerciseCapabilities returned by getCapabilities since Health Services will reject requests asking for unsupported configurations.

Parameters
configuration: ExerciseConfig

the ExerciseConfig describing this exercise

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

java.lang.SecurityException

if the calling app does not have the required permissions

updateExerciseTypeConfig

suspend fun ExerciseClient.updateExerciseTypeConfig(
    exerciseTypeConfig: ExerciseTypeConfig
): Void

Updates the configurable exercise type attributes for the current exercise.

This can be used to update the configurable attributes for the ongoing exercise, as defined in ExerciseTypeConfig.

Parameters
exerciseTypeConfig: ExerciseTypeConfig

configuration containing the new values for the configurable attributes

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call