Exercise API
Variable: exercise
Type: Exercise
New in SDK 3.0
The Exercise API allows developers to build applications which mimic the behavior of the Fitbit Exercise app. Exercise data is automatically persisted within the Fitbit Activity Log.
import { me as appbit } from "appbit";
import exercise from "exercise";
if (!appbit.permissions.granted("access_exercise")) {
console.log("We're not allowed to create exercises!");
}
if (!appbit.permissions.granted("access_heart_rate")) {
console.log("We're not allowed to read a users' heart rate!");
}
if (!appbit.permissions.granted("access_location")) {
console.log("We're not allowed to read a users' location!");
}
exercise.start("Coding Workout", { gps: true });
if (exercise.state === "started") {
console.log(exercise.stats.calories || 0);
exercise.stop();
}
Interface: Exercise
New in SDK 3.0
Represents an exercise session.
Properties
readonly currentLapStats
ExerciseStats or undefined
Stats for the current lap or undefined if no exercise session has been started yet.
onstatechange
((this: Exercise, event: Event) => any) or undefined
Optional listener for exercise session state change events.
onswimlength
((this: Exercise, event: SwimLengthEvent) => any) or undefined
Optional listener for swim length events. NOTE: this may be called when a length has been completed, or when paused during a valid length.
readonly startDate
Date or undefined
Time at which the exercise session was first started or undefined if no session has been started yet.
readonly state
"started" or "paused" or "stopped"
Current state of the exercise session.
The possible state transitions for an exercise session are as follows:
+---------+ +---------+ +--------+
| | -- start() --> | | -- pause() ----> | |
| stopped | | started | | paused |
| | <-- stop() -- | | <-- resume() --> | |
+---------+ +---------+ +--------+
^ |
| |
+--------------------- stop()---------------------------+
Attempting an invalid state transition will throw an error.
readonly stats
ExerciseStats or undefined
Stats for the current exercise session or undefined if no session has been started yet.
readonly type
string or undefined
Type of the current exercise session or undefined if no session has been started yet.
Methods
pause()
Returns: void
Pause the current exercise session. A paused exercise session can be
resumed by calling resume(), or automatically, if it has been
automatically paused before, via the autopause option.
Throws: Throws an error if the exercise session is not in the "started" state.
resume()
Returns: void
Resume a paused exercise session.
Throws: Throws an error if the exercise session is not in the "paused" state.
splitLap()
Returns: ExerciseStats
Mark a lap. This will save and return the lap's ExerciseStats.
Throws: Throws an error if the exercise session is the "stopped" state.
start()
start(exerciseType: string, options?: ExerciseOptions | undefined)
Returns: void
Start a new exercise session.
exerciseType can be one of the following pre-defined exercise types:
runtreadmillhikingweightcyclingellipticalspinningyogastair-climbercircuit-trainingbootcamppilateskickboxingtennismartial-artsgolfwalkworkoutswim- or a custom exercise name.
Throws: Throws an error if options.gps is true, but
"access_location" was not granted, that is,
appbit.me.permissions.granted('access_location') returns false.
stop()
Returns: void
Stop the current exercise session. Once stopped, the exercise session ends and cannot be restarted. A new exercise session can be started by calling start().
Throws: Throws an error if the exercise session is not in the "started" or "paused" state.
Interface: ExerciseStats
New in SDK 3.0
Exercise stats, as measured since the start of the exercise session, or during a lap.
Properties
readonly activeTime
number
Time spent in the "started" state, in milliseconds.
readonly calories
number
Number of calories burned, in calories (kcal).
readonly distance
number
Distance travelled, in meters.
readonly elevationGain
number
Elevation gain, in meters.
readonly heartRate
{ readonly current: number; readonly max: number; readonly average: number; }
Heart rate, in beats per minute. NOTE: For swim exercises, heart
rate data is not available.
readonly pace
{ readonly current: number; readonly average: number; }
Pace, in seconds per kilometer.
readonly speed
{ readonly current: number; readonly max: number; readonly average: number; }
Speed, in m/s.
readonly steps
number
Number of steps taken.
readonly swimLengths
number or undefined
Cumulative number of lengths swum since the start of the exercise. NOTE: On devices that do not have gyroscope, swim stats are undefined.
Interface: SwimLengthEvent
New in SDK 3.0
The SwimLengthEvent interface represents the completion or interruption (via pause()) of a swim length. NOTE: On devices that do not have gyroscope, swim stats are undefined.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
dominantStroke
"back" or "unknown" or "freestyle" or "breast" or "butterfly"
Type of the dominant stroke during the current swim length.
readonly lengthDuration
number
Time elapsed since lengthStart, in seconds.
readonly lengthStart
number
Time elapsed between the start of the length and the start of the exercise, in seconds.
strokes
number
Number of strokes swum since the start of the current swim length.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: ExerciseOptions
New in SDK 3.0
Exercise options, passed as parameters to Exercise.start().
Properties
autopause
boolean or undefined
When set to true, the system will enable automatic pause/resume
movement detection for run or bike exercises. The option has no
effect for any other exercise.
disableTouch
boolean or undefined
When set to true, the system will disable touchscreen input. NOTE:
For swim exercises, this option will be forced to true.
gps
boolean or undefined
When set to true, the system will enable GPS (on-board or
connected) for the next exercise session. Only a subset of exercises
support GPS: run, hiking, walk, cycling and golf.
This option has no effect for any other exercise.
NOTE: The GPS connection may take 2-3 minutes to establish. For GPS-enabled exercises, to ensure proper distance & location tracking, it is recommended to wait for the GPS connection to be established before starting to track an exercise. Take the following code snippet as an example:
import exercise from "exercise";
import { geolocation } from "geolocation";
watchId = geolocation.watchPosition((position) => {
exercise.start("run", { gps: true });
geolocation.clearWatch(watchId);
});
poolLength
number or undefined
Pool length value, specified in meters, used by swim exercises.
NOTE: The default value is 25 meters.
