Einführung

Sektion mit dem Titel „Installation“

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Installationsanleitung

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

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

1. Installieren Sie das Paket

   bun add @capgo/capacitor-watch

2. Synchronisieren Sie mit native Projekten

   bunx cap sync

3. Konfigurieren Sie das Plugin

   Grundlegende Verwendung Beispiel:

   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 in Ihrem Xcode-Projekt eine Zielgruppe für die watchOS-Anwendung
   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 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. 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);
   });

Implementierung der Watch App

Ihre watchOS-Anwendung 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)")
    }
}

Referenz zu API

Methoden

sendMessage(options: SendMessageOptions)

Ein interaktives Nachricht senden an den Watch. Erfordert, dass der Watch erreichbar ist.

Parameter:

• data: Objekt - Die Daten, die an den Watch gesendet werden sollen

updateApplicationContext(options: UpdateContextOptions)

Die Anwendungskontext aktualisieren. Nur der letzte Wert wird gespeichert.

Parameter:

• context: Objekt - Die Kontextdaten, die synchronisiert werden sollen

transferUserInfo(options: TransferUserInfoOptions)

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

Parameter:

• userInfo: Objekt - Die Benutzerinformationen zum Übertragen

replyToMessage(options: ReplyMessageOptions)

Antworte auf eine Nachricht, die eine Antwort erfordert.

Parameter:

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

getInfo()

Erhalte den Status der Watch-Verbindung.

Rückgabewert: WatchInfo Objekt mit:

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

getPluginVersion()

Die native Pluginversion abrufen.

Events

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

Kommunikationsmuster

Echtzeit-Nachrichten (sendMessage)

• Braucht, dass der Watch erreichbar ist
• Am besten für interaktive, zeitkritische Kommunikation geeignet
• Versagt sofort, wenn der Watch nicht verfügbar ist

Anwendungs Kontext (updateApplicationContext)

• Erstes Wert nur - Vorgängewerte werden überschrieben
• Am besten für die Synchronisierung des aktuellen Anwendungsstatus
• Wird geliefert, wenn der Watch verfügbar wird

Benutzerinformationen-Übertragung (transferUserInfo)

• Angefordert und geliefert in der Reihenfolge
• Am besten für wichtige Daten, die geliefert werden müssen
• Arbeitet auch, wenn der Watch vorübergehend nicht erreichbar ist

Plattformhinweise

iOS

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

Android

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

Web

• Not unterstützt
• Alle Methoden lehnen mit unavailable-Fehler ab
• getInfo() rückgibt isSupported: false

Häufige Anwendungsfälle

1. Daten-Synchronisation: Synchronisiere Daten zwischen Uhr und Telefon
2. Fernsteuerung: Steuere Telefonfunktionen von der Uhr aus
3. Benachrichtigungen: Sende benutzerdefinierte Benachrichtigungen an die Uhr
4. Gesundheitsdaten: Fitness- und Gesundheitsdaten teilen
5. Mediensteuerung: Musikwiedergabe von der Uhr steuern
6. Smart Home: Geräte von der Uhr steuern

Schwierigkeiten beheben

Die Uhr ist nicht erreichbar:

• Stellen Sie sicher, dass die Uhr 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 registriert sind, bevor Sie senden
• Stellen Sie sicher, dass die Watch-App die WCSessionDelegate implementiert
• Verwenden Sie transferUserInfo zur sicheren Zustellung

Die Sitzung aktiviert sich nicht:

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

Fortsetzen Sie von Getting Started

Wenn Sie "Getting Started" verwenden Fortsetzen Sie von Getting Started für die native Plugin-Arbeit zu planen, verbinden Sie es mit Mit @capgo/capacitor-watch für die native Fähigkeit in Mit @capgo/capacitor-watch, Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen.