Fournir des données aux complications

Les applications de fourniture de données affichent des informations sur les complications du cadran, ainsi que des champs contenant du texte, des chaînes, des images et des chiffres.

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

Créer un projet de fournisseur de données

Si vous souhaitez créer un projet dans Android Studio pour votre application de fournisseur de données, procédez comme suit :

  1. Cliquez sur File > New > New Project (Fichier > Nouveau > Nouveau projet).
  2. Dans la fenêtre Project Template (Modèle du projet), cliquez sur l'onglet Wear OS, sélectionnez No activity (Aucune activité), puis cliquez sur Next (Suivant).
  3. Dans la fenêtre Configure Your Project (Configurer votre projet), attribuez un nom à votre projet, complétez les informations habituelles sur le projet, puis cliquez sur Finish (Terminer).
  4. Android Studio crée un projet avec un module d'application pour votre fournisseur de données. Pour en savoir plus sur les projets dans Android Studio, consultez Créer un projet.
  5. Démarrez votre application de fourniture de données en créant une classe qui étend BroadcastReceiver. L'objectif de cette classe est d'écouter les demandes de mise à jour du système Wear OS. En outre, créez une classe qui étend ComplicationProviderService afin de fournir les données requises par les complications appropriées. Pour en savoir plus, consultez les ressources suivantes :

    Remarque : Il n'est pas nécessaire d'ajouter une activité à votre fournisseur de données. Par exemple, vous pouvez choisir une activité qui ne se lance que lorsque l'utilisateur appuie sur une complication.

Intégrer une méthode pour les demandes de mise à jour

Lorsque des données de complication sont nécessaires, le système Wear OS envoie des demandes de mise à jour à votre fournisseur de données. Les demandes sont reçues par votre élément BroadcastReceiver. Pour répondre à ces demandes, votre fournisseur de données doit intégrer la méthode onComplicationUpdate() de la classe ComplicationProviderService.

Le système Wear OS appelle onComplicationUpdate() lorsqu'il a besoin des données de votre fournisseur, par exemple lorsqu'une complication utilisant ce fournisseur devient active ou après un certain temps. Il transmet un objet ComplicationManager en tant que paramètre à onComplicationUpdate, qui est utilisé pour renvoyer des données au système.

Remarque : Lorsque votre application de fournisseur de données distribue des données, le cadran reçoit les valeurs brutes que vous envoyez afin de pouvoir extraire les informations.

L'extrait de code suivant présente un exemple d'intégration de la méthode onComplicationUpdate :

Kotlin

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

Java

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

Déclarations et autorisations du fichier manifeste

Les applications de fourniture de données doivent inclure des déclarations spécifiques dans leur fichier manifeste afin que le système Android puisse les traiter en tant que fournisseur de données. Cette section décrit les paramètres requis pour les applications de fourniture de données.

Dans le fichier manifeste de votre application, définissez 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 le fournisseur et s'affiche dans le sélecteur de fournisseurs.

Exemple : 

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    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>
</service>

Spécifier les éléments de métadonnées

Dans le fichier manifeste, incluez des métadonnées pour spécifier les types compatibles, la période de mise à jour et l'action de configuration, comme indiqué dans l'exemple suivant : 

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

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

Lorsque votre fournisseur de données de complication est actif, UPDATE_PERIOD_SECONDS indique la fréquence à laquelle vous souhaitez que le système recherche les 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é.

Pour en savoir plus sur l'envoi de mises à jour, consultez les clés listées pour la classe ComplicationProviderService dans les documents de référence de l'API Wear OS.

Ajouter une activité de configuration

Si nécessaire, un fournisseur peut inclure une activité de configuration qui lui est présentée lorsqu'il choisit un fournisseur de données. Pour inclure l'activité de configuration, ajoutez un élément de métadonnées dans la déclaration de service du fournisseur au sein du fichier manifeste avec la clé suivante : 

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

La valeur peut correspondre à n'importe quelle action.

Créez ensuite l'activité de configuration avec un filtre d'intent pour cette action. 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 le fournisseur doit être défini.

Cadrans sécurisés spécifiés par le fournisseur

Les fournisseurs peuvent spécifier que certains cadrans sont sûrs pour la réception de leurs données. Ce paramètre n'est utilisé que lorsqu'un cadran tente d'utiliser le fournisseur par défaut et qu'il fait confiance à l'application du cadran.

Pour déclarer les cadrans comme sûrs, le fournisseur ajoute des métadonnées avec une clé android.support.wearable.complications.SAFE_WATCH_FACES. Les métadonnées sont une liste de valeurs séparées par une virgule représentant soit des noms de composant WatchFaceService (fournis comme si ComponentName.flattenToString() avait été appelé), soit des noms de package d'applications, auquel cas chaque cadran d'une application spécifiée est considéré comme sûr. Les espaces blancs dans la liste des valeurs sont ignorés. Exemple : 

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

Fournir des images protégées contre les brûlures d'écran

Sur les écrans susceptibles de brûler, évitez les blocs de couleur unis en mode veille. Si vos icônes ou images comprennent des blocs de couleur unie, fournissez également une version protégée contre les brûlures d'écran.

Si vous fournissez une icône à l'aide de ComplicationData.Builder#setIcon, incluez une version protégée contre les brûlures d'écran à l'aide de ComplicationData.Builder#setBurnInProtectionIcon.

Si vous fournissez une image à l'aide de ComplicationData.Builder#setSmallImage, incluez une version protégée contre les brûlures d'écran à l'aide de ComplicationData.Builder#setBurnInProtectionSmallImage.

Utiliser les mises à jour push

Au lieu d'indiquer un intervalle de mise à jour constant et non nul pour une complication dans le fichier manifeste de votre application, vous pouvez utiliser une instance de ComplicationDataSourceUpdateRequester pour demander des mises à jour de manière dynamique. Pour demander une mise à jour de contenu visible par l'utilisateur de la complication, 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.

Fournir des valeurs dynamiques

À partir de Wear OS 4, certaines complications peuvent afficher des valeurs qui s'actualisent plus fréquemment en fonction de valeurs directement disponibles sur la plate-forme. Pour fournir cette fonctionnalité dans vos complications, utilisez <ph type="x-smartling-placeholder"></ph> Champs ComplicationData qui acceptent valeurs dynamiques. La plateforme évalue et met à jour ces valeurs fréquemment, sans que le fournisseur de complications ne s'exécute.

Exemples de champs : <ph type="x-smartling-placeholder"></ph> le champ de valeur dynamique de GoalProgressComplicationData, et <ph type="x-smartling-placeholder"></ph> DynamicComplicationText, qui peut être utilisée dans n'importe quelle ComplicationText. Ces valeurs dynamiques sont basées sur <ph type="x-smartling-placeholder"></ph> androidx.wear.protolayout.expression.

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

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 des valeurs en lien avec la date ou l'heure actuelle à l'aide d'un texte dépendant de l'heure. Vous pouvez utiliser des compilateurs dans la classe ComplicationText pour créer ces valeurs temporelles.

Fréquence de mise à jour des complications

Il peut arriver que vous souhaitiez mettre souvent à jour les complications. Toutefois, cela peut affecter l'autonomie de la batterie de l'appareil. Utilisez une API de demande de complication privilégiée pour permettre à certaines complications d'être mises à jour plus fréquemment. Cependant, l'utilisation de cette API doit être autorisée par le fabricant de la montre. Chaque fabricant de montre décide quelles complications peuvent être mises à jour plus souvent que d'habitude.