Companion Guide

Overview

A companion can be used to enhance any Fitbit application by providing it with an additional JavaScript runtime environment which exists within the Fitbit mobile application. This additional runtime can utilize resources and sensors of the mobile device through the Companion API, which greatly extends the capabilities of applications.

These two runtime environments can communicate with each other via the Messaging API, or via the File Transfer API.

Common Use Cases

Fitbit applications are not required to have an associated companion, but it is essential if they need to perform any of the following tasks:

  • Communicate with Web APIs.

  • Download images or other resources from the internet.

  • Utilize the mobile device GPS sensor.

  • Persist data on the mobile device.

  • Perform functions whilst the device application is not active.

Life Cycle Events

When an application is launched by the user, its associated companion is simultaneously launched on the mobile device. The companion can also subscribe to events which allow it to be woken even if the application is not currently running.

The following events which form part of the Life Cycle API and Wake Interval API can be used to wake the companion, and also determine why the companion was launched.

Periodic Wake Interval

The onwakeinterval event is emitted if the companion has configured a periodic wakeInterval timer to launch after a specified number of milliseconds.

Begin wakeInterval

To begin the wakeInterval timer, set the value to a number of milliseconds greater than 300,000 (5 minutes).

The interval value is a mere guidance to the mobile runtime, not a guarantee that the companion will be woken up.

// Import the Companion module
import { me } from "companion"

// Helper
const MILLISECONDS_PER_MINUTE = 1000 * 60

// Wake the Companion after 30 minutes
me.wakeInterval = 30 * MILLISECONDS_PER_MINUTE

Cancel wakeInterval

To cancel the wakeInterval timer, set the value to 0, null, or undefined.

// Import the Companion module
import { me } from "companion"

// Cancel the wakeInterval timer
me.wakeInterval = undefined

Significant Location Changes

The onsignificantlocationchange event is emitted if the companion has indicated that it should be woken when the device has changed physical location. The distance deemed to be a significant change is 5 kilometers.

The monitorSignificantLocationChanges flag is used to activate and deactivate this behavior.

Start Location Monitoring

// Import the Companion module
import { me } from "companion"

// Monitor for significant changes in physical location
me.monitorSignificantLocationChanges = true

Stop Location Monitoring

// Import the Companion module
import { me } from "companion"

// Don't monitor for significant changes in physical location
me.monitorSignificantLocationChanges = false

Launch Reasons

When dealing with the life cycle of a companion, it's important to understand the reason it was started. Developers can check the launchReasons, then perform custom logic based upon those specific LaunchReasons.

Peer Application Launched

The peerAppLaunched property is set to true if the peer application was launched on the device.

// Import the Companion module
import { me } from "companion"

if (me.launchReasons.peerAppLaunched) {
  // The Device application caused the Companion to start
  console.log("Device application was launched!")
}

Location Changed

The locationChanged property is set and contains the latest Position coordinates received from the mobile device GPS.

// Import the Companion module
import { me } from "companion"

if (me.launchReasons.locationChanged) {
  // The companion was started due to a significant change in physical location
  console.log("Significant location change!")
  var pos = me.locationChanged.position
  console.log("Latitude: " + pos.coords.latitude,
              "Longitude: " + pos.coords.longitude)
}

Wake Interval

The wokenUp property is set to true if the companion was woken up by the wakeInterval periodic timer.

// Import the Companion module
import { me } from "companion"

if (me.launchReasons.wokenUp) {
  // The companion started due to a periodic timer
  console.log("Started due to wake interval!")
}

Settings Changed

The settingsChanged property is set to true if the companion was woken up because of changes to settingsStorage.

// Import the Companion module
import { me } from "companion"

if (me.launchReasons.settingsChanged) {
  // The companion was started due to application settings changes
  console.log("Settings were changed!")
}

Best Practices

Here's a simple list of best practices to follow when using a companion with your application:

  1. Don't wake your companion too frequently. This will negatively affect the battery of the mobile device and potentially the Fitbit device too.

  2. Cancel the life cycle events if you no longer need them.

Companions in Action

If you're interested in using a companion alongside your application, why not check out the Bay Area Rapid Transit (BART) example or review the Companion API Reference Documentation.