Push del quadrante

Wear OS 6 introduce una nuova API, Watch Face Push, che crea opportunità per casi d'uso di pubblicazione di quadranti più avanzati.

Quando utilizzare Watch Face Push

Watch Face Push è un'API su Wear OS che consente allo sviluppatore di aggiungere, aggiornare o rimuovere i quadranti direttamente. Non è necessaria per lo sviluppo di quadranti standard.

I quadranti utilizzati con Watch Face Push devono essere scritti utilizzando Watch Face Format. Possono includere quadranti progettati utilizzando Watch Face Designer, Watch Face Studio o qualsiasi altro strumento che produce quadranti che utilizzano Watch Face Format.

Sebbene l'API Watch Face Push possa essere utilizzata in diversi modi, la seguente tabella ti guida attraverso i principali casi d'uso:

Caso d'uso Soluzione consigliata complessità
Voglio creare singoli quadranti e pubblicarli. Utilizza Watch Face Format, direttamente o tramite uno strumento come Watch Face Designer o Watch Face Studio, e pubblicali su Google Play. Bassa
Voglio creare un'app per smartphone che consenta agli utenti di selezionare i quadranti da una raccolta curata o di progettare e personalizzare i quadranti per l'installazione direttamente sul proprio smartwatch Wear OS. Crea un'app, sia per smartwatch che per smartphone, utilizzando l'API Watch Face Push sullo smartwatch. Alta

Finalità

Il caso d'uso canonico per l'API Watch Face Push è la creazione di un'app marketplace. Da questa app, gli utenti possono selezionare i quadranti da una raccolta curata sul proprio smartphone e controllare direttamente l'installazione di questi quadranti sul proprio smartwatch connesso.

Considerazioni

Per informazioni dettagliate sulla creazione dei quadranti, consulta le linee guida di Watch Face Format: i quadranti implementati utilizzando Watch Face Push sono quadranti Watch Face Format normali.

Quando crei il quadrante, tieni presente le seguenti considerazioni.

Nomi pacchetto

I quadranti installati utilizzando Watch Face Push devono rispettare la seguente convenzione:

<app name>.watchfacepush.<watchface name>

... dove <app name> è il nome del pacchetto dell'app che chiama l'API Watch Face Push.

Ad esempio, per un'app con il nome del pacchetto com.example.mymarketplace, i seguenti sono nomi di pacchetti di quadranti validi:

  • com.example.mymarketplace.watchfacepush.watchface1
  • com.example.mymarketplace.watchfacepush.watchface2
  • com.example.mymarketplace.watchfacepush.another_watchface

L'API rifiuta i quadranti che non rispettano questa convenzione.

Contenuti del pacchetto

Il sistema applica rigorosamente i contenuti dell'APK. È tecnicamente possibile produrre APK Watch Face Format che contengono file di metadati innocui e altri artefatti, che potrebbero essere accettabili per Google Play ma non superano la convalida di Watch Face Push (vedi sotto).

Ogni APK del quadrante deve contenere solo i seguenti file/percorsi:

  • /AndroidManifest.xml
  • /resources.arsc
  • /res/**
  • /META-INF/**

Inoltre, il file AndroidManifest.xml deve contenere solo i seguenti tag:

  • <manifest>
  • <uses-feature>
  • <uses-sdk>
  • <application>
  • <property>
  • <meta-data>

Infine, il pacchetto deve specificare un minSdk di almeno 33 e il <application> tag deve specificare l'attributo android:hasCode="false".

Convalida

A differenza dei normali quadranti distribuiti tramite Google Play, l'app del Marketplace è responsabile della verifica che ogni quadrante Watch Face Push sia ben formato e performante.

Watch Face Push utilizza i seguenti controlli di convalida per verificare la qualità di ogni quadrante:

  1. Tutti i quadranti installati o aggiornati tramite l'API Watch Face Push devono superare lo strumento di convalida di Watch Face Push.
  2. Utilizza solo lo strumento di convalida ufficiale per generare token di convalida da utilizzare con l'API.
  3. Lo strumento di convalida deve essere aggiornato quando esegui la convalida.

  4. Non è necessario convalidare nuovamente un APK che non è stato modificato. I token non scadono, anche quando la versione dello strumento di convalida utilizzato viene sostituita.

    Allo stesso tempo, ti consigliamo di eseguire nuovamente la convalida di tanto in tanto, perché lo strumento di convalida viene aggiornato periodicamente.

Esegui il validatore

Il validatore è disponibile in tre forme:

  • Uno strumento CLI
  • Una libreria da utilizzare con la JVM
  • Una libreria da utilizzare su Android

Utilizzo dello strumento di convalida della riga di comando

  1. Ottieni lo strumento di convalida dal repository Maven di Google.

  2. Esegui lo strumento nel seguente modo:

    java -jar validator-push-cli-1.0.0-alpha10.jar \
    --apk_path=<your watch face>.apk \
    --package_name=<your marketplace package name>

    Se l'operazione va a buon fine, l'output include un token di convalida, che devi fornire all'API Watch Face Push quando aggiungi o aggiorni un quadrante.

    Se si verifica un errore, l'output include i dettagli del controllo specifico non riuscito.

Utilizzo dello strumento di convalida della libreria

  1. Includi i repository Google e Jitpack. Entrambi sono necessari per utilizzare la libreria dello strumento di convalida.

    repositories {
    ...
    google()
    maven {
        url = uri("https://jitpack.io")
        content {
            includeGroup("com.github.xgouchet")
        }
    }
}

  2. Includi la dipendenza dello strumento di convalida nel tuo progetto:

    // For use on JVM
implementation("com.google.android.wearable.watchface.validator:validator-push:1.0.0-alpha10")

// For use on Android
implementation("com.google.android.wearable.watchface.validator:validator-push-android:1.0.0-alpha10")

  3. Esegui il validatore:

val validator = DwfValidatorFactory.create() val result = validator.validate(watchFaceFile, appPackageName) if (result.failures().isEmpty()) { val token = result.validationToken() println("Validation token: $token") // Validation success - continue with the token // ... } else { // There were failures, handle them accordingly - validation has failed. result.failures().forEach { failure -> println("FAILURE: ${failure.name()}: ${failure.failureMessage()}") // ... } }

Per un esempio di utilizzo di questa libreria, consulta l'esempio di GitHub. Consulta anche la libreria Portable Asset Compiler Kit (Pack), utile per creare APK sul dispositivo, da utilizzare con lo strumento di convalida basato su Android.

Dimensioni dell'APK

Presta particolare attenzione ai quadranti Watch Face Push per ridurre al minimo le dimensioni dell'APK: è probabile che l'APK del quadrante venga trasmesso dall'app per smartphone all'app dell'orologio tramite Bluetooth, che può essere lento.

Un APK eccessivamente grande potrebbe richiedere un tempo considerevole per la trasmissione, il che comporta una scarsa esperienza utente e un consumo della batteria.

  • Utilizza librerie appropriate come pngquant per ridurre al minimo le dimensioni dei file immagine
    • Includi questa opzione nel processo di compilazione della raccolta di quadranti.
    • Verifica che le dimensioni dell'immagine siano appropriate per la scala in cui la utilizzi.
    • Ritaglia le immagini in modo appropriato per rimuovere lo sfondo circostante.
  • Riduci le dimensioni dei file dei caratteri.

Per ulteriori suggerimenti su come ridurre al minimo le dimensioni dell'APK, consulta le linee guida Ottimizzare la memoria utilizzata.

Firma dell'APK

Come un normale APK, devi firmare tutti i quadranti. Crea una chiave diversa da quella che utilizzi con l'app principale e utilizzala per tutti i quadranti.

Architettura

Considera i quattro componenti principali del sistema:

  1. Spazio di archiviazione basato sul cloud: nell'app del Marketplace canonica, crei e memorizzi i quadranti nel cloud, pronti per essere utilizzati dagli utenti. I quadranti hanno le seguenti proprietà:
    1. Sono precompilati come normali APK Watch Face Format.
    2. Ogni APK contiene un solo quadrante basato su Watch Face Format.
    3. Vengono convalidati con il processo di convalida di Watch Face Push e memorizzati con il token di convalida associato.
    4. La tua app per smartphone può recuperarli in base alle esigenze.
  2. App Telefono: l'app Telefono è il modo principale in cui gli utenti interagiscono con il tuo sistema. Consente loro di:
    1. Sfogliare e cercare nel catalogo dei quadranti.
    2. Installare o sostituire un quadrante sullo smartwatch.
  3. App dell'orologio: in genere l'app dell'orologio non ha un'interfaccia utente significativa. È principalmente un ponte tra l'app per smartphone e le API Watch Face Push, con le seguenti funzionalità:
    1. Utilizzo dell'API Watch Face Push per installare/aggiornare o sostituire i quadranti.
    2. Richiesta delle autorizzazioni necessarie e richiesta all'utente.
    3. Fornitura di un quadrante predefinito.
    4. Fornitura di una cache minima di quadranti.
  4. Comunicazioni tra smartphone e smartwatch: la comunicazione tra l'app per smartphone e l'app dell'orologio è fondamentale per il successo dell'esperienza complessiva. Utilizza le API del livello dati di Wear OS, che consentono di:
    1. Rilevamento dell'installazione: utilizzando Capabilities e CapabilityClient, l'app per smartphone può rilevare l' assenza dell'app dell'orologio e viceversa. Puoi quindi avviare un intent al Play Store per installare il fattore di forma mancante.
    2. Gestione dello stato: utilizzando DataClient o MessageClient, mantieni lo smartphone sincronizzato con lo stato dello smartwatch, ad esempio sincronizzando lo stato del quadrante attivo.
    3. Trasmissione dell'APK: utilizzando ChannelClient o MessageClient, invia gli APK dallo smartphone allo smartwatch.
    4. Invocazione remota: utilizzando Messageclient, lo smartphone può indicare allo smartwatch di chiamare l'API Watch Face Push, ad esempio per installare un quadrante.

Per ulteriori dettagli, consulta le linee guida dell'API del livello dati.