SDK Migration Guide
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: The import
/mnt/sysassets/widgets_common.guihas been renamed to
- BREAKING: Imported UI components renamed from
- BREAKING: The following UI components have been removed:
document.replaceSync()has deprecated in favor of two asynchronous promise based methods:
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
autoOffin the Display API to protect AMOLED screens.
- BREAKING: The
brightnessOverridein 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
documentand 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
- BREAKING: Slight increase in overall memory usage, dependent upon usage:
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.jswhich did not make sense. Now you need to
import foo from './foo'.
RGBA6666image 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
- 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.
In order to upgrade your project from one version to another, you should follow the steps outlined below:
- Set your project's SDK and CLI version by running one of the following commands:
npm install --save-dev @fitbit/sdk@~5.0.0 npm install --save-dev @fitbit/sdk-cli@^1.7.3
yarn add --dev @fitbit/sdk@~5.0.0 yarn add --dev @fitbit/sdk-cli@^1.7.3
- Update your code by following the migration instructions above.
- Then rebuild your project.
Note: Don't forget to set the correct version number in the sample commands above.