Migration Guide
chevron down
back search icon cancel search
 
 

SDK Migration Guide

Overview

To ensure that your application continues to function correctly after upgrading the SDK version we have provided this migration guide to identify the breaking changes between each version of the SDK.

If you are jumping more than one SDK version when upgrading your application, you will need to check the changes in each version between your current and the latest SDK version.

SDK 4.x to 5.0

Migration from SDK 4.x to 5.0 requires careful consideration due to some breaking changes in the structure of a project.

The new build targets for atlas (Fitbit Versa 3) and vulcan (Fitbit Sense) are SDK 5.0 only. Developers cannot mix SDK 4.x and SDK 5.x build targets in a single project, remember to remove incompatible build targets.

  • BREAKING: /resources/index.gui renamed to /resources/index.view.
  • BREAKING: /resources/widgets.gui renamed to /resources/widget.defs.
  • BREAKING: The import /mnt/sysassets/widgets_common.gui has been renamed to /mnt/sysassets/system_widget.defs.
  • BREAKING: Imported UI components renamed from *.gui to *.defs. e.g. /mnt/sysassets/widgets/baseview_widget.gui becomes /mnt/sysassets/widgets/baseview_widget.defs.
  • BREAKING: The following UI components have been removed: panoramaview_widget, combo_button_widget, square_button_widget, push_button_widget, and mixed_text_widget.
  • BREAKING: document.replaceSync() has deprecated in favor of two asynchronous promise based methods: document.location.replace() and document.location.assign().

If you were using the panoramaview_widget, you should replace this with a list of items instead. Developers can use the new SDK App Demo sample project as a guide.

We've updated our Button guide to include examples of the new button styles.

SDK 3.x to 4.0

There are only a small amount of changes to existing behaviour that developers need to be aware of when migrating from SDK 3.x to 4.x:

  • BREAKING: Removed the ability to keep the screen awake using autoOff in the Display API to protect AMOLED screens.
  • BREAKING: The brightnessOverride in the Display API has changed from a percentage value to an enum of predefined settings.
  • If you begin using multi-view in your application, be aware that all event handlers for document and other elements are automatically removed when you navigate to another view. All previous references are invalidated and throw an exception if you try to use them.

SDK 2.x to 3.x

When migrating your application from SDK 2.x to SDK 3.x, you should be aware of the following changes to existing behavior:

  • BREAKING: Removed support for importing resources into components other than settings.
  • Added compressed .fba bundles.
  • BREAKING: Slight increase in overall memory usage, dependent upon usage:
    • appbit grew by 32 bytes.
    • device grew by 16 bytes.
    • document grew by 16 bytes.
    • file-transfer grew by 160 bytes.
    • heart-rate grew by 88 bytes.
    • jpeg grew by 32 bytes.
    • system grew by 16 bytes.

Please refer to the Fitbit OS 3.0 announcement blog post for full details of the new features and APIs introduced in SDK 3.0.

SDK 1.x to 2.x

When migrating your application from SDK 1.x to SDK 2.x, you should be aware of the following changes to existing behavior:

  • BREAKING: Applications will now automatically close after 2 minutes of inactivity, unless you override this behavior using the App Timeout API.
  • BREAKING: Removed JSON support for import. You can use a .js file import myObj from './myFile'.
  • BREAKING: Fixed a an issue where import paths were broken: import foo from 'foo' would import foo.js which did not make sense. Now you need to import foo from './foo'.
  • JavaScript bundle minification - with sourcemapping.
  • Added RGBA6666 image compression, so images with transparency are smaller than before.
  • The JPEG module now correctly throws an error when an image decode fails.
  • BREAKING: Vertical text alignment has been fixed, you may need to adjust any vertically aligned textarea and text elements.
  • The Geolocation API on Fitbit Versa now automatically falls back to Connected GPS mode.

Please refer to the Fitbit OS 2.2 announcement blog post for full details of the new features and APIs introduced in SDK 2.0.

Upgrade Process

In order to upgrade your project from one version to another, you should follow the steps outlined below:

  1. Set your project's SDK and CLI version by running one of the following commands:

npm users

npm install --save-dev @fitbit/sdk@~5.0.0
npm install --save-dev @fitbit/sdk-cli@^1.7.3

yarn users

yarn add --dev @fitbit/sdk@~5.0.0
yarn add --dev @fitbit/sdk-cli@^1.7.3
  1. Update your code by following the migration instructions above.
  2. Then rebuild your project.

Note: Don't forget to set the correct version number in the sample commands above.

previous
Localization Guide
Multiple Devices Guide
next