Fitbit SDK FAQ

3. Crashes, Reliability and Performance

How can I fix an 'Internal Error' when side-loading?

An 'Internal Error' can prevent new code from being side-loaded on a watch if a previous version of the code was just deleted. Shutting down the watch, then restarting it, often works.

Why doesn't my clockface/app start?

Assuming your code is otherwise okay, it can fail to start for either of two reasons:

  • It's taking too long. If it runs fine on the simulator but not a physical device, this could be the problem. Your app gets about 10 seconds to relinquish the CPU after startup — and that includes on-device compilation and initialisation before your JavaScript even wakes up. This situation is hard to test for; commenting out chunks of your code may be crude but effective. See below for possible remedies.
  • It's running out of memory. Sometimes you get a message; sometimes you don't. This problem will usually occur on the simulator as well as physical devices, and you can check for the possibility using memory API calls. See below for possible remedies.

How can I make my clockface/app faster to start?

Don't initialise anything you don't have to immediately. For example, initialise elements for secondary screens only when they’re about to be displayed. If you structure such code into objects, you can also reduce memory use.

getElementById(), getElementsByClassName(), etc, can be quite slow. If your .gui is large but well structured, minimise calls to document.getElementById by using the element’s immediate parent, rather than ‘document’, if there are several elements beneath that parent. This will spare the startup code from having to look through the whole DOM every time.

tumber-items and tile-list items all have to be created from the .gui before your app starts. If you've got dozens of these, be careful.

There are many other detailed performance tips here.

How can I improve the reliability of companion-device communications?

Messaging isn't as reliable as file transfer. If possible, use the latter.

Communications are sometimes interrupted by the companion app being closed (usually at the whim of Android/iOS). You can specify a setting to try to keep the companion awake. In addition, sending a message from the watch to the companion should awaken it.

Consider using fitbit-asap, which is a third-party library that automatically resends the messages until an acknowledgment is returned from the peer.

Why does my clockface/app stop running?

Apps may be closed as a consequence of appTimeoutEnabled, which defaults to true. You can change this.

Clockfaces/apps will die if they run out of memory. Sometimes you'll get a console message about this; sometimes you won't. Check for this possibility using memory API calls. See below for suggestions.

Once started, your clockface/app should not hog the CPU for more than one second. If it does, the operating system may kill it, and you may see an 'App msg queue full' message. A code pattern to avoid this is here.

How can I reduce memory usage?

Use local variables in preference to global variables.

Use objects for more precise control over variable lifetime. This is especially beneficial if you have many variables that are only relevant occasionally; eg, when a user is using a secondary feature.

Don't use functions that are only called from one place.

If using large arrays of numbers, consider whether you can use a more memory-efficient structure (eg, Int16Array).

Offload large data structures to local storage.

Use CBOR rather than JSON for storage.

Using less images, or smaller or more compressed images, won't make any difference to your JavaScript memory usage. Your code only has to accommodate references (eg, variables) to the images; the actual images are allocated from storage elsewhere.

If using K-pay, you can decide to forego some of its features, and even do the payment UI and API calls yourself. See the K-pay documentation and source code for details.

There are many additional memory-saving tips here.

What known bugs are there in the operating system?

See here.

What known bugs are there in the SDK?

See here.