Exercise API
chevron down
 

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:

  • run
  • treadmill
  • hiking
  • weight
  • cycling
  • elliptical
  • spinning
  • yoga
  • stair-climber
  • circuit-training
  • bootcamp
  • pilates
  • kickboxing
  • tennis
  • martial-arts
  • golf
  • walk
  • workout
  • swim
  • 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.