Complications

At the heart of the complications system is a publisher/subscriber system. The system publishes complication data for subscribers to consume. Connect IQ device apps and audio content providers can publish complication data, but only watch faces can subscribe to complication information.

To subscribe to a complication you need to add the ComplicationSubscriber permission to your manifest file. Subscribing to Complications requires the Complications.Id. You can use Complications.getComplications() to query the all complications supported by the system. You can also query a native complication directly by constructing a Complications.Id explicitly:

var complication = Complications.getComplication(
    new Id(Complications.COMPLICATION_TYPE_CALORIES)
);

This only works for native complications. Once you have the complication id, you can persist the id in storage for later use.

You can use Complications.registerComplicationChangeCallback() to subscribe to multiple complication values. All subscriptions are terminated when your app shuts down and must be re-done when your app is launched. When you subscribe, you register a callback to be called when the value updates:

function onStart(params as Dictionary) as Void {
    // Retrieve persisted Complication ID
    mComplicationId = Storage.getValue(COMPLICATION_ID_KEY);

    // Register a callback for receiving
    // updates on complication information
    Complications.registerComplicationChangeCallback(
        self.method(:onComplicationChanged));

    // Liking and subscribing
    Complications.subscribeToUpdates(mComplicationId);
}

In your callback, you can then query the updated information and process it:

function onComplicationChanged(
    complicationId as Complication.Id) as Void {
    // Identify the complication being updated
    if (complicationId == mComplicationId) {
        // Get the complication information
        try {
            var data = Complications.getComplication(
                complicationId);
            // Handle the application processing
            updateData(complicationId, data);
        } catch (e instanceof ComplicationNotFoundException) {
            handleComplicationRemoval(complicationId);
        }
    }
}

If the complication is no longer available, for example the user has uninstalled the publishing app, the system will throw a Complications.ComplicationNotFoundException. You should trap this exception and handle it within your app. If a publishing app is uninstalled, the system will send an event to your ComplicationChangeCallback and automatically unsubscribe your app from any subscribed complications.

When wheelchair mode is enabled, COMPLICATION_TYPE_STEPS and COMPLICATION_TYPE_FLOORS_CLIMBED are replaced with COMPLICATION_TYPE_WHEELCHAIR_PUSHES.

If you are developing a device or audio content provider apps, you can publish up to four complications to the framework. To publish a complication you need to add the ComplicationPublisher permission to your manifest file.

Once your complication is defined, you can use the Complications.updateComplication() function to publish data:

var data = {
    // String, Number, Float, Long, Double, or null
    :value => newValue,

    // String
    :shortLabel => newShortLabel,

    // String or Complication.UNITS_* value
    :units => newUnits,

    // Array<Numeric> with at least 3 elements
    :ranges => newRanges,
}

// update complication
// 0 is the id of the complication
// from complications.xml
Complications.updateComplication(0, data);

Publishing a complication as public allows Face It to integrate your complication. It will always display your complication icon, and will use the following rules to display your complication value:

Some best practices:

• Make sure your Face It icon is high contrast and will appear well in both light and dark mode in mobile.

• Use Latin characters (A-Z, a-z, 0-9) for published complication strings.