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:
- Fai clic su File > Nuovo > Nuovo progetto.
- Nella finestra Modello di progetto, fai clic sulla scheda Wear OS, seleziona Nessuna attività e fai clic su Avanti.
- Nella finestra Configura il tuo progetto, assegna un nome al progetto, compila le informazioni standard del progetto e fai clic su Fine.
- 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.
- 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 estendeComplicationProviderService
per fornire i dati come richiesto dalle complicazioni appropriate. Per ulteriori informazioni, consulta quanto segue:- Implementare un metodo per le richieste di aggiornamento
- Le
ComplicationTapBroadcastReceiver
eCustomComplicationProviderService
corsi nel seguente codelab: . Esposizione dei dati alle complicazioni del quadrante su Wear OS ComplicationToggleReceiver
,LongTextProviderService
, e altri corsi della . esempio di suite di test
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:
- A volte il valore dinamico non è disponibile . Questo si verifica, ad esempio, quando il parametro
dispositivo non indossato sul polso. In queste situazioni, la piattaforma utilizza il valore
del
campo di riserva per l'annullamento della convalida dei valori dinamici, in un
.
campo segnaposto di
NoDataComplicationData
. - Il valore dinamico non è mai disponibile : questo si verifica su un dispositivo in esecuzione su un
versione precedente di Wear OS 4. In questa situazione, la piattaforma utilizza un campo di riserva companion,
come
getFallbackValue()
.
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.