Fitbit SDK FAQ

1. Documentation and Support

Where is the official documentation?


What other official developer resources are there?

The source code for several clockfaces and apps is available on github.

The official documentation contains a link to a generous set of assets (icons, fonts, etc).

Where can I learn about Javascript?

Most of the 'smarts' in your clockface/app will be written in JavaScript. Here's a tutorial about it, and here's a good general reference. Beware that the JavaScript implementation used by Fitbit is customised and is not based on the latest standards, so Fitbit's official documentation is the final word.

Where can I learn about React (.jsx)?

React (.jsx) files are used to manage your clockface/app settings on the companion. Here's a good general explanation.

Where can I get Fitbit-specific development help?

Here's the official Fitbit SDK forum.

There's an unofficial Discord chat board here.

Both places are frequented by Fitbit staff and third-party developers.

Is there an official bug list for the firmware?

Alas, no. Search the forums and Discord (as best you can). If no joy, ask in one of those places.

What known bugs are there in the firmware?

  • Combo buttons don't respond to physical key presses when placed in nested SVG elements. Work-around: place combo buttons in the top-level SVG element, and use their display attribute to control their visibility.
  • onmouseup() is usually fired shortly after onmousedown() even if one's finger remains on the screen, as though the event is emulating a simple click. After onmouseup(), onmousemove() events can continue to occur. An official bug report has been filed. Some workarounds are here.
  • Rotating images that extend off the screen can result in cropping or other artefacts. This doesn't happen on the simulator, but only on physical devices.
  • Clockface/app icons sometimes don't appear or change straight away, due to over-zealous caching on the device. A restart may help.

How do I report bugs in the firmware?

In lieu of a publicly-accessible bug tracker, your best bet is to post on the forum or Discord. Fitbit staff see posts in either place, but may not acknowledge or respond.

If you want to be ultra-helpful, try to provide the following information:

  • Fitbit model & firmware version
  • Phone manufacturer, model & OS version
  • Brief description of the problem
  • Steps to reproduce
  • An export of the project source which has issues
  • iOS device logs. Here's how: recreate the problem, then put your phone in airplane mode. In the Fitbit mobile app, go to Account > Help > Contact Customer Support. Change the email address to something suitable, disable airplane mode and send the logs.
  • Android device logs. The preferred approach would be to use adb to capture logs while the issue is happening. If you can’t use adb, then use Android Settings > Developer > Bug Report
  • Fitbit OS Simulator logs (OS X: ~/Library/Logs/Fitbit OS Simulator/log.log. Windows: %USERPROFILE%\AppData\Roaming\Fitbit OS Simulator/log.log)

If your suggestion is for a new feature, you can post in the Feature Suggestions forum.

What known bugs are there in the SDK?

The official list of issues with the SDK is here.

You can contribute to the SDK by following the link on that page.

What SDK versions are there?


Fibit OS 1.2 - (Ionic)

Fibit OS 2.0 - (Ionic) or (Versa)

Fitbit OS 2.1 - (Ionic) or (Versa)

Fitbit OS 2.1.1 - (Ionic)


Fitbit OS2.2 - (Ionic) or (Versa)


Fitbit OS 3.0 - (Ionic) or (Versa)

What's the development roadmap?

The official Fitbit SDK development roadmap is here. Unfortunately, it isn't kept totally up-to-date.