Permissions Guide
Overview
Applications and clock faces developed for Fitbit OS must be granted permissions by the user, in order to use specific Device and Companion APIs.
The permissions system is primarily provided to inform users which apps are using which functionality of the system, and allow them to make informed decisions about whether they want to prevent its installation.
If a developer tries to utilize an API without first requesting the appropriate permission, the API will generate an error message, and the requested data will not be returned.
Note: Developers should be aware that permissions can be revoked by a user at any time, and developers should gracefully handle missing permissions in their application at runtime.
Available Permissions
The list of available permissions are as follows:
Activity
access_activity
Read user activities for today (distance, calories, steps, elevation and active minutes), daily goals, and activity history. The body presence sensor is used to detect if the device is being worn, or not.
Related APIs: Device.User-activity, Device.Body-presence.
Always-on Display
access_aod
Allows a developer to enable Always-on Display for their applications and clock faces.
NOTE: You can only use this permission with the Fitbit OS Simulator. Applications and clock faces must be authorized by Fitbit to use this permission due to the risk of hardware damage.
Related API: Device.Display
App Cluster Storage
access_app_cluster_storage
Allows a developer to persist data on the mobile phone and share it between all of their applications and clock faces.
Related API: Companion.App-cluster-storage
Calendars
Allows a developer to access calendar and event data from a user's mobile phone.
Related API: Companion.Calendars
Exercise
access_exercise
Allow the application to create entries within the user's Fitbit Activity Log.
Related APIs: Device.Exercise,
Heart Rate
access_heart_rate
Application may read the heart-rate sensor in real-time.
Related API: Device.Heart-rate.
Internet
access_internet
Companion may communicate with the Internet using your phone data connection.
Related API: Companion.Fetch
Location
access_location
Application and companion may request location data from the device or mobile GPS.
Related APIs: Device.Geolocation, Companion.Geolocation, Companion.Weather.
Run in background
run_background
Companion may run even when the application is not actively in use.
Related APIs: Companion.Location-change, Companion.Wake-interval
Sleep
Application may determine if the user is asleep or awake.
Related API: Device.Sleep
User Profile
access_user_profile
Read non-identifiable personal information (gender, age, height, weight, resting heart rate, basal metabolic rate, stride, heart rate zones).
Related API: Device.User-profile.
Requesting Permissions
In order to request permission to use specific APIs, edit the package.json
file. The permissions need to be added as follows:
{
"fitbit": {
...
"requestedPermissions": [
"access_activity",
"access_aod",
"access_app_cluster_storage",
"access_calendars",
"access_exercise",
"access_heart_rate",
"access_internet",
"access_location",
"run_background",
"access_sleep",
"access_user_profile",
"run_background"
]
}
}
When the application is installed, the user will be prompted to accept the permission requests.
Checking Permissions
In order to check permissions within code, you need to import the appbit API
on the device, or the companion API for the companion.
import { me as appbit } from "appbit";
if (!appbit.permissions.granted("access_heart_rate")) {
console.log("We're not allowed to read a users' heart rate!");
}
import { me as companion } from "companion";
if (!companion.permissions.granted("access_internet")) {
console.log("We're not allowed to access the internet!");
}
