Getting Started

Installation

Sie können unsere KI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer KI-Tool mithilfe der folgenden Befehl hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Verwenden Sie dann die folgende Anfrage:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-watch` plugin in my project.

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen Plattform-spezifischen Anweisungen:

1. Installieren Sie das Paket

   bun add @capgo/capacitor-watch

2. Synchronisieren mit native Projekten

   bunx cap sync

3. Die Erweiterung konfigurieren

   Grundlegender Beispielsatz:

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

   Nachricht an Watch senden:

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

   iOS

   Required iOS Setup:

   1. Die WatchConnectivity-Fähigkeit in Ihrem iOS-App in Xcode hinzufügen
   2. Eine watchOS-App-Ziel in Ihrem Xcode-Projekt erstellen
   3. WatchConnectivity in Ihrer watchOS-App implementieren (siehe Watch App Implementation 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 der Fehlermeldung „Apple Watch wird nur auf iOS unterstützt“ abgelehnt. Der getInfo() Methode gibt zurück isSupported: false.

4. Antworten auf 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. Synchronisiere die Anwendungsstate

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

Uhranwendung implementieren

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

Methode

sendMessage(options: SendMessageOptions)

Ein interaktives Nachricht an das Uhrsenden. Erfordert, dass die Uhr erreichbar ist.

Parameter:

• data: Objekt - Die Daten, die an die Uhr gesendet werden.

updateApplicationContext(options: UpdateContextOptions)

Die Anwendungskontext aktualisieren. Nur der letzte Wert wird gespeichert.

Parameter:

• context: Objekt - Die Kontextdaten zum Synchronisieren.

transferUserInfo(options: TransferUserInfoOptions)

Benutzerinformationen für eine zuverlässige Lieferung in der Warteschlange legen.

Parameter:

• userInfo: Objekt - Die Benutzerinformationen zum Übertragen.

replyToMessage(options: ReplyMessageOptions)

Antwort auf eine Nachricht, die eine Antwort erforderte.

Parameter:

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

getInfo()

Status der Verbindung zum Watch abrufen.

Rückgabewert: WatchInfo Objekt mit:

• isSupported: boolean - Ob WatchConnectivity verfügbar ist
• isPaired: boolean - Ob ein Watch pairt ist
• isWatchAppInstalled: boolean - Ob eine Watch-App installiert ist
• isReachable: boolean - Ob der Watch erreichbar ist
• activationState : Zahl - Sitzungsstatus (0/1/2)

getPluginVersion()

Erhalten Sie die native Pluginversion.

Events

Event	Beschreibung
messageReceived	Einfache Nachricht von Watch
messageReceivedWithReply	Nachricht, die eine Antwort erwartet (enthält callbackId)
applicationContextReceived	Update des Kontexts von Watch
userInfoReceived	Übertragung von Benutzerinformationen von Watch
reachabilityChanged	Verbindung zum Watch wurde geändert
activationStateChanged	Sitzung aktivierungsstatus geändert

Kommunikationsmuster

Unmittelbare Nachrichtenübermittlung (sendMessage)

• Benötigt, dass der Uhrenschalter erreichbar ist
• Beste Wahl für interaktive, zeitkritische Kommunikation
• Fällt sofort durch, wenn der Uhrenschalter nicht verfügbar ist

Anwendungs Kontext (updateApplicationContext)

• Nur der neueste Wert - vorherige Werte werden überschrieben
• Beste Wahl für das Synchronisieren des aktuellen Anwendungsstatus
• Übermittelt, wenn der Watch verfügbar wird

Nutzerinformationen übertragen (transferUserInfo)

• Angeordnet und in der Reihenfolge übermittelt
• Am besten für wichtige Daten, die übermittelt werden müssen
• Auch dann funktioniert, wenn der Watch vorübergehend nicht erreichbar ist

Plattformhinweise

iOS

• Benötigt iOS 15.0 oder später
• Mit dem WatchConnectivity-Framework verwendet
• Sitzung aktiviert sich automatisch bei Plugin-Laden
• Unterstützt Hintergrundlieferung für Kontext und Benutzerinfo

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

Gemeinsame Anwendungsfälle

1. Daten Synchronisierung: Halten Sie die Daten von Telefon und Uhr in Echtzeit synchron.
2. Fernsteuerung: Steuern Sie die Funktionen des Telefons von der Uhr aus.
3. Benachrichtigungen: Senden Sie benutzerdefinierte Benachrichtigungen an die Uhr.
4. Gesundheitsdaten: Teilen Sie Fitness- und Gesundheitsmetriken.
5. Mediensteuerung: Steuern Sie die Musikwiedergabe von der Uhr aus.
6. Smart Home: Geräte über den Arm steuern

Troubleshooting

Watch nicht erreichbar:

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

Nachrichten werden nicht empfangen:

• Überprüfen Sie, ob Hörer vor dem Senden registriert sind
• Stellen Sie sicher, dass die Watch-App WCSessionDelegate implementiert
• Verwenden Sie transferUserInfo für eine sichere Lieferung

Sitzung nicht aktivieren:

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

Weiter geht es von Getting Started

Wenn Sie Getting Started zur Planung von native Plugin-Arbeiten verwenden, verbinden Sie es mit Mit @capgo/capacitor-watch für die native Fähigkeit in Mit @capgo/capacitor-watch, Plugin-Verzeichnis von Capgo für den Produktworkflow in Plugin-Verzeichnis von Capgo, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren, und Ionic Enterprise-Plugin-Alternativen für den Produktworkflow in Ionic Enterprise-Plugin-Alternativen.