ComplicationDataSourceService

public abstract class ComplicationDataSourceService extends Service

Class for sources of complication data.

A complication data source service must implement onComplicationRequest to respond to requests for updates from the complication system.

Manifest requirements:

• The manifest declaration of this service must include an intent filter for android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST.

• A ComplicationDataSourceService must include a meta-data tag with android.support.wearable.complications.SUPPORTED_TYPES in its manifest entry.

The value of android.support.wearable.complications.SUPPORTED_TYPES should be a comma separated list of types supported by the data source, from this table:

The order in which types are listed has no significance. In the case where a watch face supports multiple types in a single complication slot, the watch face will determine which types it prefers.

For example, a complication data source that supports the RANGED_VALUE, SHORT_TEXT, and ICON types would include the following in its manifest entry:

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,ICON" />

From android T onwards, it is recommended for ComplicationDataSourceServices to be direct boot aware because the system is able to fetch complications before the lock screen has been removed. To do this add android:directBootAware="true" to your service tag.

• A provider can choose to trust one or more watch faces by including the following in its manifest entry:

<meta-data
    android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
    android:value="com.pkg1/com.trusted.wf1,com.pkg2/com.trusted.wf2" />

The listed watch faces will not need com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA in order to receive complications from this provider. Also the provider may choose to serve different types to safe watch faces by including the following in its manifest:

<meta-data
    android:name="androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES"
    android:value="ICON" />

In addition the provider can learn if a request is for a safe watchface by examining ComplicationRequest.isForSafeWatchFace. Note SAFE_WATCH_FACE_SUPPORTED_TYPES and isForSafeWatchFace are gated behind the privileged permission com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE.

• A ComplicationDataSourceService should include a meta-data tag with android.support.wearable.complications.UPDATE_PERIOD_SECONDS in its manifest entry. The value of this tag is the number of seconds the complication data source would like to elapse between update requests.

Note that update requests are not guaranteed to be sent with this frequency. For complications with frequent updates they can also register a separate meta-data tag with androidx.wear.watchface.complications.data.source.IMMEDIATE_UPDATE_PERIOD_MILLISECONDS in their manifest which supports sampling at up to 1Hz when the watch face is visible and non-ambient, however this also requires the application to have the privileged permission com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE.

If a complication data source never needs to receive update requests beyond the one sent when a complication is activated, the value of this tag should be 0.

For example, a complication data source that would like to update at most every hour should include the following in its manifest entry:

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="3600" />

• A ComplicationDataSourceService can include a meta-data tag with android.support.wearable.complications.PROVIDER_CONFIG_ACTION its manifest entry to cause a configuration activity to be shown when the complication data source is selected.

The configuration activity must reside in the same package as the complication data source, and must register an intent filter for the action specified here, including android.support.wearable.complications.category.PROVIDER_CONFIG as well as Intent.CATEGORY_DEFAULT as categories.

Note back up and restore of any configuration data is left to the complication data source, see METADATA_KEY_CONFIG_RESTORE_SUPPORTED for more details.

The complication id being configured will be included in the intent that starts the config activity using the extra key android.support.wearable.complications.EXTRA_CONFIG_COMPLICATION_ID.

The complication type that will be requested from the complication data source will also be included, using the extra key android.support.wearable.complications.EXTRA_CONFIG_COMPLICATION_TYPE.

The complication data source's ComponentName will also be included in the intent that starts the config activity, using the extra key android.support.wearable.complications.EXTRA_CONFIG_PROVIDER_COMPONENT.

The config activity must call Activity.setResult with either Activity.RESULT_OK or Activity.RESULT_CANCELED before it is finished, to tell the system whether or not the complication data source should be set on the given complication.

It is possible to provide additional meta-data tag androidx.watchface.complications.datasource.DEFAULT_CONFIG_SUPPORTED in the service set to "true" to let the system know that the data source is able to provide complication data before it is configured.

• The manifest entry for the service should also include an android:icon attribute. The icon provided there should be a single-color white icon that represents the complication data source. This icon will be shown in the complication data source chooser interface, and may also be included in ComplicationProviderInfo given to watch faces for display in their configuration activities.

• The manifest entry should also include android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER" to ensure that only the system can bind to it.

Multiple complication data sources in the same APK are supported but in android R there's a soft limit of 100 data sources per APK. Above that the companion watchface editor won't support this complication data source app.

There's no need to call setDataSource for any the ComplicationData Builders because the system will append this value on your behalf.

Summary