Configurare l'app Wear OS per il push dei quadranti

Watch Face Push consente alla tua app di gestire i quadranti su un dispositivo Wear OS. Ciò include l'aggiunta, l'aggiornamento e la rimozione dei quadranti, nonché l'impostazione del quadrante attivo. Configura l'app Wear OS per utilizzare l'API Watch Face Push.

Configura

Includi le dipendenze necessarie:

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

Aggiungi quanto segue a AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Required to use the Watch Face Push API.  -->
    <uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

    <!-- Required to be able to call the setWatchFaceAsActive() method. -->
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

</manifest>

Recuperare un riferimento all'istanza del gestore

Ottieni un'istanza di WatchFacePushManager:

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager fornisce l'accesso a tutti i metodi di interazione con il push dei quadranti.

Utilizzare gli slot

Un concetto chiave quando si lavora con il push dei quadranti è quello di slot. Gli slot sono un modo per indirizzare i quadranti installati che appartengono alla tua applicazione. Il sistema imposta un numero massimo di slot che un marketplace può avere; con Wear OS 6, il limite è 1.

Quando aggiorni o rimuovi un quadrante, slotId viene utilizzato per identificare il quadrante su cui eseguire l'operazione.

Elencare i quadranti

Per elencare l'insieme di quadranti installati, utilizza listWatchFaces():

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

In questo modo puoi determinare se lo spazio è disponibile o se l'aggiunta di un altro quadrante richiede la sostituzione di quello esistente. L'elenco fornisce anche dettagli sul quadrante orologio installato. Ad esempio, per verificare se è installato un determinato pacchetto di quadranti:

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

Aggiungere un quadrante

Se sono disponibili slot, come determinato dalla risposta listWatchFaces, deve essere utilizzato il metodo addWatchFace():

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

Nota: non archiviare i valori slotId né trattarli come persistenti. Lo stato potrebbe cambiare al di fuori dell'applicazione; ad esempio, un utente potrebbe disinstallare la watch face tramite la UI di sistema. Ottieni sempre lo stato attuale immediatamente prima di qualsiasi operazione basata sugli slot.

Aggiornare un quadrante

L'aggiornamento di un quadrante ti consente di sostituire i contenuti di un determinato slot con un nuovo pacchetto. Potrebbe trattarsi dell'upgrade dello stesso quadrante a una versione più recente o della sostituzione completa del quadrante con un altro.

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

Rimuovere un quadrante

Per rimuovere un quadrante:

// Remove the com.example.watchfacepush.green watch face.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

Nota :valuta se la tua app deve chiamare removeWatchFace. In alternativa, quando l'utente tocca per disinstallare un quadrante orologio tramite l'app marketplace, puoi sostituirlo con un quadrante orologio predefinito.

In questo modo, il quadrante sarà sempre disponibile nel selettore di quadranti di sistema, potrà mostrare il tuo logo in evidenza e persino un pulsante per avviare l'app Marketplace sullo smartphone.

Controllare se il quadrante è attivo

Determinare se il tuo marketplace ha impostato il quadrante attivo è importante per garantire all'utente un'esperienza fluida: se il marketplace ha già impostato il quadrante attivo, l'utente deve solo sostituire quello attuale tramite l'app marketplace perché la modifica abbia effetto. Tuttavia, se il marketplace non ha impostato il quadrante attivo, l'app per smartphone deve offrire all'utente maggiori indicazioni. Per maggiori dettagli su come gestire questa esperienza utente, consulta la sezione sull'app Telefono.

Per determinare se il marketplace ha impostato il quadrante attivo, utilizza la seguente logica:

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

Avviso: quando chiami updateWatchFace(), non chiamare isWatchFaceActive() subito dopo, perché potresti ottenere risultati imprevisti. Il completamento dello scambio del quadrante può richiedere un po' di tempo.

Determina invece se l'app di chiamata ha un riferimento al quadrante attivo come mostrato nello snippet precedente e poi chiama updateWatchFace(). Se updateWatchFace() viene completato correttamente, puoi presumere che la tua app abbia ancora il controllo del quadrante attivo.

Fornire un quadrante predefinito

Il push dei quadranti offre la possibilità di installare un quadrante predefinito quando l'app del marketplace è installata. Questa operazione non imposta di per sé il quadrante predefinito come attivo (vedi Impostare il quadrante attivo), ma garantisce che il quadrante sia disponibile nel selettore di quadranti di sistema.

Per usare questa funzionalità:

1. Nella build dell'app Wear OS, includi il quadrante predefinito nel percorso: assets/default_watchface.apk

2. Aggiungi la seguente voce al tuo AndroidManifest.xml

   <application ...>
   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   

Nota: un pattern di build tipico include la creazione del tuo default_watchface.apk come parte della build complessiva dell'app come passaggio di pre-build. Puoi utilizzarlo per compilare il valore del manifest del token di convalida facendo in modo che il processo di build del quadrante predefinito restituisca un file XML di risorse Android aggiuntivo e includa il percorso delle risorse come percorso delle risorse aggiuntivo all'interno dell'app principale. Questo approccio è più semplice rispetto al tentativo di manipolare il file manifest durante il processo di build.

Impostare il quadrante attivo

Il push dei quadranti fornisce i mezzi all'app del marketplace per impostare il quadrante attivo.

Ciò significa in particolare che l'app può impostare il quadrante attivo su uno appartenente al marketplace nel caso in cui il quadrante attivo corrente non appartenga al marketplace. Tieni presente che nel caso in cui il marketplace abbia già il quadrante attivo, il passaggio a un altro quadrante viene eseguito tramite una chiamata a updateWatchFace per sostituire i contenuti dello slot del quadrante con un altro quadrante.

L'impostazione del quadrante attivo è un processo in due fasi:

1. Acquisisci l'autorizzazione Android necessaria per impostare il quadrante attivo.
2. Chiama il metodo setWatchFaceAsActive.

Acquisire le autorizzazioni per impostare il quadrante attivo

L'autorizzazione richiesta è SET_PUSHED_WATCH_FACE_AS_ACTIVE, che deve essere aggiunta al manifest:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

Poiché si tratta di un'autorizzazione di runtime, la tua app deve richiederla all'utente durante l'esecuzione (valuta l'utilizzo della libreria Accompanist per facilitare questa operazione).

Nota :questa autorizzazione ha un conteggio massimo di rifiuto pari a 1: se l'utente rifiuta la richiesta, quest'ultima non può essere ripresentata. In questo caso, l'app deve indirizzare l'utente alle impostazioni per modificare manualmente l'autorizzazione.

Imposta il quadrante come attivo

Una volta concessa l'autorizzazione, chiama setWatchFaceAsActive sull'ID slot del quadrante che deve essere attivo:

watchFacePushManager.setWatchFaceAsActive(slotId)

Nota :il quadrante attivo può essere impostato in questo modo una sola volta. Se l'utente passa a un quadrante di un altro sviluppatore, la chiamata a questa API per impostare di nuovo il quadrante attivo sul tuo quadrante genera un'eccezione.

Una volta utilizzato questo metodo, l'app Telefono dovrebbe invece offrire indicazioni su come impostare manualmente il quadrante attivo.

Leggere metadati aggiuntivi dall'APK del quadrante

L'oggetto WatchFaceSlot fornisce anche i mezzi per ottenere informazioni aggiuntive che puoi dichiarare sul quadrante.

Ciò può essere utile soprattutto in scenari in cui sono presenti varianti minori della stessa quadrante. Ad esempio, potresti avere un quadrante definito:

• Nome pacchetto: com.myapp.watchfacepush.mywatchface
• Versione del pacchetto: 1.0.0

Tuttavia, questo quadrante potrebbe essere fornito come quattro APK diversi, tutti quasi identici, ma con colori predefiniti diversi: rosso, giallo, verde e blu, impostati in un ColorConfiguration nel file XML di Watch Face Format.

Questa leggera variazione si riflette poi in ciascuno dei quattro APK:

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

L'utilizzo di una proprietà personalizzata consente alla tua app di determinare quale di queste varianti è installata:

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

Nota: nell'esempio precedente, lo spazio dei nomi doveva essere specificato per la proprietà perché none è stato dichiarato nella proprietà. Se la proprietà include un punto (.), non è necessario, quindi una proprietà denominata abc.def può essere recuperata utilizzando getMetaDataValues("abc.def").

Considerazioni

Considerazioni importanti da tenere presenti quando implementi il push dei quadranti nella tua app includono il consumo energetico, la memorizzazione nella cache, l'aggiornamento dei quadranti in bundle e la fornitura di un quadrante predefinito rappresentativo.

Potenza

Un aspetto fondamentale per qualsiasi app in esecuzione su Wear OS è il consumo energetico. Per il componente Wear OS della tua app del marketplace:

1. La tua app deve essere eseguita il meno possibile e con la frequenza più bassa possibile (a meno che non sia direttamente utilizzata dall'utente). Ad esempio:
   • Riduzione al minimo dell'attivazione dell'app dall'app Telefono
   • Riduzione al minimo dell'esecuzione dei job WorkManager
2. Pianifica la generazione di report di analisi quando lo smartwatch è in carica:
   1. Se vuoi segnalare statistiche sull'utilizzo dall'app Wear OS o altre metriche, utilizza WorkManager con il vincolo requiresCharging.
3. Pianifica gli aggiornamenti per quando lo smartwatch è in carica e utilizza il Wi-Fi:
   1. Ti consigliamo di controllare le versioni dei quadranti installati e aggiornarli automaticamente. Anche in questo caso, utilizza il vincolo requiresCharging e il tipo di rete UNMETERED per requiresNetworkType.
   2. Quando è in carica, è probabile che il dispositivo abbia accesso al Wi-Fi. Richiedi il Wi-Fi per scaricare rapidamente gli APK aggiornati e rilascia la rete al termine dell'operazione.
   3. Queste stesse indicazioni si applicano nel caso in cui il marketplace offra un quadrante dell'orologio del giorno: scaricalo in anticipo mentre lo smartwatch è in carica.
4. Non pianificare job per controllare il quadrante attivo:
   1. Il controllo periodico per verificare se il tuo marketplace ha ancora il quadrante attivo e quale quadrante è, consuma la batteria. Evita questo approccio.
5. Non utilizzare le notifiche sullo smartwatch:
   1. Se la tua app utilizza le notifiche, concentrati sullo smartphone, dove l'azione dell'utente apre l'app Telefono per continuare il percorso. Assicurati che questi non vengano trasferiti all'app per lo smartwatch utilizzando setLocalOnly.

Memorizzazione nella cache

Nell'esempio di marketplace canonico, i quadranti vengono trasferiti dallo smartphone allo smartwatch. Questa connessione è in genere una connessione Bluetooth, che può essere piuttosto lenta.

Per offrire una migliore esperienza utente e risparmiare energia di ritrasmissione, valuta la possibilità di implementare una piccola cache nel dispositivo Wear OS per archiviare una manciata di APK.

Nel caso in cui l'utente provi un altro quadrante ma poi decida di ripristinare quello scelto in precedenza, questa azione è quasi istantanea.

Allo stesso modo, può essere utilizzato per la prememorizzazione nella cache del quadrante del giorno o schemi simili in cui i quadranti vengono scaricati mentre il dispositivo Wear OS è in carica.

Aggiornare i quadranti preinstallati

La tua app potrebbe includere un asset quadrante predefinito come descritto in precedenza. È importante riconoscere che, sebbene questo quadrante orologio venga installato nel sistema quando viene installata l'app marketplace, il quadrante orologio non viene aggiornato se una versione più recente viene inclusa in qualsiasi aggiornamento dell'app marketplace.

Per gestire questa situazione, l'app del marketplace deve rimanere in ascolto dell'intent di trasmissione MY_PACKAGE_REPLACED e verificare la necessità di aggiornare qualsiasi quadrante orologio in bundle dagli asset del pacchetto.

Quadrante predefinito rappresentativo

Un quadrante predefinito è un ottimo modo per aiutare gli utenti a scoprire e utilizzare il tuo marketplace: il quadrante viene installato quando viene installato il marketplace, in modo che gli utenti possano trovarlo nella galleria di quadranti.

Alcune considerazioni da fare quando si utilizzano i quadranti predefiniti:

• Non utilizzare removeWatchFace se l'utente sceglie di disinstallare un quadrante dall'app marketplace. In questo caso, ripristina il quadrante predefinito utilizzando updateWatchFace. In questo modo, gli utenti possono trovare il tuo quadrante e impostarlo dalla galleria.
• Rendi il quadrante predefinito semplice e immediatamente riconoscibile grazie al tuo logo e al tema. In questo modo gli utenti possono trovarlo nella galleria di quadranti.

• Aggiungi un pulsante al quadrante predefinito per aprire l'app Telefono. Questa operazione può essere eseguita in due fasi:

  1. Aggiungi un elemento Launch al quadrante per avviare un intent utilizzando l'app Wear OS, ad esempio:

     <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

  2. In LaunchOnPhoneActivity, avvia l'app Telefono utilizzando RemoteActivityHelper.