Apple HealthKit in React Native synchronisieren

In der boomenden Welt der Gesundheits- und Fitness-Technologie erwarten Nutzer eine nahtlose Integration zwischen ihren bevorzugten Apps und ihrem zentralen Gesundheits-Dashboard – Apple Health. Für React-Native-Entwickler kann der Zugriff auf diese umfangreichen, vom Nutzer freigegebenen Daten entmutigend wirken. Oft geht es darum, native iOS-Konfigurationen zu bewältigen, sensible Berechtigungen zu handhaben und ein völlig anderes Ökosystem zu verstehen.

Dieser Artikel entmystifiziert den Prozess. Wir erstellen eine praktische, schrittweise Anleitung zur Integration von Apples HealthKit in eine React-Native-Anwendung. Wir verwenden die beliebte Bibliothek react-native-health, um grundlegende Gesundheitsmetriken wie Schrittzahl, Schlafanalyse und Trainingsdaten zu lesen und zu schreiben. Damit unser Code sauber, wiederverwendbar und leicht zu verwalten bleibt, kapseln wir alle HealthKit-Interaktionen in einem benutzerdefinierten React-Hook.

Voraussetzungen:

• Ein macOS-Computer mit installiertem Xcode.
• Ein physisches iOS-Gerät (HealthKit-Funktionen sind auf Simulatoren eingeschränkt).
• Node.js (LTS-Version) und eine React-Native-Entwicklungsumgebung.
• Grundkenntnisse in React Native und TypeScript.

Warum das für Entwickler wichtig ist: Die Integration mit Apple Health kann die Nutzerbindung deutlich steigern, indem sie ein ganzheitlicheres und personalisierteres Erlebnis bietet. Sie ermöglicht es Ihrer App, zu den umfassenden Gesundheitsdaten des Nutzers beizutragen und davon zu profitieren, wodurch sie wertvoller und wettbewerbsfähiger wird.

Das Problem verstehen

Apple HealthKit ist ein leistungsstarkes, aber geschütztes Framework. Es dient als zentrales Repository für die Gesundheits- und Fitnessdaten eines Nutzers. Apps können ohne ausdrückliche, granulare Nutzerberechtigung nicht auf diese Daten zugreifen. Die wichtigsten Herausforderungen für einen React-Native-Entwickler sind:

1. Native Konfiguration: HealthKit ist ein natives iOS-Framework. Es erfordert spezielle Konfigurationen in Xcode, die außerhalb der üblichen JavaScript-Umgebung liegen.
2. Berechtigungsverwaltung: Apple hat ein strenges Datenschutzmodell. Wenn ein Nutzer die Berechtigung einmal verweigert, wird er nicht erneut gefragt. Er muss sie manuell in der Einstellungen-App aktivieren – ein Ablauf, den Ihre App berücksichtigen muss.
3. Datensynchronisation: Das Lesen und Schreiben von Daten erfordert das Verständnis verschiedener Datentypen, Einheiten und asynchroner Vorgänge.
4. UI/UX: Die Benutzeroberfläche muss klar erklären, warum diese Berechtigungen benötigt werden, und Fälle, in denen der Zugriff verweigert wird, elegant behandeln.

Unser Ansatz besteht darin, diese Herausforderungen direkt anzugehen: Wir nutzen eine Bibliothek, um die native Komplexität zu abstrahieren, und einen benutzerdefinierten Hook, um eine saubere, wiederverwendbare Schnittstelle für unsere React-Native-Komponenten zu schaffen.

Voraussetzungen

Bevor wir mit dem Programmieren beginnen, richten wir unser Projekt ein.

1. Ein neues React-Native-Projekt erstellen (mit TypeScript):

   npx create-react-native-app MyHealthApp --template react-native-template-typescript
   cd MyHealthApp
   

2. Die HealthKit-Bibliothek installieren: Wir verwenden react-native-health, eine weit verbreitete Bibliothek für die HealthKit-Integration.

   npm install react-native-health
   

3. iOS-Abhängigkeiten installieren:

   cd ios && pod install
   

Schritt 1: Native iOS-Konfiguration ✨

Dies ist der wichtigste Schritt. Wenn Sie hier einen Fehler machen, funktioniert nichts anderes.

Was wir tun

Wir müssen Xcode mitteilen, dass unsere App das HealthKit-Framework verwenden wird, und Meldungen bereitstellen, die dem Nutzer erklären, warum wir Zugriff auf seine Gesundheitsdaten benötigen.

Umsetzung

1. Das Xcode-Projekt öffnen: Öffnen Sie die Datei ios/MyHealthApp.xcworkspace in Xcode.

2. Die HealthKit-Capability hinzufügen:

   • Wählen Sie Ihr Projekt im linken Navigator aus.
   • Wechseln Sie zum Tab „Signing & Capabilities“.
   • Klicken Sie auf „+ Capability“.
   • Suchen Sie nach „HealthKit“ und doppelklicken Sie, um es hinzuzufügen. Damit teilen Sie iOS mit, dass Ihre App das HealthKit-Framework verwenden möchte.

3. Info.plist für Berechtigungen konfigurieren:

   • Suchen und öffnen Sie in Xcode die Datei Info.plist.
   • Fügen Sie zwei neue Schlüssel hinzu, indem Sie auf die Schaltfläche „+“ klicken:
     • Privacy - Health Share Usage Description: Diese Meldung wird angezeigt, wenn Sie die Berechtigung zum Lesen von Daten anfordern.
     • Privacy - Health Update Usage Description: Diese Meldung wird angezeigt, wenn Sie die Berechtigung zum Schreiben von Daten anfordern.
   • Geben Sie für jeden Schlüssel benutzerfreundliche Zeichenfolgenwerte an, zum Beispiel:
     • Wert für Share Usage: Unsere App verwendet Ihre Gesundheitsdaten, um personalisierte Einblicke zu geben und Ihren Fortschritt zu verfolgen.
     • Wert für Update Usage: Unsere App muss Ihre Trainings- und Aktivitätsdaten in Apple Health speichern.

   Der Quellcode Ihrer Info.plist sollte so aussehen:

   <key>NSHealthShareUsageDescription</key>
   <string>Unsere App verwendet Ihre Gesundheitsdaten, um personalisierte Einblicke zu geben und Ihren Fortschritt zu verfolgen.</string>
   <key>NSHealthUpdateUsageDescription</key>
   <string>Unsere App muss Ihre Trainings- und Aktivitätsdaten in Apple Health speichern.</string>
   

So funktioniert es

Durch das Hinzufügen der HealthKit-Capability werden die erforderlichen nativen Frameworks mit Ihrem Projekt verknüpft. Die Einträge in der Info.plist sind eine verpflichtende Sicherheitsfunktion von Apple. iOS zeigt diese Meldungen automatisch auf dem Bildschirm zur Einwilligung in Berechtigungen an. Daher ist es wichtig, dass sie klar sind und Vertrauen bei Ihren Nutzern aufbauen.

Schritt 2: Einen benutzerdefinierten Hook useHealthData erstellen

Damit unser Komponenten-Code sauber bleibt, erstellen wir einen benutzerdefinierten Hook namens useHealthData.ts. Dieser Hook verwaltet Berechtigungen und alle Interaktionen mit der Bibliothek react-native-health.

Was wir tun

Wir definieren die spezifischen Lese- und Schreibberechtigungen, die unsere App benötigt, und erstellen eine Funktion zur Initialisierung von HealthKit.

Umsetzung

1. Die Hook-Datei erstellen: Erstellen Sie im Verzeichnis src Ihres Projekts einen neuen Ordner hooks und darin eine Datei namens useHealthData.ts.

2. Die anfängliche Hook-Struktur einrichten:

   // src/hooks/useHealthData.ts
   import AppleHealthKit, {
     HealthKitPermissions,
   } from 'react-native-health';
   import { useEffect, useState } from 'react';
   
   /* Die Berechtigungen definieren, die wir anfordern möchten */
   const permissions: HealthKitPermissions = {
     permissions: {
       read: [
         AppleHealthKit.Constants.Permissions.Steps,
         AppleHealthKit.Constants.Permissions.SleepAnalysis,
         AppleHealthKit.Constants.Permissions.Workout,
       ],
       write: [
         AppleHealthKit.Constants.Permissions.Steps,
         AppleHealthKit.Constants.Permissions.SleepAnalysis,
         AppleHealthKit.Constants.Permissions.Workout,
       ],
     },
   };
   
   const useHealthData = () => {
     const [hasPermissions, setHasPermissions] = useState(false);
   
     useEffect(() => {
       // HealthKit initialisieren
       AppleHealthKit.initHealthKit(permissions, (error: string) => {
         if (error) {
           console.log('[ERROR] Cannot grant permissions!');
           return;
         }
         setHasPermissions(true);
       });
     }, []);
   
     // Hier fügen wir Funktionen zum Lesen/Schreiben von Daten hinzu
   
     return {
       hasPermissions,
     };
   };
   
   export default useHealthData;
   

So funktioniert es

Wir importieren AppleHealthKit und HealthKitPermissions aus der Bibliothek. Anschließend definieren wir ein permissions-Objekt, das genau angibt, welche Datentypen wir lesen und schreiben möchten. Der Hook useEffect ruft AppleHealthKit.initHealthKit auf, was beim ersten Aufruf die native iOS-Berechtigungsabfrage auslöst. Wenn der Nutzer die Berechtigung erteilt, wird unser Zustand hasPermissions auf true gesetzt.

Schritt 3: Gesundheitsdaten lesen (Schritte, Schlaf, Trainings)

Nun erweitern wir unseren Hook, um Daten zu lesen.

Was wir tun

Wir fügen unserem Hook useHealthData Funktionen hinzu, um die Schrittzahl, Schlafdaten und den Trainingsverlauf des Nutzers der letzten 7 Tage abzurufen.

Umsetzung

// Diese Zeilen innerhalb des Hooks useHealthData vor der return-Anweisung einfügen

const [steps, setSteps] = useState(0);
const [sleep, setSleep] = useState<any[]>([]); // Für das Beispiel vereinfacht
const [workouts, setWorkouts] = useState<any[]>([]); // Für das Beispiel vereinfacht

useEffect(() => {
  if (!hasPermissions) {
    return;
  }

  const options = {
    startDate: new Date(new Date().setDate(new Date().getDate() - 7)).toISOString(), // Letzte 7 Tage
    endDate: new Date().toISOString(),
  };

  // Schrittzahl abrufen
  AppleHealthKit.getStepCount(options, (err, results) => {
    if (err) {
      console.log('Error getting step count:', err);
      return;
    }
    setSteps(results.value);
  });

  // Schlafanalyse abrufen
  AppleHealthKit.getSleepSamples(options, (err, results) => {
    if (err) {
      console.log('Error getting sleep samples:', err);
      return;
    }
    setSleep(results);
  });

  // Trainings abrufen
  AppleHealthKit.getSamples({ ...options, type: 'Workout' }, (err, results) => {
    if (err) {
        console.log('Error getting workout samples:', err);
        return;
    }
    setWorkouts(results);
  });

}, [hasPermissions]);

// Die return-Anweisung aktualisieren
return {
  hasPermissions,
  steps,
  sleep,
  workouts,
};

So funktioniert es

Wir verwenden einen zweiten useEffect, der ausgeführt wird, sobald sich hasPermissions auf true ändert. Darin definieren wir Datumsoptionen, um Daten der letzten Woche abzufragen. Anschließend rufen wir die spezifischen Methoden von react-native-health auf, etwa getStepCount und getSleepSamples. Jede Funktion erhält die Datumsoptionen und einen Callback, der entweder einen Fehler oder die angeforderten Daten zurückgibt.

Schritt 4: Gesundheitsdaten schreiben (Ein Training speichern)

Das Lesen von Daten ist nützlich, aber viele Apps müssen auch Daten an HealthKit zurückgeben.

Was wir tun

Wir fügen unserem Hook eine Funktion hinzu, mit der wir ein neues Training in Apple Health speichern können.

Umsetzung

// Diese Funktion innerhalb des Hooks useHealthData einfügen
const saveWorkout = () => {
  if (!hasPermissions) {
    console.log('Cannot save workout without permissions.');
    return;
  }

  const options = {
    type: AppleHealthKit.Constants.Workouts.Running,
    startDate: new Date(new Date().getTime() - 60 * 60 * 1000).toISOString(), // vor 1 Stunde
    endDate: new Date().toISOString(),
    energyBurned: 350, // in Kalorien
    totalDistance: 5, // in Kilometern
  };

  AppleHealthKit.saveWorkout(options, (err, results) => {
    if (err) {
      console.log('Error saving workout:', err);
      return;
    }
    console.log('Workout saved successfully:', results);
    // Hier könnten Sie die Trainings erneut abrufen, um die Benutzeroberfläche zu aktualisieren
  });
};

// Die return-Anweisung aktualisieren
return {
  hasPermissions,
  steps,
  sleep,
  workouts,
  saveWorkout, // Die neue Funktion bereitstellen
};

So funktioniert es

Die Funktion saveWorkout erstellt ein options-Objekt mit Trainingstyp, Start- und Endzeit sowie wichtigen Kennzahlen wie verbrannten Kalorien und Distanz. Anschließend ruft sie AppleHealthKit.saveWorkout auf. Bei Erfolg erscheint das neue Training sofort in der Apple-Health-App des Nutzers.

Alles zusammenfügen

Nun können wir unseren leistungsstarken Hook useHealthData in jeder Komponente mit sehr sauberem Code verwenden.

Vollständiger Hook useHealthData.ts

// src/hooks/useHealthData.ts
import AppleHealthKit, {
  HealthKitPermissions,
  HealthValue,
  SleepSample,
  WorkoutSample,
} from 'react-native-health';
import { useEffect, useState } from 'react';

const permissions: HealthKitPermissions = {
  permissions: {
    read: [
      AppleHealthKit.Constants.Permissions.Steps,
      AppleHealthKit.Constants.Permissions.SleepAnalysis,
      AppleHealthKit.Constants.Permissions.Workout,
    ],
    write: [
      AppleHealthKit.Constants.Permissions.Steps,
      AppleHealthKit.Constants.Permissions.SleepAnalysis,
      AppleHealthKit.Constants.Permissions.Workout,
    ],
  },
};

const useHealthData = () => {
  const [hasPermissions, setHasPermissions] = useState(false);
  const [steps, setSteps] = useState(0);
  const [sleep, setSleep] = useState<SleepSample[]>([]);
  const [workouts, setWorkouts] = useState<WorkoutSample[]>([]);

  useEffect(() => {
    AppleHealthKit.initHealthKit(permissions, (error: string) => {
      if (error) {
        console.log('[ERROR] Cannot grant permissions!');
        return;
      }
      setHasPermissions(true);
    });
  }, []);

  useEffect(() => {
    if (!hasPermissions) {
      return;
    }

    const options = {
      startDate: new Date(new Date().setDate(new Date().getDate() - 7)).toISOString(),
      endDate: new Date().toISOString(),
    };

    AppleHealthKit.getStepCount(options, (err, results: HealthValue) => {
      if (err) {
        console.log('Error getting step count:', err);
        return;
      }
      setSteps(results.value);
    });

    AppleHealthKit.getSleepSamples(options, (err, results: SleepSample[]) => {
      if (err) {
        console.log('Error getting sleep samples:', err);
        return;
      }
      setSleep(results);
    });

    AppleHealthKit.getAnchoredWorkouts(options, (err, results: WorkoutSample[]) => {
      if (err) {
        console.log('Error getting workout samples:', err);
        return;
      }
      setWorkouts(results);
    });
  }, [hasPermissions]);

  const saveWorkout = () => {
    if (!hasPermissions) {
      console.log('Cannot save workout without permissions.');
      return;
    }

    const options = {
      type: AppleHealthKit.Constants.Workouts.Running,
      startDate: new Date(new Date().getTime() - 60 * 60 * 1000).toISOString(),
      endDate: new Date().toISOString(),
      energyBurned: 350,
      totalDistance: 5,
    };

    AppleHealthKit.saveWorkout(options, (err, results) => {
      if (err) {
        console.log('Error saving workout:', err);
        return;
      }
      console.log('Workout saved successfully:', results);
    });
  };

  return {
    hasPermissions,
    steps,
    sleep,
    workouts,
    saveWorkout,
  };
};

export default useHealthData;

Beispielkomponente App.tsx

// App.tsx
import React from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  Text,
  useColorScheme,
  View,
  Button,
} from 'react-native';
import { Colors } from 'react-native/Libraries/NewAppScreen';
import useHealthData from './src/hooks/useHealthData';

const App = () => {
  const isDarkMode = useColorScheme() === 'dark';
  const backgroundStyle = {
    backgroundColor: isDarkMode ? Colors.darker : Colors.lighter,
  };

  const { steps, sleep, workouts, saveWorkout } = useHealthData();

  return (
    <SafeAreaView style={backgroundStyle}>
      <StatusBar barStyle={isDarkMode ? 'light-content' : 'dark-content'} />
      <ScrollView contentInsetAdjustmentBehavior="automatic" style={backgroundStyle}>
        <View style={styles.container}>
          <Text style={styles.title}>HealthKit Demo</Text>

          <View style={styles.metricBox}>
            <Text style={styles.metricValue}>{steps.toLocaleString()}</Text>
            <Text style={styles.metricLabel}>Steps (Last 7 Days)</Text>
          </View>

          <View style={styles.metricBox}>
            <Text style={styles.metricValue}>{sleep.length}</Text>
            <Text style={styles.metricLabel}>Sleep Entries (Last 7 Days)</Text>
          </View>

          <View style={styles.metricBox}>
            <Text style={styles.metricValue}>{workouts.length}</Text>
            <Text style={styles.metricLabel}>Workouts (Last 7 Days)</Text>
          </View>
          
          <Button title="Save a Test Workout" onPress={saveWorkout} />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: { padding: 20 },
  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
  metricBox: {
    marginBottom: 15,
    padding: 15,
    borderRadius: 10,
    backgroundColor: '#f0f0f0',
  },
  metricValue: { fontSize: 20, fontWeight: '600' },
  metricLabel: { fontSize: 14, color: '#555', marginTop: 5 },
});

export default App;

Bewährte Sicherheitspraktiken

• Nur das anfordern, was Sie benötigen: Fordern Sie keine Berechtigungen für Daten an, die Sie nicht verwenden. Das wirkt für Nutzer verdächtig und kann dazu führen, dass sie den Zugriff vollständig verweigern.
• Erklären Sie, warum: Verwenden Sie die Beschreibungen in der Info.plist, um klar und ehrlich zu erklären, warum Ihre App Gesundheitsdaten benötigt.
• Verweigerte Berechtigungen behandeln: Wenn ein Nutzer die Berechtigung verweigert, sollte Ihre App weiterhin einwandfrei funktionieren. Stellen Sie eine Schaltfläche oder eine Anleitung bereit, die den Nutzer zur Einstellungen-App führt, wo er Berechtigungen manuell aktivieren kann. Denken Sie daran: Sie können die Abfrage nicht erneut aus der App heraus auslösen.

Fazit

Die Integration von Apple HealthKit in eine React-Native-App eröffnet vielfältige Möglichkeiten, ansprechende, personalisierte Gesundheits- und Fitnessanwendungen zu erstellen. Durch die Verwendung einer Bibliothek wie react-native-health und die Kapselung der Logik in einem benutzerdefinierten Hook können Sie die Komplexität nativer Konfiguration und Berechtigungen mit sauberem, wiederverwendbarem Code beherrschen.

Sie haben nun gelernt, wie Sie:

1. Xcode mit der HealthKit-Capability konfigurieren.
2. Die erforderlichen Berechtigungen in der Info.plist einrichten.
3. Die Nutzerautorisierung mit react-native-health anfordern.
4. Wichtige Gesundheitsmetriken wie Schritte, Schlaf und Trainings lesen und schreiben.
5. Ihren Code mit einem benutzerdefinierten Hook skalierbar strukturieren.

Ressourcen

• Offizielle Dokumentation von react-native-health: GitHub-Repository
• HealthKit-Dokumentation von Apple: Apple Developer
• Anleitung zur Einrichtung von HealthKit: Apple Developer

Kurzreferenz

Häufig gestellte Fragen

F: Woher weiß ich, ob das auf mich zutrifft? A: Besprechen Sie Ihre persönliche und familiäre Krankengeschichte mit Ihrem Gesundheitsdienstleister, um Ihre individuellen Risikofaktoren einzuschätzen und die geeigneten nächsten Schritte festzulegen.

F: Was sollte ich meinen Arzt fragen? A: Gute Fragen sind: „Was bedeuten meine Ergebnisse?“, „Welche Möglichkeiten habe ich?“, „Welche Änderungen des Lebensstils würden helfen?“ und „Wann sollte ich zur Nachsorge kommen?“

F: Gibt es Änderungen des Lebensstils, die helfen können? A: Die meisten Erkrankungen profitieren von grundlegenden Maßnahmen: ausgewogene Ernährung, regelmäßige körperliche Aktivität (150+ Minuten pro Woche), erholsamer Schlaf (7–9 Stunden), Stressbewältigung und der Verzicht auf Tabak.

Medizinischer Haftungsausschluss

Dieser Artikel dient ausschließlich Bildungszwecken und stellt keine medizinische Beratung dar. Konsultieren Sie stets einen qualifizierten Gesundheitsdienstleister, bevor Sie Entscheidungen über Ihre Gesundheit, Behandlung oder Versorgung treffen. Die individuellen Umstände unterscheiden sich, und was für eine Person angemessen ist, muss für eine andere nicht angemessen sein.

Wenn Sie einen medizinischen Notfall erleben, rufen Sie sofort 911 (oder Ihre örtliche Notrufnummer) an.