Fournir des données aux complications

Les sources de données de complication affichent des informations sur les complications du cadran , ainsi que du texte, des images et des chiffres que le cadran peut afficher.

Un service de source de données étend SuspendingComplicationDataSourceService afin de fournir des informations utiles directement à un cadran.

Premiers pas

Ajoutez la dépendance suivante au module de votre application : 

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

Créer le service de source de données

Lorsque des données de complication sont nécessaires, le système Wear OS envoie des demandes de mise à jour à votre source de données. Pour répondre à ces demandes, votre source de données doit implémenter la onComplicationRequest() méthode de la SuspendingComplicationDataSourceService classe.

Le système Wear OS appelle onComplicationRequest() lorsqu'il a besoin de données provenant de votre source, par exemple lorsqu'une complication utilisant votre source de données devient active ou lorsqu'une durée fixe s'est écoulée.

Remarque : Lorsque votre source de données fournit des données, le cadran reçoit les valeurs brutes. Le cadran est chargé de mettre en forme les données pour l'affichage.

L'extrait de code suivant montre un exemple d'implémentation :

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}
MyComplicationDataSourceService.kt

Déclarations et autorisations du fichier manifeste

Les sources de données doivent inclure des déclarations spécifiques dans leur fichier manifeste d'application afin que le système Android puisse les traiter en tant que source de données. Cette section explique les paramètres requis pour les sources de données.

Dans le fichier manifeste de votre application, déclarez le service et ajoutez un filtre d'intent de demande de mise à jour. Le fichier manifeste doit également protéger le service en ajoutant l'autorisation BIND_COMPLICATION_PROVIDER pour garantir que seul le système Wear OS peut être lié aux services du fournisseur.

Incluez également un attribut android:icon dans l'élément service qui fournit une icône blanche d'une seule couleur. Nous vous recommandons d'utiliser des drawables vectoriels pour les icônes. Cette icône représente la source de données et s'affiche dans le sélecteur de complications.

Exemple : 

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST" />
    </intent-filter>

    <!-- Supported types should be comma-separated, for example: "SHORT_TEXT,SMALL_IMAGE" -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!-- Optionally, specify a configuration activity, where the user can configure your complication. -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>
AndroidManifest.xml

Éléments de métadonnées

Dans le fichier manifeste, notez les éléments de métadonnées suivants :

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": : spécifie les types de données de complication compatibles avec la source de données.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": : spécifie la fréquence à laquelle le système doit rechercher des mises à jour des données.

Lorsque votre source de données de complication est active, UPDATE_PERIOD_SECONDS spécifie la fréquence à laquelle vous souhaitez que le système recherche des mises à jour des données. Si les informations affichées dans la complication ne requièrent pas de mises à jour régulières, par exemple lorsque vous utilisez des mises à jour push, définissez cette valeur sur 0.

Si vous ne définissez pas UPDATE_PERIOD_SECONDS sur 0, vous devez utiliser une valeur d'au moins 300 (5 minutes), qui correspond à la période de mise à jour minimale imposée par le système, afin de préserver l'autonomie de la batterie de l'appareil. En outre, sachez que les demandes de mise à jour peuvent se produire moins souvent lorsque l'appareil est en mode veille ou lorsqu'il n'est pas porté.

Ajouter une activité de configuration

Si nécessaire, une source de données peut inclure une activité de configuration qui lui est présentée lorsqu'il choisit cette source de données particulière dans le sélecteur de complications. Par exemple, une source de données d'horloge mondiale peut avoir une configuration activité qui permet à l'utilisateur de choisir la ville ou le fuseau horaire à afficher.

L'exemple de fichier manifeste inclut un meta-data élément avec la PROVIDER_CONFIG_ACTION clé. La valeur de cet élément est l'action utilisée pour lancer l'activité de configuration.

Créez l'activité de configuration et ajoutez un filtre d'intent qui correspond à l'action dans le fichier manifeste. 

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>
AndroidManifest.xml

L'activité peut obtenir des détails sur l'emplacement de la complication qu'elle configure à partir de l'intent dans la méthode onCreate() de l'activité : 

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)
ConfigurationActivity.kt

L'activité de configuration doit se trouver dans le même package que le fournisseur. L'activité de configuration doit renvoyer RESULT_OK ou RESULT_CANCELED pour indiquer au système si la source de données doit être définie : 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()
ConfigurationActivity.kt

Utiliser les mises à jour push

Au lieu de spécifier un intervalle de mise à jour dans le fichier manifeste de votre application, vous pouvez utiliser une instance de ComplicationDataSourceUpdateRequester pour lancer des mises à jour de manière dynamique. Pour demander une mise à jour, appelez requestUpdate().

Attention : Pour préserver l'autonomie de la batterie de l'appareil, n'appelez pas requestUpdate() plus souvent que toutes les cinq minutes en moyenne à partir de l'instance de ComplicationDataSourceUpdateRequester.

Indiquer des valeurs temporelles

Certaines complications doivent afficher une valeur correspondant à l'heure actuelle. Par exemple : la date actuelle, l'heure avant la prochaine réunion ou l'heure dans un autre fuseau horaire.

Ne mettez pas à jour une complication toutes les secondes ou toutes les minutes pour maintenir ces valeurs à jour. Précisez plutôt les valeurs en lien avec la date ou l'heure actuelle à l'aide d'un texte dépendant de l'heure. Les classes suivantes vous permettent de créer ces valeurs temporelles :

Données de Vos trajets

Pour les sources de données de complication qui fournissent une séquence de valeurs à des moments prédéfinis, utilisez SuspendingTimelineComplicationDataSourceService.

Par exemple, une source de données "événement suivant" provenant d'une application Agenda : au lieu que le système interroge régulièrement la source de données pour l'événement suivant, la source de données peut fournir une chronologie des événements une seule fois, puis lancer des mises à jour si l'agenda change. Cela minimise la charge sur le système et permet à la complication d'afficher l'événement correct en temps voulu : 

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}
MyTimelineComplicationDataSourceService.kt

Le comportement de SuspendingTimelineComplicationDataSourceService est le suivant :

  • Lorsque l'heure actuelle se situe entre l'heure de début et l'heure de fin d'une entrée de la chronologie, le cadran utilise cette valeur.
  • Lorsque l'heure actuelle ne correspond à aucune entrée de la chronologie, la valeur par défaut est utilisée. Par exemple, dans l'application Agenda, il peut s'agir de "Aucun événement".
  • Si l'heure actuelle correspond à plusieurs événements, l'événement le plus court est utilisé.

Fournir des valeurs dynamiques

À partir de Wear OS 4, certaines complications peuvent afficher des valeurs qui s'actualisent plus fréquemment en fonction des valeurs disponibles directement sur la plate-forme. Pour fournir cette fonctionnalité dans vos complications, utilisez ComplicationData champs qui acceptent les valeurs dynamiques. La plate-forme évalue et met à jour ces valeurs fréquemment, sans que le fournisseur de complications n'ait besoin d'être exécuté.

Les exemples de champs incluent GoalProgressComplicationData's dynamic value field, and DynamicComplicationText, which can be used in any ComplicationText field. Ces valeurs dynamiques sont basées sur la androidx.wear.protolayout.expression bibliothèque.

Dans certaines situations, la plate-forme ne peut pas évaluer les valeurs dynamiques :