Multiple Devices Guide

Overview

When developing applications or clock faces using the Fitbit SDK, you are able to build for multiple device targets simultaneously, if they are targeting the same SDK version.

These Build Targets are devices capable of running Fitbit OS.

The Fitbit OS 5 devices are:

• Versa 3
• Sense

and the Fitbit OS 4 devices are:

• Versa
• Versa Lite
• Versa 2

Devices

There are a number of different devices that support apps and clock faces built using the Fitbit OS SDK. Each device has a model name, model ID, and an alias that is used within the package.json file as a build target. The full list of device model names, modelId's, and aliases are:

Hardware Differentiators

In addition to the form factor and hardware design of various devices, there are some specific hardware differences that developers should be aware of when creating applications or clock faces:

1. Device may have a different size and shape display.

   • Versa, Versa Lite, and Versa 2 are square shaped. 300x300 pixels.
   • Versa 3, and Sense are squircle shaped. 336x336 pixels.

2. Only specific devices have on-board GPS (Versa 3, and Sense). Other devices will fall back to using connected GPS from from the mobile device, provided that the access_location permission has been granted. The majority of use cases don't actually require the use of the Device Geolocation API, the Companion Geolocation API is a more power efficient method and should satify your requirements.

Recommended Approach

Each device may have different hardware specifications, so during the development process it's important to cater for these different requirements either in code, or by including different resource files.

The recommended approach when dealing with multiple devices is to detect the capabilities of a device, rather than coding for a specific device model name. This way devices which share the same capabilities will be able to share the same application logic or resources.

Resource Files

The build process has been designed to generate an application for each selected Build Target within a single .fba file, provided they are targeting the same version of Fitbit OS. During the build process, only the relevant resources are included for each target. The build targets are selected within the package.json file in your project.

The current build process uses the screen resolution as the method for determining the device capability when bundling the resource files.

Resources such as images, css, and SVG files can all be targeted to specific devices by using the following file-naming convention:

/resources/filename~SCREEN-RESOLUTION.ext

During the build process, we only include the relevant resources for each platform.

We always try to use the resource with the highest specificity first, then fall back to the default filename. For example, if you included these two files in your project:

/resources/styles~300x300.css\
/resources/styles.css

The file styles~300x300.css would be used on Versa, and styles.css would be used as the default for other platforms.

From a referencing perspective, just refer to the base filename (e.g., styles.css) in your code or SVG files. The files are renamed without the screen resolution during the build process.

<link rel="stylesheet" href="styles.css" />

You are not required to target resource files to specific devices, but it's a simple way of keeping your resource files uncluttered, or optimized for specific devices.

Code Detection

To perform device detection within your code files, the BasicDeviceInfo interface includes the screen width and height. You can access screen dimensions via the Device.Device API, or the Companion.Peer API.

Device API

import { me as device } from "device";
if (!device.screen) device.screen = { width: 348, height: 250 };
console.log(`Dimensions: ${device.screen.width}x${device.screen.height}`);

Companion API

import { device } from "peer";
if (!device.screen) device.screen = { width: 348, height: 250 };
console.log(`Dimensions: ${device.screen.width}x${device.screen.height}`);

Settings API

If you want to provide settings based on the type of connected device, you would need to pass them from the Companion API to the Settings API using settingsStorage, as follows:

import { device } from "peer";
if (!device.screen) device.screen = { width: 348, height: 250 };
settingsStorage.setItem("screenWidth", device.screen.width);
settingsStorage.setItem("screenHeight", device.screen.height);

function mySettings(props) {
  let screenWidth = props.settingsStorage.getItem("screenWidth");
  let screenHeight = props.settingsStorage.getItem("screenHeight");
}

Migration Guide

Permissions Guide