Esporre i dati a complicazioni

Le app dei fornitori di dati espongono informazioni al quadrante complicazioni, fornendo campi che contengono testo, stringhe, immagini e numeri.

Un servizio del fornitore di dati estende ComplicationProviderService per offrire informazioni utili le informazioni direttamente su un quadrante.

Crea un progetto del fornitore di dati

Per creare un in Android Studio per l'app del fornitore di dati, completa i seguenti passaggi:

  1. Fai clic su File > Nuovo > Nuovo progetto.
  2. Nella finestra Modello di progetto, fai clic sulla scheda Wear OS, seleziona Nessuna attività e fai clic su Avanti.
  3. Nella finestra Configura il tuo progetto, assegna un nome al progetto, compila le informazioni standard del progetto e fai clic su Fine.
  4. Android Studio crea un progetto con un modulo dell'app per il tuo fornitore di dati. Per ulteriori informazioni sui progetti in Android Studio, consulta Crea un progetto.
  5. Avvia l'app del tuo fornitore di dati creando una nuova classe che si estende BroadcastReceiver. Lo scopo della lezione è ascoltare richieste di aggiornamento delle complicazioni dal sistema Wear OS. Inoltre, crea un'istanza una nuova classe che si estende ComplicationProviderService per fornire i dati come richiesto dalle complicazioni appropriate. Per ulteriori informazioni, consulta quanto segue:

    Nota. L'aggiunta di un'attività per il fornitore di dati facoltativo. Ad esempio, potresti volere un'attività che venga avviata solo quando l'utente tocca un una complicanza.

Implementare un metodo per le richieste di aggiornamento

Quando sono necessari dati sulle complicazioni, il sistema Wear OS invia richieste di aggiornamento ai tuoi dati o il provider di servizi di terze parti. Le richieste vengono ricevute da BroadcastReceiver. Per rispondere alle richieste di aggiornamento, il tuo fornitore di dati deve implementare onComplicationUpdate() del metodo ComplicationProviderService .

Il sistema Wear OS chiama il numero onComplicationUpdate() quando ha bisogno di dati delle tue fornitore, ad esempio, quando una complicazione nell'utilizzo del provider o quando è trascorso un periodo di tempo prestabilito. Passa un codice ComplicationManager come parametro per onComplicationUpdate, che viene utilizzato per inviare i dati al sistema.

Nota: quando l'app del fornitore di dati fornisce dati, il quadrante riceve i valori non elaborati che invii in modo da poter estrarre le informazioni.

Il seguente snippet di codice mostra un'implementazione di esempio del Metodo 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);
   }
}

Dichiarazioni e autorizzazioni del file manifest

Le app dei fornitori di dati devono includere dichiarazioni specifiche nel file manifest dell'app per poter essere trattate come un fornitore di dati dal sistema Android. Questa sezione illustra le impostazioni richieste per le app dei fornitori di dati.

Nel file manifest dell'app, dichiara il servizio e aggiungi un filtro per intent dell'azione di richiesta di aggiornamento. Il file manifest deve inoltre proteggere il servizio mediante l'aggiunta dell'elemento BIND_COMPLICATION_PROVIDER per garantire che solo il sistema Wear OS possa collegarsi ai servizi del fornitore.

Inoltre, includi un attributo android:icon in Elemento service che fornisce un icona bianca monocolore. Consigliamo di utilizzare drawable vettoriali per le icone. L'icona rappresenta il provider ed è mostrata nel provider selettore.

Ecco un esempio: 

<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>

Specifica gli elementi dei metadati

Nel file manifest, includi i metadati per specificare i tipi supportati, il periodo di aggiornamento e l'azione di configurazione, come illustrato di seguito esempio: 

<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" />

Quando il fornitore di dati per complicazioni è attivo, UPDATE_PERIOD_SECONDS specifica la frequenza con cui vuoi che per verificare la presenza di aggiornamenti ai dati. Se le informazioni mostrate complicanza non deve aggiornarsi regolarmente, ad esempio quando utilizzi gli aggiornamenti push, imposta questo valore su 0.

Se non imposti UPDATE_PERIOD_SECONDS su 0, devi utilizzare un valore di almeno 300 (5 minuti), ovvero il periodo minimo di aggiornamento applicato dal sistema, per preservare la durata della batteria del tuo dispositivo. Inoltre, tieni presente che le richieste di aggiornamento si verificano meno spesso quando il dispositivo è in modalità Ambient o non è indossato.

Per ulteriori dettagli sull'invio di aggiornamenti, consulta le chiavi elencate per ComplicationProviderService nel API Wear OS Riferimento.

Aggiungi un'attività di configurazione

Se necessario, un provider può includere un'attività di configurazione mostrato all'utente quando sceglie un fornitore di dati. Per includere i campi per l'attività di configurazione, includi un elemento di metadati nel servizio del provider dichiarazione nel file manifest con la seguente chiave: 

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

Il valore può essere qualsiasi azione.

Quindi, crea l'attività di configurazione con un filtro per intent specifico un'azione. L'attività di configurazione deve risiedere nello stesso pacchetto della o il provider di servizi di terze parti. L'attività di configurazione deve restituire RESULT_OK o RESULT_CANCELED per comunicare al sistema se il provider deve essere impostato.

Quadranti sicuri specificati dal fornitore

I fornitori possono specificare alcuni quadranti come "sicuri" per ricevere le loro e i dati di Google Cloud. Viene usato soltanto quando un quadrante prova a di usare il provider come predefinito e il fornitore considera attendibile l'app del quadrante.

Per dichiarare i quadranti come sicuri, il fornitore aggiunge metadati con una chiave android.support.wearable.complications.SAFE_WATCH_FACES. La valore metadati è un elenco separato da virgole di Nomi dei componenti WatchFaceService, indicati come se ComponentName.flattenToString() viene chiamato o nomi di pacchetti dell'app, nel qual caso ogni quadrante all'interno di un l'app specificata è considerata sicura. Lo spazio vuoto nell'elenco dei valori viene ignorato. Ad esempio: 

<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"/>

Fornisci immagini con burn-in sicuro

Sugli schermi suscettibili al burn-in, evita blocchi di colore solidi in modalità Ambient. Se le icone o le immagini includono blocchi di colore a tinta unita, forniscono anche una versione sicura per il burn-in.

Quando fornisci un'icona utilizzando ComplicationData.Builder#setIcon, includi una versione sicura per il burn-in utilizzando ComplicationData.Builder#setBurnInProtectionIcon.

Quando fornisci un'immagine utilizzando ComplicationData.Builder#setSmallImage, includi una versione sicura per il burn-in utilizzando ComplicationData.Builder#setBurnInProtectionSmallImage.

Utilizzare gli aggiornamenti push

In alternativa alla specifica di un intervallo di aggiornamento costante diverso da zero per un complicazione nel file manifest dell'app, puoi utilizzare un'istanza ComplicationDataSourceUpdateRequester per richiedere aggiornamenti in modo dinamico. Per richiedere un aggiornamento dei contenuti visibili all'utente della complicazione, chiama requestUpdate().

Attenzione:per preservare la durata della batteria del dispositivo, non chiamare requestUpdate() dalla tua istanza di ComplicationDataSourceUpdateRequester in più rispetto a ogni 5 minuti nei media.

Fornisci valori dinamici

A partire da Wear OS 4, alcune complicazioni possono mostrare valori che si aggiornano più spesso in base ai valori disponibili direttamente sulla piattaforma. Per fornire questa funzionalità le tue complicazioni, usa ComplicationData campi che accettano valori dinamici: La piattaforma valuta e aggiorna spesso questi valori, senza richiedere l'esecuzione del fornitore delle complicazioni.

I campi di esempio includono campo del valore dinamico di GoalProgressComplicationData e DynamicComplicationText, che può essere utilizzato in qualsiasi ComplicationText. Questi valori dinamici si basano sui androidx.wear.protolayout.expression.

In determinate situazioni, la piattaforma non è in grado di valutare i valori dinamici:

Fornisci valori dipendenti dal tempo

Alcune complicazioni devono mostrare un valore relativo all'attuale nel tempo. Alcuni esempi sono la data corrente, l'ora fino alla prossima riunione, o l'ora in un altro fuso orario.

Non aggiornare una complicazione ogni secondo o minuto per mantenere questi valori aggiornati. Specifica invece i valori relativi alla data o all'ora correnti utilizzando il testo dipendente dal tempo. Puoi utilizzare i builder nella ComplicationText per creare questi valori dipendenti dal tempo.

Tasso di aggiornamento della complicazione

Potresti voler aggiornare rapidamente le complicazioni. Tuttavia, ciò potrebbe influire sulla batteria la durata massima del dispositivo. Puoi scegliere di utilizzare un modello API Complication Request, che consente di aggiornare con maggiore frequenza complicazioni specifiche. Tuttavia, l'uso di questa API deve essere consentito dal produttore di orologi. Ogni produttore di orologi decide quali complicazioni possono essere aggiornate una velocità maggiore rispetto a quella normalmente consentita.