Wear OS App für Push-Mitteilungen zu Zifferblättern konfigurieren

Mit Watch Face Push kann Ihre App Zifferblätter auf einem Wear OS-Gerät verwalten. Dazu gehören das Hinzufügen, Aktualisieren und Entfernen von Zifferblättern sowie das Festlegen des aktiven Zifferblatts. Konfiguriere deine Wear OS App für die Verwendung der Watch Face Push API.

Einrichten

Fügen Sie die Abhängigkeit androidx.wear.watchfacepush:watchfacepush in Ihre build.gradle.kts-Datei ein.

Fügen Sie zum AndroidManifest.xml Folgendes hinzu:

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

Referenz zur Manager-Instanz abrufen

WatchFacePushManager-Instanz abrufen:

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager bietet Zugriff auf alle Methoden für die Interaktion mit Watch Face Push.

Mit Slots arbeiten

Ein wichtiges Konzept bei der Verwendung von Watch Face Push sind Slots. Slots sind eine Möglichkeit, auf installierte Zifferblätter zuzugreifen, die zu Ihrer Anwendung gehören. Das System legt eine maximale Anzahl von Slots fest, die ein Marktplatz haben kann. Bei Wear OS 6 liegt das Limit bei 1.

Beim Aktualisieren oder Entfernen eines Zifferblatts wird slotId verwendet, um das Zifferblatt zu identifizieren, auf das sich der Vorgang bezieht.

Zifferblätter auflisten

Verwenden Sie listWatchFaces(), um die installierten Zifferblätter aufzulisten:

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")

So können Sie feststellen, ob der Slot verfügbar ist oder ob das vorhandene Zifferblatt ersetzt werden muss, um ein weiteres hinzuzufügen. Die Liste enthält auch Details zum installierten Zifferblatt. So prüfen Sie beispielsweise, ob ein bestimmtes Zifferblattpaket installiert ist:

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

Zifferblatt hinzufügen

Wenn gemäß der listWatchFaces-Antwort Slots verfügbar sind, sollte die addWatchFace()-Methode verwendet werden:

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: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}

Zifferblatt aktualisieren

Wenn Sie ein Zifferblatt aktualisieren, können Sie den Inhalt eines bestimmten Slots durch ein neues Paket ersetzen. Das kann entweder ein Upgrade des Zifferblatts auf eine neuere Version oder ein vollständiger Austausch des Zifferblatts sein.

// 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
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}

Zifferblatt entfernen

So entfernen Sie ein Zifferblatt:

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

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}

So ist Ihr Zifferblatt immer in der Systemauswahl für Zifferblätter zu finden. Sie können Ihr Logo gut sichtbar präsentieren und sogar eine Schaltfläche einfügen, über die Ihre Marketplace-App auf dem Smartphone gestartet wird.

Prüfen, ob Ihr Zifferblatt aktiv ist

Es ist wichtig, festzustellen, ob das aktive Zifferblatt in Ihrem Marketplace festgelegt ist, um dem Nutzer eine reibungslose Nutzung zu ermöglichen: Wenn das aktive Zifferblatt bereits im Marketplace festgelegt ist und der Nutzer ein anderes Zifferblatt auswählen möchte, muss er das aktuelle Zifferblatt nur über die Marketplace-App ersetzen, damit die Änderung wirksam wird. Wenn auf dem Marktplatz jedoch nicht das aktive Zifferblatt festgelegt ist, muss die Smartphone-App dem Nutzer weitere Informationen bieten. Weitere Informationen dazu, wie Sie diese Nutzererfahrung handhaben, finden Sie im Abschnitt zur Smartphone-App.

So ermitteln Sie, ob auf dem Marktplatz das aktive Zifferblatt festgelegt ist:

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

Standardzifferblatt bereitstellen

Mit Watch Face Push können Sie ein Standardzifferblatt installieren, wenn Ihre Marketplace-App installiert wird. Dadurch wird das Standardzifferblatt nicht automatisch als aktiv festgelegt (siehe Aktives Zifferblatt festlegen), aber Ihr Zifferblatt wird in der Systemauswahl für Zifferblätter verfügbar.

Wenn du diese Funktion verwenden möchtest, geh so vor:

  1. Fügen Sie in den Build Ihrer Wear OS App das Standard-Zifferblatt in den Pfad ein: assets/default_watchface.apk

  2. Fügen Sie Ihrer AndroidManifest.xml den folgenden Eintrag hinzu:

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

Aktives Zifferblatt festlegen

Mit dem Watch Face Push kann die Marketplace-App das aktive Zifferblatt festlegen.

Das bedeutet konkret, dass die App das aktive Zifferblatt auf eines festlegen kann, das zum Marketplace gehört, wenn das aktuelle aktive Zifferblatt nicht zum Marketplace gehört. Wenn das aktive Zifferblatt bereits auf dem Marktplatz verfügbar ist, wird es durch einen Aufruf von updateWatchFace geändert. Dabei wird der Inhalt des Zifferblatt-Slots durch ein anderes Zifferblatt ersetzt.

Das aktive Zifferblatt wird in zwei Schritten festgelegt:

  1. Die für das Festlegen des aktiven Zifferblatts erforderliche Android-Berechtigung wird angefordert.
  2. Rufen Sie die Methode setWatchFaceAsActive auf.

Berechtigungen zum Festlegen des aktiven Zifferblatts erhalten

Die erforderliche Berechtigung ist SET_PUSHED_WATCH_FACE_AS_ACTIVE. Sie muss Ihrem Manifest hinzugefügt werden:

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

Da es sich um eine Laufzeitberechtigung handelt, muss Ihre App diese Berechtigung vom Nutzer anfordern, wenn die App ausgeführt wird. Die Accompanist-Bibliothek kann Ihnen dabei helfen.

Zifferblatt als aktiv festlegen

Nachdem die Berechtigung erteilt wurde, rufen Sie setWatchFaceAsActive mit der Slot-ID des Zifferblatts auf, das aktiv sein soll.

Wenn diese Methode verwendet wurde, sollte Ihre Smartphone-App stattdessen eine Anleitung zum manuellen Festlegen des aktiven Zifferblatts enthalten.

Zusätzliche Metadaten aus dem APK des Zifferblatts lesen

Das WatchFaceSlot-Objekt bietet auch die Möglichkeit, zusätzliche Informationen abzurufen, die Sie auf Ihrem Zifferblatt deklarieren können.

Das kann besonders in Szenarien nützlich sein, in denen Sie kleinere Varianten desselben Zifferblatts haben. Sie könnten beispielsweise ein Zifferblatt so definieren:

  • Paketname: com.myapp.watchfacepush.mywatchface
  • Paketversion: 1.0.0

Dieses Zifferblatt kann jedoch als vier verschiedene APKs vorliegen, die alle fast identisch sind, aber unterschiedliche Standardfarben haben: Rot, Gelb, Grün und Blau, die in einem ColorConfiguration im Watch Face-Format-XML festgelegt sind.

Diese geringfügige Abweichung wird dann in jedem der vier APKs berücksichtigt:

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

Mithilfe eines benutzerdefinierten Attributs kann Ihre App ermitteln, welche dieser Varianten installiert ist:

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")

Wissenswertes

Wichtige Aspekte bei der Implementierung von Watch Face Push in Ihrer App sind der Stromverbrauch, das Caching, das Aktualisieren von gebündelten Zifferblättern und die Bereitstellung eines repräsentativen Standardzifferblatts.

Leistung

Ein wichtiger Aspekt für jede App, die unter Wear OS ausgeführt wird, ist der Stromverbrauch. Für die Wear OS-Komponente Ihrer Marketplace-App:

  1. Ihre App sollte so selten wie möglich ausgeführt werden, es sei denn, der Nutzer interagiert direkt mit ihr. Dazu gehören:
    • Minimieren des Aufweckens der App über die Telefon App
    • Ausführung von WorkManager-Jobs minimieren
  2. Analytics-Berichte nur dann erstellen, wenn die Smartwatch geladen wird:
    1. Wenn Sie Nutzungsstatistiken aus der Wear OS-App oder andere Messwerte melden möchten, verwenden Sie WorkManager mit der Einschränkung requiresCharging.
  3. Updates planen, wenn die Smartwatch aufgeladen wird und WLAN verwendet:
    1. Du kannst die Versionen der installierten Zifferblätter prüfen und sie automatisch aktualisieren lassen. Verwenden Sie auch hier die Einschränkung requiresCharging und den Netzwerktyp UNMETERED für requiresNetworkType.
    2. Wenn das Gerät geladen wird, hat es wahrscheinlich Zugriff auf WLAN. WLAN anfordern, um die aktualisierten APKs schnell herunterzuladen, und das Netzwerk nach Abschluss freigeben.
    3. Diese Anleitung gilt auch für den Fall, dass der Marktplatz ein Zifferblatt des Tages anbietet. Lade es vorab herunter, während die Smartwatch geladen wird.
  4. Keine Jobs zum Prüfen des aktiven Zifferblatts planen:
    1. Das regelmäßige Prüfen, ob auf Ihrem Marktplatz noch das aktive Zifferblatt vorhanden ist und welches Zifferblatt es ist, belastet den Akku. Wir raten aber dringend davon ab.
  5. Benachrichtigungen auf der Smartwatch nicht verwenden:
    1. Wenn Ihre App Benachrichtigungen verwendet, sollten diese auf dem Smartphone angezeigt werden. Durch die Nutzeraktion wird die Smartphone-App geöffnet, um den Vorgang fortzusetzen. Konfiguriere Benachrichtigungen so, dass sie nicht an die Smartwatch-App weitergeleitet werden, indem du setLocalOnly verwendest.

Caching läuft...

Im kanonischen Marketplace-Beispiel werden Zifferblätter vom Smartphone auf die Smartwatch übertragen. Diese Verbindung ist in der Regel eine Bluetooth-Verbindung, die recht langsam sein kann.

Um sowohl eine bessere Nutzerfreundlichkeit zu bieten als auch die Sendeleistung zu schonen, solltest du auf dem Wear OS-Gerät einen kleinen Cache implementieren, in dem einige APKs gespeichert werden.

Wenn der Nutzer ein anderes Zifferblatt ausprobiert, sich dann aber entscheidet, zum zuvor ausgewählten Zifferblatt zurückzukehren, erfolgt diese Aktion fast sofort.

Dies kann auch für das Vorab-Caching für das Zifferblatt des Tages oder ähnliche Schemata verwendet werden, bei denen Zifferblätter heruntergeladen werden, während das Wear OS-Gerät geladen wird.

Vorinstallierte Zifferblätter aktualisieren

Ihre App kann ein Standard-Zifferblatt-Asset enthalten, wie oben beschrieben. Es ist wichtig zu wissen, dass das Zifferblatt zwar im System installiert wird, wenn Ihre Marketplace-App installiert wird, aber nicht aktualisiert wird, wenn eine neuere Version mit einem Update Ihrer Marketplace-App gebündelt wird.

Um diese Situation zu bewältigen, sollte Ihre Marketplace-App auf die Broadcast-Aktion MY_PACKAGE_REPLACED warten und prüfen, ob ein gebündeltes Zifferblatt aus Paket-Assets aktualisiert werden muss.

Repräsentatives Standardzifferblatt

Ein Standardzifferblatt ist eine gute Möglichkeit, Nutzern zu helfen, Ihren Marketplace zu entdecken und zu verwenden: Das Zifferblatt wird installiert, wenn Ihr Marketplace installiert wird. Nutzer können es also in der Zifferblattgalerie finden.

Einige Überlegungen bei der Verwendung von Standard-Zifferblättern:

  • Verwende removeWatchFace nicht, wenn der Nutzer ein Zifferblatt aus deiner Marketplace-App deinstalliert. Stelle in diesem Fall stattdessen das Standardzifferblatt mit updateWatchFace wieder her. So können Nutzer dein Zifferblatt in der Galerie leichter finden und einrichten.
  • Das Standard-Zifferblatt sollte einfach und durch Ihr Logo und Design sofort erkennbar sein. So können Nutzer das Zifferblatt in der Zifferblattgalerie leichter finden.

  • Fügen Sie dem Standardzifferblatt eine Schaltfläche hinzu, um die Telefon App zu öffnen. Dies kann in zwei Schritten erfolgen:

    1. Fügen Sie dem Zifferblatt ein Launch-Element hinzu, um einen Intent über die Wear OS App zu starten, z. B.:

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

    2. Starten Sie in LaunchOnPhoneActivity die Telefon App mit RemoteActivityHelper.