Configurare l'app Wear OS per il push dei quadranti

La funzionalità Push dei quadranti consente alla tua app di gestire i quadranti su un dispositivo Wear OS. Sono incluse l'aggiunta, l'aggiornamento e la rimozione dei quadranti, nonché l'impostazione del quadrante attivo. Configura l'app Wear OS in modo da utilizzare l'API Watch Face Push.

Configura

Includi le dipendenze necessarie:

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

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>

Ottenere un riferimento all'istanza di gestione

Ottieni un'istanza di WatchFacePushManager:

val manager = WatchFacePushManager(context)

WatchFacePushManager fornisce l'accesso a tutti i metodi per interagire con Push del quadrante.

Lavorare con gli slot

Un concetto chiave quando si lavora con Watch Face Push è 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.

Elenco dei quadranti

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

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

In questo modo puoi stabilire se lo spazio è disponibile o se l'aggiunta di un altro quadrante richiede la sostituzione di quello esistente. L'elenco fornisce inoltre dettagli sul quadrante 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 spazi, come stabilito 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.
}

Aggiornare un quadrante

L'aggiornamento di un quadrante ti consente di sostituire i contenuti di una determinata posizione 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.
}

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

Controllare se il quadrante è attivo

È importante stabilire se il tuo marketplace ha impostato il quadrante attivo per garantire all'utente un'esperienza fluida: se il marketplace ha già impostato il quadrante attivo, l'utente che vuole scegliere un altro quadrante deve solo sostituire quello attuale tramite l'app del marketplace per far sì che la modifica venga applicata. Tuttavia, se il marketplace non ha impostato il quadrante attivo, l'app per smartphone deve offrire all'utente ulteriori indicazioni. Per ulteriori dettagli su come gestire questa esperienza utente, consulta la sezione sull'app per smartphone.

Per determinare se il marketplace ha impostato il quadrante attivo:

Fornire un quadrante predefinito

La funzionalità Push dei quadranti offre la possibilità di installare un quadrante predefinito quando è installata la tua app del marketplace. Ciò non imposta automaticamente il quadrante predefinito come attivo (vedi Impostazione del quadrante attivo), ma garantisce che il quadrante sia disponibile nel selettore dei quadranti di sistema.

Per usare questa funzionalità:

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

  2. Aggiungi la seguente voce a AndroidManifest.xml

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

Impostare il quadrante attivo

La funzionalità Push del quadrante fornisce all'app del marketplace i mezzi 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, se il marketplace ha già il quadrante attivo, la sostituzione con un altro quadrante viene eseguita tramite una chiamata a updateWatchFace per sostituire i contenuti della posizione del quadrante con un altro quadrante.

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

  1. Acquisisci l'autorizzazione Android richiesta 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 al momento dell'esecuzione (considera la libreria Accompanist per ricevere assistenza in merito).

Impostare il quadrante come attivo

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

watchFacePushManager.setWatchFaceAsActive(slotId)

Una volta utilizzato questo metodo, l'app per smartphone 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.

Questa operazione può essere utile in particolare in scenari in cui sono presenti varianti minori dello stesso quadrante. Ad esempio, potresti avere definito un quadrante:

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

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

Questa lieve 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()

Considerazioni

Alcune considerazioni importanti da tenere presenti quando implementi la funzionalità Push dei quadranti nella tua app includono l'attenzione al consumo energetico, alla memorizzazione nella cache, all'aggiornamento dei quadranti in dotazione e alla fornitura di un quadrante predefinito rappresentativo.

Potenza

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

  1. L'app deve essere eseguita il meno possibile e con la minore frequenza possibile (a meno che non sia stata oggetto di interazione diretta da parte dell'utente). Ad esempio:
    • Ridurre al minimo l'attivazione dell'app dall'app Telefono
    • Riduci al minimo l'esecuzione dei job WorkManager
  2. Pianifica i report di analisi per quando lo smartwatch è in carica:
    1. Se vuoi registrare le statistiche sull'utilizzo dall'app Wear OS o da 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 di aggiornarli automaticamente. Anche in questo caso, utilizza il vincolo requiresCharging e il tipo di rete UNMETERED per requiresNetworkType.
    2. Quando è in carica, il dispositivo ha probabilmente accesso al Wi-Fi. Richiedi la connessione Wi-Fi per scaricare rapidamente gli APK aggiornati e, al termine, rilascia la rete.
    3. Queste stesse indicazioni si applicano anche nel caso in cui il marketplace offra un quadrante del giorno. Precaricalo mentre lo smartwatch è in carica.
  4. Non pianificare job per controllare il quadrante attivo:
    1. Il controllo periodico della presenza sul tuo marketplace del quadrante attivo e del quadrante in questione comporta un consumo della 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 non vengano trasferiti all'app dello smartwatch utilizzando setLocalOnly.

Memorizzazione nella cache

Nell'esempio di marketplace canonico, i quadranti vengono trasferiti dal telefono allo smartwatch. In genere si tratta di una connessione Bluetooth, che può essere piuttosto lenta.

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

Se l'utente prova un altro quadrante, ma poi decide di tornare a quello scelto in precedenza, questa azione è quasi istantanea.

Analogamente, questa funzionalità può essere utilizzata per la memorizzazione nella cache per il quadrante del giorno o per schemi simili in cui i quadranti vengono scaricati durante la ricarica del dispositivo Wear OS.

Aggiornare i quadranti in bundle

La tua app può includere un asset del quadrante predefinito come descritto in precedenza. È importante sapere che, anche se questo quadrante è installato nel sistema quando è installata l'app del marketplace, non viene aggiornato se una versione più recente è inclusa in un aggiornamento dell'app del marketplace.

Per gestire questa situazione, l'app del marketplace deve ascoltare l'azione di trasmissione MY_PACKAGE_REPLACED e verificare la necessità di aggiornare eventuali quadranti in bundle dagli asset del pacchetto.

Quadrante orologio 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 dei quadranti.

Alcune considerazioni per l'utilizzo dei quadranti predefiniti:

  • Non utilizzare removeWatchFace se l'utente sceglie di disinstallare un quadrante dalla tua 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 tramite il logo e il tema. In questo modo gli utenti possono trovarlo nella galleria dei quadranti.

  • Aggiungi un pulsante al quadrante predefinito per aprire l'app Telefono. Puoi eseguire questa operazione 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.