Einstieg

1. Installieren Sie das Paket

   bun add @capgo/capacitor-watch

2. Synchronisieren Sie mit native Projekten

   bunx cap sync

3. Konfigurieren Sie das Plugin

   Grundlegender Beispielsatz: Basic Usage Example

   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 iOS-Anwendung in Xcode die WatchConnectivity-Fähigkeit hinzu
   2. Erstellen Sie ein Ziel für eine watchOS-Anwendung in Ihrem Xcode-Projekt
   3. Implementieren Sie WatchConnectivity in Ihrer watchOS-Anwendung (siehe Implementierung des Watch-Apps unten)

   Der Plugin aktiviert die WCSession automatisch, wenn das Plugin geladen wird.

   Android

   Apple Watch wird nur auf iOS unterstützt. Auf Android werden alle Methoden mit dem Fehler „Apple Watch wird nur auf iOS unterstützt“ abgelehnt. Der getInfo() Methode isSupported: false.

4. Antworten auf Nachrichten 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. Synchronisiere 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. Benutzerinformationen zuverlässig übertragen

   // 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. Verbindung überwachen

   // 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);
   });

Uhranwendungsimplementierung ansehen

Ihre Uhranwendung muss WatchConnectivity implementieren. Hier ist ein Beispiel für 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 Referenz

Methoden

sendMessage(options: SendMessageOptions)

Senden Sie ein interaktives Nachricht an das Gerät. Erfordert, dass das Gerät erreichbar ist.

Parameter:

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

updateApplicationContext(options: UpdateContextOptions)

Aktualisieren Sie den Anwendungs Kontext. Nur der neueste Wert wird gespeichert.

Parameter:

• context: Objekt - Die Kontext Daten, die synchronisiert werden.

transferUserInfo(options: TransferUserInfoOptions)

Benutzerinformationen für zuverlässige Lieferung in Warteschlange setzen.

Parameter:

• userInfo: Objekt - Die zu übertragenden Benutzerinformationen

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()

Verbindungszustand des Watches abrufen.

Rückgabewert: WatchInfo Objekt mit:

• isSupported: boolean - Ob WatchConnectivity verfügbar ist
• isPaired: boolean - Ob ein Armband gepaart ist
• isWatchAppInstalled: boolean - Ob eine Armband-App installiert ist
• isReachable: boolean - Ob das Armband erreichbar ist
• activationState: number - Sitzungsstatus (0/1/2)

getPluginVersion()

Ermitteln Sie die native Pluginversion.

Ereignisse

Ereignis	Beschreibung
messageReceived	Einfache Nachricht von der Uhr
messageReceivedWithReply	Nachricht, die eine Antwort erwartet (enthält callbackId)
applicationContextReceived	Aktualisierung des Kontexts von der Uhr
userInfoReceived	Übertragung von Benutzerinformationen von der Uhr
reachabilityChanged	Uhr-Verbindung geändert
activationStateChanged	Aktivierungsstatus der Sitzung geändert

Kommunikationsmuster

Echtzeit-Nachrichten (sendMessage)sendMessage)

• Am besten für interaktive, zeitkritische Kommunikation geeignet
• Echtzeit-Nachrichten (sendMessage)
• Fällt sofort durch, wenn Watch nicht verfügbar ist

Anwendungs Kontext (updateApplicationContext)

• Nur der letzte Wert - vorherige Werte werden überschrieben
• Am besten geeignet für die Synchronisierung des aktuellen App-Zustands
• Wird geliefert, wenn Watch verfügbar wird

Benutzerinfo-Übertragung (transferUserInfo)

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

Plattformhinweise

iOS

• Benötigt iOS 15.0 oder höher
• Verwendet WatchConnectivity-Framework
• Sitzung aktiviert sich automatisch bei Plugin-Laden
• Unterstützt Hintergrundlieferung für Kontext und Benutzerinformationen

Android

• Alle Methoden lehnen mit entsprechender Fehlermeldung ab
• returns
• getInfo() __CAPGO_KEEP_0__ isSupported: false

Web

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

Häufige Verwendungsfälle

1. Daten Synchronisierung: Synchronisiert Uhr und Telefon-Daten
2. Remote Control: Steuert Telefon-Funktionen von der Uhr aus
3. Benachrichtigungen: Benachrichtigungen an den Uhr anpassen
4. Gesundheitsdaten: Fitness- und Gesundheitsdaten teilen
5. Mediensteuerung: Musikwiedergabe von der Uhr steuern
6. Smart Home: Geräte von der Uhr steuern

Fehlersuche

Uhr nicht erreichbar:

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

Nicht empfangene Nachrichten:

• Überprüfen Sie, ob Hörer vor dem Senden registriert sind
• Überprüfen Sie, ob die Uhranzeige die WCSessionDelegate implementiert
• Verwenden Sie transferUserInfo für eine garantierte Zustellung

Sitzung nicht aktiviert:

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