How to migrate to SDK 5.0?

January 17, 2021

This guide will help you in migrating your Fitbit OS 4.2 app to the latest version of the Fitbit SDK. For the sake of completeness, some steps have been replicated here from Fitbit’s SDK 5.0 announcement page.

Build

You need to update dependencies in your package.json as follows:

{
  ...
  "devDependencies": {
    "@fitbit/sdk": "~5.0.1",
    "@fitbit/sdk-cli": "^1.7.3",
    "fitbit-sdk-types": "^6.0.1",
    ...
  }
}

After updating the above make sure you run npm install or yarn install.

You also need to remove existing values under the fitbit/buildTargets field and add one or all of the newly supported build targets (atlas is for Fitbit Versa 3, while vulcan is for Fitbit Sense):

{
  ...
  "fitbit": {
    ...
    "buildTargets": [
      "atlas",
      "vulcan"
    ],
    ...
  }
}

Project Structure

Change all view definitions (such as index.gui) to have the extension .view.
Rename widgets.gui to widget.defs.
Optional: rename all template definitions in addition to widgets.gui to have the extension .defs.

View Definitions

Rename Import for System Components

You need to rename the import for system component definitions from:

<link rel="import" href="/mnt/sysassets/widgets_common.gui" />

to the following in your widget.defs:

<link rel="import" href="/mnt/sysassets/system_widget.defs" />

Rename Main View

Rename your main view from resources/index.gui to resources/index.view.
If you are loading other views via the Document API (e.g., document.replaceSync(...)) or import other SVG files into your main view, then you can keep those as-is.

Replace Deprecated Elements

In the following sections we provide recipes for common GUI elements that need to be replaced in order to work on a Fitbit OS 5.0 device.

`mixed-text`

In SDK 5.0 there’s no longer support for mixed-text-* components, however, they can be replaced via text elements and styling. The styling depends on what type of specific mixed-text component you would like to migrate – only mixed-text-center-mid is going to be described here.

If you need to create a pop-up, just use text-button component(s) for the button(s).


Include
SDK 4.2	`/mnt/sysassets/widgets/mixed_text_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/system_widget.defs`
Reference
SDK 4.2	`<use href="#mixed-text-center-mid">...</use>`
SDK 5.0	`<text class="h3 center-text center-mid-header">...</text>`
	`<text class="h4 center-text center-mid-copy">...</text>`

Here is a suggested positioning to replicate mixed-center-mid components in SDK 5.0:

  .center-mid-header {
    x: 50%;
    y: 33%;
  }
  .center-mid-copy {
    x: 50%;
    y: 50%;
  }

Example SDK 4.2

<svg>
  <use href="#mixed-text-center-mid" fill="fb-white">
    <set href="#top-padding" attributeName="display" to="none" />
    <set href="#header/text" attributeName="text-buffer" to="Ready, Set, Go" />
    <set href="#header/text" attributeName="fill" to="fb-magenta"/>
    <set href="#copy/text" attributeName="text-buffer" to="Are you ready?" />
    <set href="#bottom-padding" attributeName="display" to="none" />
  </use>
</svg>

Example SDK 5.0

<svg>
  <text class="h3 center-text magenta-fill">Ready, Set, Go</text>
  <text class="h4 center-text foreground-fill">Are you ready?</text>
</svg>

`square-button`


Include
SDK 4.2	`/mnt/sysassets/widgets/square_button_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/text_button.defs`
Reference
SDK 4.2	`<use href="#square-button" />`
SDK 5.0	`<use href="#text-button" class="text-button ..." />`

Example SDK 4.2

<svg>
  <use id="mybutton" href="#square-button" y="5" fill="fb-red">
    <set href="#text" attributeName="text-buffer" to="Click Me!" />
  </use>
</svg>

Example SDK 5.0

<svg>
  <use id="mybutton" href="#text-button" class="text-button" y="5" fill="fb-red">
    <set href="#text" attributeName="text-buffer" to="Click Me!" />
  </use>
</svg>

`square-button` with Icon


Include
SDK 4.2	`/mnt/sysassets/widgets/square_button_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/icon_button.defs`
Reference
SDK 4.2	`<use href="#square-button-icon" />`
SDK 5.0	`<use href="#icon-text-button" class="icon-text-button ..." />`

Example SDK 4.2

<svg>
  <use id="mybutton" href="#square-button-icon" y="5" fill="coral">
    <set href="#text"  attributeName="text-buffer" to="Steps" />
    <set href="#image" attributeName="href" to="steps.png" />
  </use>
</svg>

Example SDK 5.0

<svg>
  <use id="mybutton" href="#icon-text-button" class="icon-text-button" y="5" fill="coral">
    <set href="#text"  attributeName="text-buffer" to="Steps" />
    <set href="#image" attributeName="href" to="steps.png" />
  </use>
</svg>

`square-button-positive/neutral`

One way to migrate these is to use primary and secondary CSS classes for them (see Button Components Guide).


Include
SDK 4.2	`/mnt/sysassets/widgets/square_button_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/text_button.defs`
Reference	(`positive`)
SDK 4.2	`<use href="#square-button-positive" />`
SDK 5.0	`<use href="#text-button" class="text-button primary ..." />`
Reference	(`neutral`)
SDK 4.2	`<use href="#square-button-neutral" />`
SDK 5.0	`<use href="#text-button" class="text-button secondary ..." />`

Example SDK 4.2

<svg>
  <use href="#square-button-positive" y="5">
    <set href="#text" attributeName="text-buffer" to="Positive" />
  </use>
  <use href="#square-button-neutral" y="$">
    <set href="#text" attributeName="text-buffer" to="Neutral" />
  </use>
</svg>

Example SDK 5.0

<svg>
  <use href="#text-button" class="text-button primary" y="5">
    <set href="#text" attributeName="text-buffer" to="Positive" />
  </use>
  <use href="#text-button" class="text-button secondary" y="$">
    <set href="#text" attributeName="text-buffer" to="Neutral" />
  </use>
</svg>

`square-button-negative`

There is no equivalent representation in Fitbit OS 5.0 for this, however, you can color a negative button differently by applying e.g. fb-red fill on it.

Toggle Buttons

Toggle buttons can be emulated in Fitbit OS 5.0 using onclick events on left and right buttons and changing their fill property depending on their on/off state.


Include
SDK 4.2	`/mnt/sysassets/widgets/square_button_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/text_button.defs`
Reference	(left)
SDK 4.2	`<use href="#square-button-toggle" />`
SDK 5.0	`<use href="#text-button" class="text-button left secondary ..." />`
Reference	(right)
SDK 4.2	`<use href="#square-button-toggle" />`
SDK 5.0	`<use href="#text-button" class="text-button right ..." />`

Example SDK 4.2

<svg height="70">
  <!-- toggle button OFF -->
  <use id="btn-off" href="#square-button-toggle" fill="fb-light-gray">
    <set href="#text"  attributeName="text-buffer" to="Off" />
  </use>
  <!-- toggle button ON -->
  <use id="btn-on" href="#square-button-toggle" value="1" x="50%" fill="fb-green">
    <set href="#text"  attributeName="text-buffer" to="On" />
  </use>
</svg>

Example SDK 5.0

<svg>
  <use href="#text-button" class="text-button left secondary application-fill" y="5">
    <set href="#text" attributeName="text-buffer" to="Off" />
  </use>
  <use href="#text-button" class="text-button right application-fill" y="$">
    <set href="#text" attributeName="text-buffer" to="On" />
  </use>
</svg>

Combo Buttons

Note that due to the squirce design of Fitbit Versa 3 and Fitbit Sense you may want to modify your design to avoid using combo buttons as there is less space in the corners of the screen.

Combo buttons can be replicated in Fitbit OS 5.0 using icon buttons. Medium-sized icons are the nearest to the size of the combo button icons in SDK 4.2. Bear in mind that icons for icon buttons need to have dimensions of 48x48 pixels instead of 60x60.

Few other points to consider when migrating combo buttons:

Coloring the icon is possible via the fill CSS property (see Grayscale Magic for details on how fill works).
Strokes can be emulated by adding a circle around the icon (the below examples assume no strokes).
Pressed vs. normal state can be emulated by attaching onmousedown and onmouseup event handlers and changing the image property of the button.


Include
SDK 4.2	`/mnt/sysassets/widgets/combo_button_widget.gui`
SDK 5.0	`/mnt/sysassets/widgets/icon_button.defs`
Reference	(upper left)
SDK 4.2	`<use href="#combo-button-upper-left" />`
SDK 5.0	`<use href="#icon-button" class="medium-button combo-upper-left application-fill ..." />`
Reference	(lower right)
SDK 4.2	`<use href="#combo-button-lower-right" />`
SDK 5.0	`<use href="#icon-button" class="medium-button combo-lower-right application-fill ..." />`

Note that you need to specify the icon’s image either by adding a CSS class attribute or via a <set /> tag:

Icon Image via CSS

.example-icon #image {
  href: "filename.png"
}

Icon Image via SVG

<use href="#icon-button" class="medium-button combo-upper-left application-fill">
  <set href="#image" attributeName="href" to="filename.png" />
</use>

Here is a suggested positioning for the four combo button types in SDK 4.2:

.combo-upper-left {
  x: 5%;
  y: 5%;
}
.combo-upper-right {
  x: 75%;
  y: 5%;
}
.combo-lower-left {
  x: 5%;
  y: 75%;
}
.combo-lower-right {
  x: 75%;
  y: 75%;
}

Example SDK 4.2

<svg>
  <!-- TOP RIGHT -->
  <use id="btn-tr" href="#combo-button-upper-right" fill="fb-red">
    <set href="combo-button-icon" attributeName="href" to="list.png"/>
    <set href="combo-button-icon-press" attributeName="href" to="list_press.png"/>
  </use>
  <!-- BOTTOM RIGHT -->
  <use id="btn-br" href="#combo-button-lower-right" fill="fb-peach">
    <set href="combo-button-icon" attributeName="href" to="play.png"/>
    <set href="combo-button-icon-press" attributeName="href" to="play_press.png"/>
  </use>
</svg>

Example SDK 5.0

<svg>
  <!-- TOP RIGHT -->
  <use id="btn-tr" href="#icon-button" class="icon-button combo-upper-right">
    <set href="#image" attributeName="href" to="list.png"/>
  </use>
  <!-- BOTTOM RIGHT -->
  <use id="btn-br" href="#icon-button" class="icon-button combo-lower-right">
    <set href="#image" attributeName="href" to="play.png"/>
  </use>
</svg>

API Changes

`document.replaceSync()`

This method has been deprecated because of the new navigation gestures.

Example SDK 4.2

  document.replaceSync('settings.svg');
  doSomething();
  initializeSettingsView();

Example SDK 5.0

  document.location.replace('settings.view').then(() => {
    doSomething();
    initializeSettingsView();
  });

References

Migration guide by Fitbit. The original migration guide is part of the announcement of Fitbit OS 5.0.
Fitbit SDK 4.2 guides. You can access the SDK 4.2 guides that are no longer available on dev.fitbit.com starting from this Wayback Machine link.

Build

Project Structure

View Definitions

Rename Import for System Components

Rename Main View

Replace Deprecated Elements

mixed-text

square-button

square-button with Icon

square-button-positive/neutral

square-button-negative

Toggle Buttons

Combo Buttons

API Changes

document.replaceSync()

References

`mixed-text`

`square-button`

`square-button` with Icon

`square-button-positive/neutral`

`square-button-negative`

`document.replaceSync()`