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:

Androidx class Tag name
GoalProgressComplicationData GOAL_PROGRESS
LongTextComplicationData LONG_TEXT
MonochromaticImageComplicationData ICON
PhotoImageComplicationData LARGE_IMAGE
RangedValueComplicationData RANGED_TEXT
ShortTextComplicationData SHORT_TEXT
SmallImageComplicationData SMALL_IMAGE
WeightedElementsComplicationData WEIGHTED_ELEMENTS

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

Nested types

Callback for onComplicationRequest where only one of onComplicationData or onComplicationDataTimeline should be called.

Constants

static final @NonNull String

The intent action used to send update requests to the data source.

static final @NonNull String

Category for complication data source config activities.

static final @NonNull String

Extra used to supply the complication id to a complication data source configuration activity.

static final @NonNull String

Extra used to supply the complication type to a complication data source configuration activity.

static final @NonNull String

Extra used to supply the complication data source component to a complication data source configuration activity.

static final @NonNull String

Metadata key used to declare that the complication data source service supports backup and restore (B&R) of complication configuration data.

static final @NonNull String

Metadata key used to declare an action for a configuration activity for a complication data source.

static final @NonNull String

Metadata key.

static final @NonNull String

Metadata key used to request elevated frequency of onComplicationRequests when the watch face is visible and non-ambient.

static final @NonNull String

Metadata key used to declare a list of watch faces that may receive data from a complication data source before they are granted the RECEIVE_COMPLICATION_DATA permission.

static final @NonNull String

Metadata key used to declare supported complication types for safe watch faces.

static final @NonNull String

Metadata key used to declare supported complication types.

static final @NonNull String

Metadata key used to declare the requested frequency of update requests.

Public constructors

Public methods

abstract ComplicationData

A request for representative preview data for the complication, for use in the editor UI.

final IBinder
void
@MainThread
onComplicationActivated(
    int complicationInstanceId,
    @NonNull ComplicationType type
)

Called when a complication is activated.

void
@MainThread
onComplicationDeactivated(int complicationInstanceId)

Called when a complication is deactivated.

abstract void

Called when a complication data update is requested for the given complication id.

void

If a metadata key with METADATA_KEY_IMMEDIATE_UPDATE_PERIOD_MILLISECONDS is present in the manifest, and the provider has privileged permission com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE, then onStartImmediateComplicationRequests will be called when the watch face is visible and non-ambient.

void
@MainThread
onStopImmediateComplicationRequests(int complicationInstanceId)

If a metadata key with METADATA_KEY_IMMEDIATE_UPDATE_PERIOD_MILLISECONDS is present in the manifest, and the provider has privileged permission com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE, then onStartImmediateComplicationRequests will be called when the watch face ceases to be visible and non-ambient.

Inherited methods

From android.content.Context
boolean
final int
getColor(int p0)
final @NonNull ColorStateList
final @Nullable Drawable
getDrawable(int p0)
final @NonNull String
getString(int p0)
final @NonNull String
getString(int p0, @NonNull Object p1)
final @NonNull T
<T extends Object> getSystemService(@NonNull Class<@NonNull T> p0)
final @NonNull CharSequence
getText(int p0)
final @NonNull TypedArray
final @NonNull TypedArray
final @NonNull TypedArray
obtainStyledAttributes(int p0, @NonNull int[] p1)
final @NonNull TypedArray
obtainStyledAttributes(
    @Nullable AttributeSet p0,
    @NonNull int[] p1,
    int p2,
    int p3
)
void
void
sendBroadcastWithMultiplePermissions(
    @NonNull Intent p0,
    @NonNull String[] p1
)
From android.content.ContextWrapper
boolean
bindIsolatedService(
    @NonNull Intent p0,
    int p1,
    @NonNull String p2,
    @NonNull Executor p3,
    @NonNull ServiceConnection p4
)
boolean
boolean
boolean
boolean
bindService(
    @NonNull Intent p0,
    int p1,
    @NonNull Executor p2,
    @NonNull ServiceConnection p3
)
boolean
boolean
bindServiceAsUser(
    @NonNull Intent p0,
    @NonNull ServiceConnection p1,
    int p2,
    @NonNull UserHandle p3
)
int
int
@NonNull int[]
int
int
@NonNull int[]
int
checkContentUriPermissionFull(@NonNull Uri p0, int p1, int p2, int p3)
int
checkPermission(@NonNull String p0, int p1, int p2)
int
int
checkUriPermission(@NonNull Uri p0, int p1, int p2, int p3)
int
checkUriPermission(
    @Nullable Uri p0,
    @Nullable String p1,
    @Nullable String p2,
    int p3,
    int p4,
    int p5
)
@NonNull int[]
checkUriPermissions(@NonNull List<@NonNull Uri> p0, int p1, int p2, int p3)
void

This method is deprecated. Deprecated in Java

@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull String[]
boolean
boolean
boolean
void
void
enforceCallingOrSelfUriPermission(
    @NonNull Uri p0,
    int p1,
    @NonNull String p2
)
void
void
void
enforcePermission(@NonNull String p0, int p1, int p2, @Nullable String p3)
void
enforceUriPermission(
    @NonNull Uri p0,
    int p1,
    int p2,
    int p3,
    @NonNull String p4
)
void
enforceUriPermission(
    @Nullable Uri p0,
    @Nullable String p1,
    @Nullable String p2,
    int p3,
    int p4,
    int p5,
    @Nullable String p6
)
@NonNull String[]
@NonNull Context
@NonNull ApplicationInfo
@NonNull AssetManager
@NonNull AttributionSource
@Nullable String
@NonNull Context
@NonNull File
@NonNull ClassLoader
@NonNull File
@NonNull ContentResolver
@NonNull File
@NonNull File
int
@NonNull File
getDir(@NonNull String p0, int p1)
@Nullable Display
@Nullable File
@NonNull File[]
@Nullable File
@NonNull File[]
@NonNull File[]
@NonNull File
@NonNull File
@NonNull Executor
@NonNull Looper
@NonNull File
@NonNull File
@NonNull File[]
@NonNull String
@NonNull String
@NonNull PackageManager
@NonNull String
@NonNull String
@Nullable ContextParams
@NonNull Resources
@NonNull SharedPreferences
@NonNull Object
String
@NonNull Resources.Theme
@NonNull Drawable

This method is deprecated. Deprecated in Java

int

This method is deprecated. Deprecated in Java

int

This method is deprecated. Deprecated in Java

void
boolean
boolean
boolean
boolean
boolean
@NonNull FileInputStream
@NonNull FileOutputStream
openFileOutput(@NonNull String p0, int p1)
@NonNull SQLiteDatabase
openOrCreateDatabase(
    @NonNull String p0,
    int p1,
    @NonNull SQLiteDatabase.CursorFactory p2
)
@NonNull SQLiteDatabase
@NonNull Drawable

This method is deprecated. Deprecated in Java

void
void
Intent
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    int p2
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    @Nullable String p2,
    @Nullable Handler p3
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    @Nullable String p2,
    @Nullable Handler p3,
    int p4
)
void

This method is deprecated. Deprecated in Java

void

This method is deprecated. Deprecated in Java

void
void
void
void
void
void
void
void
void
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable Bundle p2
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable BroadcastReceiver p2,
    @Nullable Handler p3,
    int p4,
    @Nullable String p5,
    @Nullable Bundle p6
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable Bundle p2,
    @Nullable BroadcastReceiver p3,
    @Nullable Handler p4,
    int p5,
    @Nullable String p6,
    @Nullable Bundle p7
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable String p2,
    @Nullable BroadcastReceiver p3,
    @Nullable Handler p4,
    int p5,
    @Nullable String p6,
    @Nullable Bundle p7
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    int p1,
    @