Push del quadrante

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

Identificare quando utilizzare Watch Face Push

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

I quadranti utilizzati con Watch Face Push devono essere scritti utilizzando Watch Face Format. Ciò può includere quadranti progettati utilizzando 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 tabella seguente deve essere utilizzata come guida per i principali casi d'uso:

Storytelling Soluzione consigliata Complessità
Voglio creare singoli quadranti e pubblicarli. Utilizza Watch Face Format, direttamente o tramite uno strumento come 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 loro smartwatch Wear OS. Crea un'app, sia per lo smartwatch che per lo smartphone, utilizzando l'API Watch Face Push sullo smartwatch. Alto

Finalità

Il caso d'uso canonico dell'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 sullo smartwatch connesso.

Considerazioni

Per informazioni dettagliate sulla creazione dei quadranti, consulta le indicazioni relative a Watch Face Format: i quadranti implementati utilizzando Watch Face Push sono normali quadranti Watch Face Format.

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 nome pacchetto com.example.mymarketplace, i seguenti sono nomi pacchetto validi per i quadranti:

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

I quadranti che non rispettano questa convenzione vengono rifiutati dall'API.

Contenuti del pacchetto

I contenuti dell'APK vengono applicati rigorosamente. È necessario prestare attenzione per garantire che Watch Face Format sia conforme ai seguenti vincoli: è 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).

In ogni APK del quadrante sono accettabili solo i seguenti file/percorsi:

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

Inoltre, nel file AndroidManifest.xml sono consentiti solo i seguenti tag:

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

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

Convalida

A differenza dei normali quadranti orologio distribuiti tramite Google Play, i controlli di Watch Face Push per garantire che ogni quadrante sia ben formato e performante sono responsabilità dell'app Marketplace.

Google Play utilizza i seguenti controlli di convalida per verificare la qualità di ogni quadrante che utilizza il push dei quadranti:

  1. Tutti i quadranti installati o aggiornati tramite l'API Watch Face Push devono superare lo strumento di convalida Watch Face Push.
  2. Per generare token di convalida da utilizzare con l'API, può essere utilizzato solo lo strumento di convalida ufficiale.
  3. Lo strumento di convalida utilizzato deve essere aggiornato al momento dell'esecuzione della 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é il validatore viene aggiornato periodicamente.

Esegui lo strumento di convalida

Lo strumento di convalida è 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 a riga di comando

  1. Ottieni il validatore dal repository Maven di Google.

  2. Esegui lo strumento nel seguente modo:

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

    In caso di esito positivo, l'output include un token di convalida, che devi fornire all'API Watch Face Push quando aggiungi o aggiorni un quadrante orologio.

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

Utilizzo dello strumento di convalida della libreria

  1. Includi il repository Jitpack, necessario per la dipendenza del validatore:

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

  2. Includi la dipendenza del validatore nel tuo progetto:

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

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

  3. Esegui lo strumento di convalida:

    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()}")
        // ...
    }
}
    Main.kt

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 il validatore basato su Android.

Dimensioni APK

È necessario prestare particolare attenzione ai quadranti orologio push per assicurarsi che le dimensioni dell'APK siano ridotte al minimo: è probabile che l'APK del quadrante orologio venga trasmesso dall'app per smartphone all'app per smartwatch tramite Bluetooth, che può essere lento.

Un APK troppo grande potrebbe richiedere molto tempo per essere trasmesso, il che comporta sia un'esperienza utente scadente sia un consumo eccessivo della batteria.

  • Utilizza librerie appropriate come pngquant per ridurre al minimo le dimensioni dei file immagine
    • Includi questo elemento nel processo di creazione della raccolta di quadranti
    • Controlla che le dimensioni dell'immagine siano adatte alla scala in cui verrà utilizzata.
    • Assicurati che le immagini siano ritagliate in modo appropriato per rimuovere lo sfondo circostante.
  • Ridurre le dimensioni dei file dei caratteri

Consulta le indicazioni per ottimizzare l'utilizzo della memoria per altri suggerimenti su come ridurre al minimo le dimensioni dell'APK.

Firma dell'APK

Come per un normale APK, tutti i quadranti devono essere firmati. Crea una chiave diversa da quella utilizzata con la tua app principale e usa la chiave diversa per tutti i tuoi quadranti.

Architettura

Considera i tre componenti principali del sistema:

  1. Spazio di archiviazione basato su cloud: nell'app Marketplace canonica, i quadranti vengono creati e archiviati nel cloud, pronti per essere utilizzati dagli utenti. I quadranti sono:
    1. Preinstallati come normali APK di Watch Face Format
    2. Ciascuno contiene un solo quadrante basato su Watch Face Format
    3. Sono state convalidate utilizzando la procedura di convalida push del quadrante e vengono memorizzate insieme al token di convalida associato.
    4. Pronti per essere recuperati dall'app Telefono quando necessario.
  2. App Telefono: l'app Telefono è il modo principale in cui gli utenti interagiscono con il tuo sistema. Consente di:
    1. Sfogliare ed eseguire ricerche nel catalogo di quadranti
    2. Installare o sostituire un quadrante sull'orologio
  3. App per smartwatch: l'app per smartwatch in genere non ha un'interfaccia utente significativa. È principalmente un ponte tra l'app per smartphone e le API Push del quadrante, 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. Fornire un quadrante orologio predefinito
    4. Fornire una cache minima di quadranti
  4. Comunicazioni tra smartphone e smartwatch: la comunicazione tra l'app per smartphone e quella per smartwatch è fondamentale per la riuscita dell'esperienza complessiva. Utilizza le API Wear OS Data Layer, che consentono di:
    1. Rilevamento dell'installazione: utilizzando le funzionalità e l'CapabilityClient, l'app per smartphone può rilevare l'assenza dell'app per smartwatch e viceversa. A questo punto, puoi avviare un intent al Play Store per installare il fattore di forma mancante.
    2. Gestione dello stato: utilizzando DataClient o MessageClient, lo smartphone può essere sincronizzato con lo stato dello smartwatch, ad esempio assicurandosi che lo smartphone sia a conoscenza del quadrante impostato.
    3. Trasmissione APK: utilizzando ChannelClient o MessageClient, gli APK possono essere inviati dallo smartphone allo smartwatch
    4. Chiamata remota: utilizzando Messageclient, lo smartphone può istruire lo smartwatch a chiamare l'API Watch Face Push, ad esempio per installare un quadrante.

Per ulteriori dettagli, consulta le linee guida per l'API Data Layer.