App-Kompatibilität auf Wear OS-Geräten verbessern

Die Wear Health Services API (WHS) ist eine obligatorische Komponente für alle Geräte mit Wear OS 3 und höher, da sie eine einheitliche Integrationsoberfläche für Entwickler von Gesundheits- und Fitness-Apps bietet. Entwickeln Sie Ihre App so, dass sie sich problemlos an viele Geräte und ihre unterschiedlichen Funktionen anpasst, um die Kompatibilität zwischen Geräten aufrechtzuerhalten und Probleme mit der Nutzerfreundlichkeit zu vermeiden. Dazu müssen Sie Abhängigkeiten nur für die Clients deklarieren, die von Ihrer App verwendet werden. Außerdem sollte Ihre App die Flexibilität haben, optionale erweiterte Messwerte je nach Verfügbarkeit anzuzeigen oder zu entfernen.

Verschiedene Sensoren generieren Daten mit unterschiedlichen Frequenzen, die je nach Gerät und zugrunde liegender Hardware und Sensorplattform variieren. Ein Gerät kann beispielsweise die Herzfrequenz zu einem bestimmten Zeitstempel und den Standort zu einem anderen zurückgeben. Erstellen Sie Apps, die unabhängige Datenstreams mit unterschiedlichen oder sich überschneidenden Zeitstempeln empfangen können.

In diesem Leitfaden werden die erwarteten Verhaltensweisen und Datentypen beschrieben, die von verschiedenen Clients in Wear Health Services unterstützt werden.

Übungsclient

In den folgenden Abschnitten werden das erwartete Verhalten und die Datentypen von ExerciseClient beschrieben.

Erwartetes Verhalten

Bei der ExerciseClient sind einige Trainingstypen von der Verfügbarkeit bestimmter Datentypen abhängig. So sind beispielsweise Rollstuhl-Trainings nur verfügbar, wenn Rollstuhl-Schübe unterstützt werden. Aktivieren und deaktivieren Sie diese Optionen je nach Verfügbarkeit auf einem bestimmten Gerät.

Die meisten Trainingsdatentypen werden in Intervallen von einer Sekunde erfasst und bereitgestellt. Es gibt jedoch einige Ausnahmen:

  • In einigen Situationen werden bestimmte Trainingsdatentypen mehrmals pro Sekunde aktualisiert. Wenn der Nutzer beispielsweise läuft, wird die Schrittzahl mehr als einmal pro Sekunde aktualisiert.
  • Bei einigen Datentypen wird eine Aktualisierung nur bereitgestellt, wenn sich der aktuelle Wert vom vorherigen Wert unterscheidet.

Die Datenbereitstellung kann entweder als Stream oder als Batch erfolgen. Die Daten werden gestreamt, während der Anwendungsprozessor aktiv ist. Das ist in der Regel der Fall, wenn das Display eingeschaltet ist und Interaktionen möglich sind. Sobald das Display ausgeschaltet wird oder in den Inaktivmodus wechselt (eingeschaltet, aber nicht interaktiv), werden die Daten in Batches verarbeitet, um Energie zu sparen. Die gebündelten Daten werden an die Anwendung gesendet, wenn der Anwendungsprozessor wieder aktiviert wird, entweder weil die Smartwatch aus dem Inaktivmodus wechselt oder weil die Puffer für die Bündelung voll sind. Das hängt vom Gerät ab. Die Samplingrate bleibt gleich, während sich das Gerät im Ambient-Modus befindet. Ein ausgelieferter Batch enthält also weiterhin Datenpunkte mit hoher Häufigkeit.

Datentypen werden ausschließlich aus Daten abgeleitet, die von Sensoren auf der Smartwatch generiert werden. Standortdaten stammen beispielsweise ausschließlich von der Smartwatch und nicht vom Smartphone.

Datentypen

Mit der ExerciseClient API können Sie Workouts verschiedener Typen starten, pausieren, fortsetzen und beenden. Für jedes Training definiert WHS eine Reihe von Datentypen, die für diese Trainingsart verfügbar sind. Das spart Energie und vereinfacht die Anwendungslogik, da Sensoren, die für ein bestimmtes Training nicht erforderlich sind, nicht aktiviert werden. Wenn du beispielsweise mit dem Laufen beginnst, werden Standortdaten nur für einen Lauf im Freien bereitgestellt und aufgezeichnet. Wenn Sie ein Radfahrtraining starten, werden keine Schritte angegeben oder aufgezeichnet. In den folgenden Abschnitten werden die Datentypen beschrieben, die in ExerciseClient unterstützt werden.

Auf allen Geräten verfügbare Trainingsdatentypen

Die folgenden Trainingsdatentypen sind auf allen Geräten verfügbar.

  • Beispieldatentypen haben einen entsprechenden _STATS-Datentyp, der die Mindest-, Höchst- und Durchschnittswerte der Aktivität zurückgibt. So können beispielsweise PACE-Statistiken mit dem Datentyp PACE_STATS abgerufen werden.
  • Für Intervalldatentypen gibt es einen entsprechenden _TOTAL-Datentyp, der den kumulativen Wert der Aktivität zurückgibt. So können beispielsweise DISTANCE-Statistiken mit dem Datentyp DISTANCE_TOTAL abgerufen werden.
Tabelle 1: Auf allen Geräten verfügbare Trainingsdatentypen
Messwert Erwartete Daten Hinweise zum erwarteten Verhalten
HERZFREQUENZ_BPM Schläge pro Minute [Datentyp: Double] Bei allen Geräten wird die Herzfrequenz während eines Trainings einmal pro Sekunde gemessen. Einige Geräte melden jede Sekunde einen BPM-Wert. Einige Geräte melden die Herzfrequenz nur, wenn sie sich seit dem vorherigen Wert geändert hat. Du solltest nicht davon ausgehen, dass du auf allen Geräten in jedem Intervall von einer Sekunde einen BPM-Wert erhältst.
SPIELORT Breiten- und Längengrad[DataType: Double] Standortdaten basieren nur auf dem GPS der Smartwatch. Standortdaten stammen nicht vom Fused Location Provider oder anderen Android-Diensten. Jeder Datenpunkt enthält außerdem einen Genauigkeitswert (auch als horizontaler Positionsfehler bezeichnet) und die Verfügbarkeit.
SCHRITTE [Datentyp: Long] Die Schrittzahl ist eine laufende Summe über die Dauer des Trainings, ohne Pausen.
DISTANZ Meter [Datentyp: Double] Wird, sofern verfügbar, anhand des GPS-basierten Standorts und ansonsten anhand der Schritte berechnet. „Insgesamt“ bezieht sich auf die Gesamtdauer des Trainings, ohne die Zeit, in der das Training pausiert wurde.
GESCHWINDIGKEIT [Meter / Sekunde] [Datentyp: Double] Gibt Minimal-, Maximal- und Durchschnittswerte zurück. Diese Werte werden über die Dauer des Trainings hinweg erfasst, nicht während der Pausen.
TEMPO [Sekunden / Meter] [Datentyp: Double] Der Standardwert ist 0, wenn die Geschwindigkeit 0 ist. Die Durchschnittswerte beziehen sich auf die Dauer des Trainings, nicht auf die Zeit, in der das Training pausiert wurde.
ELEVATION_GAIN Meter [Datentyp: Double] Positive Höhenänderungen. Die Gesamtzahl wird für die Dauer des Trainings angegeben, ohne die Zeit, in der das Training pausiert wird.
TOTAL_CALORIES kCal [Datentyp: Double] Aktiv verbrannte Kalorien werden zum Grundumsatz addiert. Bei den hier angegebenen Kalorien werden die in den Systemeinstellungen angegebenen Größe, das Gewicht, das Alter und das Geschlecht des Nutzers berücksichtigt. Bei den Kalorien werden keine Nutzerprofildaten berücksichtigt, die in Ihrer App erhoben werden. Die angegebene Gesamtzahl bezieht sich auf die Dauer des Trainings, ohne die Zeit, in der das Training pausiert wird.

Optionale Trainingsdatentypen

Die folgende Liste mit Datentypen ist nur auf bestimmten Geräten verfügbar. Eine vollständige Liste der DataTypes finden Sie in der Jetpack-Referenz. Wenn ein DataType nicht in der vorherigen Liste „Erforderlich/garantiert“ enthalten ist, ist es optional.

Hier sind einige Beispiele für optionale Datentypen. Hier einige Beispiele:

Tabelle 2: Beispiele für optionale Trainingsdatentypen
Messwert Erwartete Daten Hinweise zum erwarteten Verhalten
ABSOLUTE_ELEVATION [Datentyp: Double]
ELEVATION_LOSS Meter [Datentyp: Double] Negative Höhenunterschiede. Der Wert ist positiv. Beispielsweise wird ein Höhenverlust von 1 Meter als 1 und nicht als -1 zurückgegeben.
STEPS_PER_MINUTE [Datentyp: Long]
WHEELCHAIR_PUSHES [Datentyp: Long] Die Anzahl der Rollstuhl-Schübe für Rollstuhl-basierte Übungen.
REP_COUNT [Datentyp: Long]
SWIM_STROKE_COUNT [Datentyp: Long]
SWIM_LAP_COUNT [Datentyp: Long]

Datentypen pro Training

Für jede Trainingsart werden unterschiedliche Datentypen zurückgegeben. Die zurückgegebenen Datentypen entsprechen den Anforderungen der Übung. Für den Trainingstyp „RADFAHREN“ wird beispielsweise nicht der Datentyp „SCHRITTE“ zurückgegeben. Verwenden Sie die Methode Capabilities zur Laufzeit, um zu ermitteln, welche Datentypen auf dem Gerät des Nutzers unterstützt werden.

Bei allen Trainingstypen werden mindestens Herzfrequenz- und Kaloriendaten zurückgegeben. Bei anderen Aktivitäten werden je nach den Anforderungen für die Aktivität möglicherweise zusätzliche Datentypen unterstützt.

Hier einige Beispiele:

  • Bei Übungen wie Meditation oder Pilates werden nur Herzfrequenz und Kalorien unterstützt.
  • Bei Sportarten wie Basketball oder Badminton werden Herzfrequenz, Kalorienverbrauch, Strecke und Schritte aufgezeichnet.
  • Bei Aktivitäten wie Gehen und Laufen werden Herzfrequenz, Kalorienverbrauch, Distanz, Schritte, Geschwindigkeit und Tempo unterstützt.
  • Beim Schwimmen werden Herzfrequenz, Kalorienverbrauch, Distanz und geschwommene Bahnen unterstützt.

Passiver Monitoring-Client

Die folgenden Datentypen sind erforderlich für alle Geräte mit Wear OS, um Apps zu unterstützen, die Gesundheits- und Fitnessdaten wie Herzfrequenz 
und Schrittzahl passiv erfassen. Jeder dieser Datentypen muss ausschließlich aus Daten abgeleitet werden, die von Sensoren auf der Smartwatch generiert werden.

Erwartetes Verhalten

Um Strom zu sparen, werden Sensorwerte, die mit der passiven Überwachung erfasst werden, auf der MCU gespeichert und in Batches an Health Services gesendet. Diese Batch-Ergebnisse werden in unterschiedlichen Intervallen zurückgegeben, je nach Systemverhalten. Beispiele sind das Zurückgeben von Batches, wenn Sensorpuffer voll sind oder wenn der Nutzer mit dem Display interagiert.

Gehen Sie nicht von vordefinierten oder vorhersehbaren Batching-Intervallen für Datentypen aus.

Passive Monitoring-Datentypen

Tabelle 3: Erforderliche passive Überwachungsdatentypen für Wear OS-Geräte
Messwert Erwartete Daten Notes
HERZFREQUENZ_BPM Schläge pro Minute [Datentyp: Double] Geräte können Herzfrequenzmesswerte in unterschiedlichen Intervallen zurückgeben. Einige Geräte können jede Sekunde einen Messwert erfassen. Bei anderen Geräten kann es bis zu zehn Minuten dauern, bis ein Messwert erfasst wird. Diese Intervalle werden Apps nicht zur Verfügung gestellt. Apps sollten sich problemlos an unterschiedliche Sampling-Intervalle anpassen.
STEPS_DAILY/STEPS [Datentyp: Long] „Tägliche Schritte“ ist die Gesamtzahl der Schritte seit dem letzten Zurücksetzen, das um Mitternacht von WHS ausgelöst wird. Dazu gehören alle Schritte, die während einer pausierten Trainingseinheit gemacht werden. „Schritte“ ist ein detaillierter Deltawert seit der letzten Prüfung.
DISTANCE_DAILY/DISTANCE Meter [Datentyp: Double] Wird aus dem Beschleunigungsmesser/den Schritten berechnet. Berechnen Sie die Schritte nicht während der GPS-Aufzeichnung, damit Nutzer, die die Standortdienste deaktiviert haben, trotzdem genaue Schrittzahlen erhalten.
GESCHWINDIGKEIT [Meter / Sekunde] [Datentyp: Double]
CALORIES_DAILY kCal [Datentyp: Double] Kalorien für den Tag, einschließlich aktiv verbrannter Kalorien und Grundumsatz. Die hier ausgegebene Kalorienzahl berücksichtigt die in den Systemeinstellungen angegebenen Größe, das Gewicht, das Alter und das Geschlecht des Nutzers. Die Kalorien werden nicht auf Grundlage von Nutzerprofildaten angepasst, die in Ihrer App erhoben werden.
RUNNING_STEPS (optional) [Datentyp: Long] Differenz der Schritte sowohl während eines Trainings als auch sonst. Beide gleichzeitig verfolgen.
WALKING_STEPS (optional) [Datentyp: Long]
ELEVATION_GAIN Meter [Datentyp: Double] Enthält nur die positiven Höhenänderungen.
ELEVATION_LOSS Meter [Datentyp: Double] Enthält nur die negativen Höhenänderungen
FLOORS_DAILY [Datentyp: Double] Kann als „teilweise“ Stockwerke dargestellt werden

Tagesziele für passives Monitoring

Tabelle 4: Messwerte für tägliche Ziele für das passive Monitoring
Messwert Erwartete Daten Notes
STEPS_DAILY [Datentyp: Long] Die täglichen Schritte, einschließlich aller Schritte, die während einer pausierten aktiven Trainingseinheit gemacht wurden, sind die Gesamtzahl der Schritte seit dem letzten Zurücksetzen. WHS wird um Mitternacht zurückgesetzt.
FLOORS_DAILY [Datentyp: Double] Kann als „teilweise“ Treppenstufen dargestellt werden.
CALORIES_DAILY kCal [Datentyp: Double] Kalorien für den Tag, einschließlich aktiv verbrannter Kalorien und Grundumsatz.
DISTANCE_DAILY Meter [Datentyp: Double] Wird aus dem Beschleunigungsmesser oder der Schrittzahl berechnet. Berechne die Schrittzahl nicht mithilfe des GPS, damit Nutzer, die die Standortdienste deaktiviert haben, trotzdem genaue Schrittzahlen erhalten.
DAILY_ELEVATION_GAIN Meter [Datentyp: Double] Enthält nur die positiven Höhenänderungen.

MeasureClient

Verwende MeasureClient, um die Herzfrequenz zu einem bestimmten Zeitpunkt zu messen.

Erwartetes Verhalten

MeasureClient und PassiveClient sind in gewisser Hinsicht ähnlich. Beide liefern nicht gruppierte Gesundheitsstatistiken, die sich nicht auf ein Training beziehen. Beide können zur Messung der Herzfrequenz verwendet werden. Der Hauptunterschied besteht darin, dass MeasureClient die Verfügbarkeit von Herzfrequenzdaten berücksichtigt, PassiveClient jedoch nicht.

Datentypen

Tabelle 5: MeasureClient-Datentypen
Messwert Erwartete Daten Notes
HERZFREQUENZ_BPM Schläge pro Minute [Datentyp: Double] Auch Verfügbarkeit enthalten

Unterstützte Funktionen

Zusätzlich zu den Datentypen für Trainings und passives Monitoring unterstützen Geräte zusätzliche Funktionen zum Auslösen von Ereignissen, z. B. zum Starten eines Trainings, und zum Messen des Status, z. B. ob du schläfst oder wach bist. Einige dieser Funktionen sind auf allen Geräten verfügbar, andere nur auf bestimmten Geräten.

Ereignistrigger

Alle Geräte unterstützen die folgenden gängigen Trigger:

  • Tagesziele für Distanz und Schritte
  • Trainingsziele für Schritte, Distanz und Dauer.

Andere Geräte unterstützen möglicherweise erweiterte Ereignistrigger. Einige Beispiele:

  • Bahnen beim Schwimmen zählen
  • Trainingsziele für verbrannte Kalorien
  • Trainingsziele für die Momentangeschwindigkeit

Bundesstaaten

Alle Geräte unterstützen grundlegende Statusfunktionen. Der Status gibt an, ob ein Nutzer gerade trainiert oder nicht.

Andere Geräte bieten möglicherweise zusätzliche Statusfunktionen. Zu den zusätzlichen Statusfunktionen gehört die Erkennung, ob ein Training automatisch pausiert oder fortgesetzt wurde oder wann der Nutzer wach oder schlafend ist.

Gesundheitsbezogene Benachrichtigungen bei der passiven Überwachung

Einige Geräte unterstützen Gesundheitswarnungen. Diese Funktionen werden nicht auf allen Geräten unterstützt. Zu den Gesundheitswarnungen gehören die Erkennung von Herzfrequenzanomalien oder Stürzen.