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

Mit „Zifferblatt-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. Konfigurieren Sie Ihre Wear OS-App für die Verwendung der Watch Face Push API.

Einrichten

Fügen Sie die erforderlichen Abhängigkeiten hinzu:

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

Fügen Sie dem 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 Verwaltungsinstanz abrufen

Rufen Sie eine Instanz von WatchFacePushManager ab:

val manager = WatchFacePushManager(context)

WatchFacePushManager bietet Zugriff auf alle Methoden zur Interaktion mit dem Zifferblatt-Push.

Mit Slots arbeiten

Ein wichtiges Konzept bei der Arbeit mit dem Pushen von Zifferblättern sind Slots. Slots sind eine Möglichkeit, installierte Zifferblätter anzusprechen, die zu Ihrer App gehören. Das System legt eine maximale Anzahl von Slots fest, die ein Marktplatz haben kann. Bei Wear OS 6 ist das Limit 1.

Wenn Sie ein Zifferblatt aktualisieren oder entfernen, wird slotId verwendet, um das Zifferblatt zu identifizieren, auf das die Aktion angewendet werden soll.

Zifferblätter auflisten

Verwenden Sie listWatchFaces(), um die Liste der installierten Zifferblätter aufzurufen:

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 Sie das vorhandene Zifferblatt ersetzen müssen, um ein weiteres hinzuzufügen. Die Liste enthält auch Details zum installierten Zifferblatt. So prüfen Sie beispielsweise, ob ein bestimmtes Zifferblatt-Paket 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 Methode addWatchFace() 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.
}

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 auf eine neuere Version desselben Zifferblatts 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.
}

So wird sichergestellt, dass Ihr Zifferblatt immer in der Auswahl der Systemzifferblätter zu finden ist, Ihr Logo gut sichtbar ist und es sogar eine Schaltfläche zum Starten Ihrer Marketplace-App auf dem Smartphone geben kann.

Prüfen, ob das Zifferblatt aktiv ist

Es ist wichtig, festzustellen, ob im Marktplatz das aktive Zifferblatt festgelegt ist, damit Nutzer reibungslos arbeiten können: Wenn im Marktplatz bereits das aktive Zifferblatt festgelegt ist, muss der Nutzer nur das aktuelle über die Marktplatz-App ersetzen, damit dies wirksam wird. Wenn das aktive Zifferblatt jedoch nicht im Marktplatz festgelegt ist, muss die Smartphone-App dem Nutzer mehr Anleitung bieten. Weitere Informationen dazu, wie Sie mit dieser Nutzererfahrung umgehen, finden Sie im Abschnitt zur Telefon-App.

So prüfen Sie, ob im Play Store das aktive Zifferblatt festgelegt ist:

Standard-Zifferblatt angeben

Mit der Funktion „Zifferblatt-Push“ können Sie ein Standard-Zifferblatt installieren, wenn Ihre Marktplatz-App installiert ist. Dadurch wird das Standard-Zifferblatt nicht automatisch als aktiv festgelegt (siehe „Aktives Zifferblatt festlegen“). Es ist aber in der Auswahl der System-Zifferblätter verfügbar.

Um diese Funktionen zu nutzen,

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

  2. Fügen Sie 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" />

Aktives Zifferblatt festlegen

Über die Zifferblatt-Push-Funktion kann die Marktplatz-App das aktive Zifferblatt festlegen.

Das bedeutet konkret, dass die App das aktive Zifferblatt auf ein Zifferblatt festlegen kann, das zum Marktplatz gehört, wenn das derzeit aktive Zifferblatt nicht zum Marktplatz gehört. Wenn der Marktplatz bereits das aktive Zifferblatt hat, wird es durch einen Aufruf von updateWatchFace durch ein anderes Zifferblatt ersetzt.

Das Festlegen des aktiven Zifferblatts erfolgt in zwei Schritten:

  1. Erforderliche Android-Berechtigung zum Festlegen des aktiven Zifferblatts abrufen
  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. Verwenden Sie dazu die Accompanist Library.

Zifferblatt als aktiv festlegen

Rufe nach der Erteilung der Berechtigung setWatchFaceAsActive mit der Slot-ID des Zifferblatts auf, das aktiv sein soll:

watchFacePushManager.setWatchFaceAsActive(slotId)

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

Zusätzliche Metadaten aus dem Zifferblatt-APK lesen

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

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

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

Dieses Zifferblatt kann jedoch in vier verschiedenen APKs vorliegen, die alle fast genau gleich sind, aber unterschiedliche Standardfarben haben: rot, gelb, grün und blau, die in einer ColorConfiguration im XML-Format des Zifferblatts festgelegt sind.

Diese kleine 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 einer benutzerdefinierten Property kann Ihre App ermitteln, welche dieser Varianten installiert ist:

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

Wissenswertes

Wichtige Aspekte bei der Implementierung von Zifferblatt-Push in Ihrer App sind der Energieverbrauch, das Caching, die Aktualisierung der im Lieferumfang enthaltenen Zifferblätter und die Bereitstellung eines repräsentativen Standardzifferblatts.

Leistung

Ein wichtiger Aspekt für jede App, die auf Wear OS ausgeführt wird, ist der Energieverbrauch. Für die Wear OS-Komponente Ihrer Marktplatz-App:

  1. Ihre App sollte so wenig und 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. Analysberichte für die Zeit planen, in der die Smartwatch geladen wird:
    1. Wenn Sie Nutzungsstatistiken aus der Wear OS-App oder andere Messwerte erfassen möchten, verwenden Sie WorkManager mit der Einschränkung requiresCharging.
  3. Updates für die Zeit planen, in der die Smartwatch geladen wird, und WLAN verwenden:
    1. Sie können die Versionen der installierten Zifferblätter prüfen und sie automatisch aktualisieren. Verwenden Sie wieder die Einschränkung requiresCharging und den Netzwerktyp UNMETERED für requiresNetworkType.
    2. Wenn das Gerät geladen wird, hat es wahrscheinlich Zugriff auf WLAN. Wählen Sie ein WLAN aus, um die aktualisierten APKs schnell herunterzuladen, und geben Sie das Netzwerk frei, wenn Sie fertig sind.
    3. Diese Hinweise gelten auch für den Fall, dass der Marktplatz ein Zifferblatt des Tages anbietet. Laden Sie dieses Zifferblatt herunter, während die Smartwatch geladen wird.
  4. Planen Sie keine Jobs zum Überprüfen des aktiven Zifferblatts:
    1. Die regelmäßige Prüfung, ob Ihr Marktplatz noch das aktive Zifferblatt hat und welches das ist, belastet den Akku. Wir raten davon ab.
  5. Benachrichtigungen auf der Smartwatch nicht verwenden:
    1. Wenn in Ihrer App Benachrichtigungen verwendet werden, sollten diese auf dem Smartphone angezeigt werden, damit die Nutzeraktion die Telefon-App öffnet, um den Vorgang fortzusetzen. Achten Sie darauf, dass diese nicht über setLocalOnly zur Smartwatch-App weitergeleitet werden.

Caching läuft...

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

Um die Nutzerfreundlichkeit zu verbessern und die Energie für die erneute Übertragung zu sparen, sollten Sie auf dem Wear OS-Gerät einen kleinen Cache implementieren, in dem einige APKs gespeichert werden.

Wenn der Nutzer ein anderes Zifferblatt ausprobiert, aber dann zum zuvor ausgewählten Zifferblatt zurückkehren möchte, erfolgt diese Aktion nahezu sofort.

Ebenso kann diese Funktion für das Vorab-Caching des Zifferblatts des Tages oder ähnlicher Systeme verwendet werden, bei denen Zifferblätter heruntergeladen werden, während das Wear OS-Gerät geladen wird.

Im Lieferumfang enthaltene Zifferblätter aktualisieren

Ihre App kann ein Standard-Zifferblatt-Asset enthalten, wie oben beschrieben. Dieses Zifferblatt wird zwar beim Installieren Ihrer Marktplatz-App auf dem System installiert, es wird jedoch nicht aktualisiert, wenn eine neuere Version mit einem Update Ihrer Marktplatz-App gebündelt ist.

In diesem Fall sollte Ihre Marktplatz-App auf die Broadcast-Aktion MY_PACKAGE_REPLACED warten und prüfen, ob das im Lieferumfang enthaltene Zifferblatt aus den Paket-Assets aktualisiert werden muss.

Repräsentatives Standard-Zifferblatt

Ein Standardzifferblatt ist eine gute Möglichkeit, Nutzern die Entdeckung und Nutzung Ihres Marktplatzes zu erleichtern: Das Zifferblatt wird installiert, wenn Ihr Marktplatz installiert wird, sodass Nutzer es in der Zifferblattgalerie finden können.

Beachten Sie bei der Verwendung von Standard-Zifferblättern Folgendes:

  • Verwenden Sie removeWatchFace nicht, wenn der Nutzer ein Zifferblatt aus Ihrer Marktplatz-App deinstalliert. Stellen Sie in diesem Fall stattdessen mit updateWatchFace das Standardzifferblatt wieder her. So können Nutzer Ihr Zifferblatt leichter finden und über die Galerie einrichten.
  • Das Standard-Zifferblatt sollte durch Ihr Logo und Ihre Designthemen einfach und sofort erkennbar sein. So können Nutzer es leichter in der Zifferblattgalerie 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 auszuführen, z. B.:

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

    2. Öffnen Sie in LaunchOnPhoneActivity die Telefon App mit RemoteActivityHelper.