Einstieg

1. Das Paket installieren

   bun add @capgo/capacitor-watch

2. Synchronisiere mit native Projekten

   bunx cap sync

3. Die Erweiterung konfigurieren

   Grundlegende Verwendungsaufgabe:

   import { CapgoWatch } from '@capgo/capacitor-watch';
   
   // Check watch connectivity status
   const info = await CapgoWatch.getInfo();
   console.log('Watch paired:', info.isPaired);
   console.log('Watch reachable:', info.isReachable);
   
   // Listen for messages from watch
   await CapgoWatch.addListener('messageReceived', (event) => {
     console.log('Message from watch:', event.message);
   });

   Senden Sie eine Nachricht an Watch:

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOS

   Erforderliche iOS-Einrichtung:

   1. Fügen Sie der WatchConnectivity-Fähigkeit Ihrer iOS-Anwendung in Xcode hinzu
   2. Erstellen Sie in Ihrem Xcode-Projekt einen watchOS-Anwendungsziel
   3. Implementieren Sie WatchConnectivity in Ihrer watchOS-Anwendung (siehe Implementierung des Watch-Apps unten)

   Die Erweiterung aktiviert die WCSession automatisch, wenn die Erweiterung geladen wird.

   Android

   Der Apple Watch wird nur auf iOS unterstützt. Auf Android werden alle Methoden mit der Fehlermeldung „Apple Watch wird nur auf iOS unterstützt“ abgelehnt. Der getInfo() methode gibt zurück isSupported: false.

4. Behandeln Sie Nachrichten, die eine Antwort erfordern

   // Listen for messages that need a response
   await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
     console.log('Request from watch:', event.message);
   
     // Process the request
     const result = await processWatchRequest(event.message);
   
     // Send reply back to watch
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { result }
     });
   });

5. Synchronisieren Sie den Anwendungsstatus

   // Update application context (latest value only)
   await CapgoWatch.updateApplicationContext({
     context: {
       theme: 'dark',
       userId: '123',
       lastSync: Date.now()
     }
   });
   
   // Listen for context updates from watch
   await CapgoWatch.addListener('applicationContextReceived', (event) => {
     console.log('Context from watch:', event.context);
   });

6. Übertragen Sie Benutzerinformationen zuverlässig

   // Queue data for reliable delivery (even when watch is offline)
   await CapgoWatch.transferUserInfo({
     userInfo: {
       recordId: '456',
       action: 'created',
       data: { name: 'Item 1' }
     }
   });
   
   // Listen for user info transfers
   await CapgoWatch.addListener('userInfoReceived', (event) => {
     console.log('User info from watch:', event.userInfo);
   });

7. Verbindungsüberwachung

   // Track reachability changes
   await CapgoWatch.addListener('reachabilityChanged', (event) => {
     console.log('Watch reachable:', event.isReachable);
     if (event.isReachable) {
       // Watch is now available for interactive messaging
     }
   });
   
   // Track session activation state
   await CapgoWatch.addListener('activationStateChanged', (event) => {
     // 0 = notActivated, 1 = inactive, 2 = activated
     console.log('Session state:', event.state);
   });

Uhr App-Implementierung anzeigen

Ihre Uhr-App muss WatchConnectivity implementieren. Hier ist ein Beispiel mit SwiftUI:

import SwiftUI
import WatchConnectivity

@main
struct MyWatchApp: App {
    init() {
        WatchViewModel.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class WatchViewModel: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WatchViewModel()

    @Published var lastMessage: [String: Any] = [:]

    func activate() {
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    // Send message to iPhone
    func sendToPhone(_ data: [String: Any]) {
        guard WCSession.default.isReachable else {
            print("iPhone not reachable")
            return
        }
        WCSession.default.sendMessage(data, replyHandler: nil)
    }

    // Send message with reply
    func sendToPhoneWithReply(_ data: [String: Any], completion: @escaping ([String: Any]) -> Void) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(data, replyHandler: completion)
    }

    // Receive message from iPhone
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = message
        }
    }

    // Receive application context
    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = applicationContext
        }
    }

    // Required delegate methods
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        print("Watch session activated: \(activationState.rawValue)")
    }
}

API Reference

Methode

sendMessage(options: SendMessageOptions)

Senden Sie eine interaktive Nachricht an das Gerät. Erfordert, dass das Gerät erreichbar ist.

Parameter:

• data: Objekt - Die Daten, die an das Gerät gesendet werden sollen

updateApplicationContext(options: UpdateContextOptions)

Aktualisieren Sie den Anwendungscontex. Nur der letzte Wert wird gespeichert.

Parameter:

• context: Objekt - Der Kontextdaten, die gesynchronisiert werden sollen

transferUserInfo(options: TransferUserInfoOptions)

Warten Sie auf die Zuverlässigkeit der Benutzerinformationen.

Parameter:

• userInfo: Objekt - Die Benutzerinformationen, die übertragen werden sollen

replyToMessage(options: ReplyMessageOptions)

Antwort auf eine Nachricht, die eine Antwort erforderte.

Parameter:

• callbackId: string - Die Callback-ID aus dem Ereignis messageReceivedWithReply
• data: Objekt - Die Antwortdaten

getInfo()

Status der Uhrverbindung abrufen.

Rückgabewert: WatchInfo Objekt mit:

• isSupported: boolean - Ob WatchConnectivity verfügbar ist
• isPaired: boolean - Ob eine Uhr gepaart ist
• isWatchAppInstalled: boolean - Ob die Uhr-App installiert ist
• isReachable: boolean - Ob die Uhr erreichbar ist
• activationStateZahl - Sitzungsstatus (0/1/2)

getPluginVersion()

Ermitteln Sie die native Pluginversion.

Ereignisse

Ereignis	Beschreibung
messageReceived	Einfache Nachricht von watch
messageReceivedWithReply	Nachricht, die eine Antwort erwartet (enthält callbackId)
applicationContextReceived	Aktualisierung des Kontexts von watch
userInfoReceived	Übertragung von Benutzerinformationen von watch
reachabilityChanged	Änderung der Verbindung zum Watch
activationStateChanged	Sitzungsaktivierungsstatus geändert

Kommunikationsmuster

Echtzeitkommunikation (sendMessage)

• Braucht, dass der Watch erreichbar ist
• Am besten für interaktive, zeitkritische Kommunikation
• Fällt sofort durch, wenn der Watch nicht verfügbar ist

Anwendungs Kontext (updateApplicationContext)

• Nur der letzte Wert - vorherige Werte werden überschrieben
• Am besten für das Synchronisieren des aktuellen App-Zustands
• Geliefert, wenn der Watch verfügbar wird

Benutzerinformationen übertragen (transferUserInfo)

• In der Reihenfolge geplant und geliefert
• Ideal für wichtige Daten, die geliefert werden müssen
• Funktioniert auch, wenn der Watch vorübergehend nicht erreichbar ist

Plattformhinweise

iOS

• Bereitstellung erfordert iOS 15.0 oder später
• Verwendet WatchConnectivity-Framework
• Sitzung aktiviert sich automatisch bei Plugin-Laden
• Hintergrundlieferung für Kontext und Benutzerinformationen unterstützt

Android

• Nicht unterstützt (Apple Watch ist iOS-only)
• Alle Methoden lehnen mit entsprechender Fehler ab
• getInfo() returns isSupported: false

Web

• Nicht unterstützt
• Alle Methoden lehnen mit unavailable Fehler ab
• getInfo() returns isSupported: false

Häufige Anwendungsfälle

1. Daten Synchronisierung: Synchronisiere Uhr und Telefon-Daten
2. Remote-Control: Steuere Telefon-Funktionen von der Uhr aus
3. Benachrichtigungen: Senden Sie benutzerdefinierte Benachrichtigungen an die Uhr
4. Gesundheitsdaten: Teilen Sie Fitness- und Gesundheitsmetriken
5. Mediensteuerung: Steuere die Musikwiedergabe von der Uhr aus
6. Smart HomeGeräte von deinem Handgelenk steuern

Fehlersuche

Uhren nicht erreichbar:

• Stellen Sie sicher, dass die Uhr in Bluetooth-Range ist
• Überprüfen Sie, ob beide Apps läuft
• Überprüfen Sie, ob WCSession auf beiden Seiten aktiviert ist

Nachrichten werden nicht empfangen:

• Stellen Sie sicher, dass die Listener vor dem Senden registriert sind
• Überprüfen Sie, ob die Uhr-App die WCSessionDelegate implementiert
• Verwenden Sie transferUserInfo __CAPGO_KEEP_0__

Sitzung nicht aktivieren:

• Stellen Sie sicher, dass die WatchConnectivity-Fähigkeit in Xcode hinzugefügt ist
• Überprüfen Sie, ob die Uhr-App die Begleit-Bundle-ID hat
• Überprüfen Sie, ob beide Apps auf kompatible Betriebssystemversionen zielen