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 erforderlichen Abhängigkeiten hinzu:

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

Fügen Sie zum AndroidManifest.xml Folgendes hinzu:

<?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>

Verweis auf die Manager-Instanz abrufen

Rufen Sie eine Instanz von WatchFacePushManager ab:

val manager = 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 Marketplace 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, für das der Vorgang ausgeführt werden soll.

Zifferblätter auflisten

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

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.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) = watchFacePush.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: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

Hinweis :Speichern Sie keine slotId-Werte und behandeln Sie sie nicht als dauerhaft. Der Status kann sich außerhalb Ihrer Anwendung ändern. Ein Nutzer kann beispielsweise Ihr Zifferblatt über die System-UI deinstallieren. Rufen Sie den aktuellen Status immer unmittelbar vor einem slotbasierten Vorgang ab.

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

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

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

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

Hinweis :Überlegen Sie, ob Ihre App removeWatchFace überhaupt aufrufen sollte. Stattdessen solltest du das Zifferblatt durch ein Standardzifferblatt ersetzen, wenn der Nutzer in deiner Marketplace-App darauf tippt, um es zu deinstallieren.

So wird sichergestellt, dass Ihr Zifferblatt immer in der Systemauswahl für Zifferblätter zu finden ist, Ihr Logo gut sichtbar platziert werden kann und sogar eine Schaltfläche zum Starten Ihrer Marketplace-App auf dem Smartphone enthalten sein kann.

Prüfen, ob Ihr Zifferblatt aktiv ist

Es ist wichtig, festzustellen, ob auf Ihrem Marktplatz das aktive Zifferblatt festgelegt ist, um den Nutzern eine reibungslose Nutzung zu ermöglichen. Wenn das aktive Zifferblatt bereits auf dem Marktplatz festgelegt ist, muss der Nutzer nur das aktuelle Zifferblatt über die Marktplatz-App ersetzen, wenn er ein anderes Zifferblatt auswählen möchte. Wenn auf dem Marktplatz nicht das aktive Zifferblatt festgelegt ist, muss die Smartphone-App dem Nutzer jedoch weitere Informationen bieten. Weitere Informationen dazu, wie Sie mit dieser Nutzererfahrung umgehen, finden Sie im Abschnitt zur Telefon-App.

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

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

Warnung :Rufen Sie nach dem Aufrufen von updateWatchFace() nicht sofort isWatchFaceActive() auf, da dies zu unerwarteten Ergebnissen führen kann. Es kann eine Weile dauern, bis das Zifferblatt gewechselt wurde.

Ermittle stattdessen zuerst, ob die aufrufende App einen Verweis auf das aktive Zifferblatt hat, wie im vorherigen Snippet gezeigt, und rufe dann updateWatchFace() auf. Wenn updateWatchFace() erfolgreich abgeschlossen wird, kannst du davon ausgehen, dass deine App weiterhin die Kontrolle über das aktive Zifferblatt hat.

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). Es wird jedoch dafür gesorgt, dass Ihr Zifferblatt in der Systemauswahl für Zifferblätter verfügbar ist.

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:

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

Hinweis :Bei einem typischen Build-Muster wird Ihr default_watchface.apk als Vorab-Build-Schritt im Rahmen des gesamten App-Builds erstellt. Damit können Sie den Manifestwert für das Validierungstoken festlegen, indem Sie den Standard-Buildprozess für das Zifferblatt so konfigurieren, dass eine zusätzliche Android-Ressourcen-XML-Datei ausgegeben wird. Fügen Sie dann den Ressourcenpfad als zusätzlichen Ressourcenpfad in Ihre Haupt-App ein. Dieser Ansatz ist einfacher als die Manifestdatei selbst während des Buildprozesses zu bearbeiten.

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, um den Inhalt des Zifferblatt-Slots durch ein anderes Zifferblatt zu ersetzen.

Das aktive Zifferblatt wird in zwei Schritten festgelegt:

1. Die für das Festlegen des aktiven Zifferblatts erforderliche Android-Berechtigung muss eingeholt werden.
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:

<?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>

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.

Hinweis : Für diese Berechtigung gilt eine maximale Anzahl von Ablehnungen von 1. Wenn der Nutzer die Anfrage ablehnt, kann sie nicht noch einmal gestellt werden. In diesem Fall sollte die App den Nutzer zu den Einstellungen weiterleiten, damit er die Berechtigung manuell anpassen kann.

Zifferblatt als aktiv festlegen

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

watchFacePushManager.setWatchFaceAsActive(slotId)

Hinweis :Das aktive Zifferblatt kann auf diese Weise nur einmal festgelegt werden. Wenn der Nutzer zu einem Zifferblatt eines anderen Entwicklers wechselt, wird beim Aufrufen dieser API zum Zurücksetzen des aktiven Zifferblatts auf Ihr Zifferblatt eine Ausnahme ausgelöst.

Nachdem 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:

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

Hinweis :Im vorherigen Beispiel musste der Namespace für das Attribut angegeben werden, da none für das Attribut deklariert wurde. Wenn das Attribut einen Punkt (.) enthält, ist dies nicht erforderlich. Ein Attribut mit dem Namen abc.def kann also mit getMetaDataValues("abc.def") abgerufen werden.

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 auf 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 Aktivierens der App über die Telefon App
   • Ausführung von WorkManager-Jobs minimieren
2. Analysenberichte für den Ladevorgang der Smartwatch planen:
   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 auf dem Marktplatz ein Zifferblatt des Tages angeboten wird. 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. Achte darauf, dass diese nicht über setLocalOnly in die Smartwatch-App übertragen werden.

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 Leistung für die erneute Übertragung 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 bei der Installation Ihrer Marketplace-App auf dem System 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 Ihr Zifferblatt in der Galerie finden und festlegen.
• 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. Das geht in zwei Schritten:

  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.