Getting Started

Installation

You können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Werkzeugleiste mit folgendem Befehl hinzu:

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

Dann verwenden Sie 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 aufgeführten plattform-spezifischen Anweisungen:

1. Das Paket installieren

   bun add @capgo/capacitor-watch

2. Mit der native Projekte synchronisieren

   bunx cap sync

3. Die Plugin-Konfiguration anpassen

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

   Eine Nachricht an den 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

   Erforderliche iOS-Einrichtung:

   1. Fügen Sie der iOS-Anwendung in Xcode die WatchConnectivity-Fähigkeit 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)

   Das 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. Die getInfo() Die Methode gibt zurück isSupported: false.

4. Nachrichten bearbeiten, 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. Verbindungsstatus ü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

Ihr watchOS-App 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)

Ein interaktives Nachricht senden an den Uhren. Erfordert, dass die Uhr erreichbar ist.

Parameter:

• dataObject - Die Daten, die an die Uhr gesendet werden

updateApplicationContext(options: UpdateContextOptions)

Die Anwendungscontext aktualisieren. Nur der letzte Wert wird gespeichert.

Parameter:

• context: Objekt - Der Synchronisationskontext

transferUserInfo(options: TransferUserInfoOptions)

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

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

Verbindungsstatus der Uhr ermitteln.

Rückgabewert: WatchInfo Objekt mit:

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

getPluginVersion()

Stelle die native Pluginversion ein.

Events

Ereignis	Beschreibung
messageReceived	Einfacher Nachricht von der Uhr
messageReceivedWithReply	Nachricht, die eine Antwort erwartet (enthält callbackId)
applicationContextReceived	Kontextaktualisierung von der Uhr
userInfoReceived	Benutzerinformationenübertragung von der Uhr
reachabilityChanged	Uhr-Verbindung geändert
activationStateChanged	Aktivierungsstatus der Sitzung geändert

Kommunikationsmuster

Sofortige Nachrichtenübermittlung (sendMessage)sendMessage)

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

Anwendungs Kontext (updateApplicationContext)

• Nur der letzte Wert – vorherige Werte werden überschrieben
• Beste Wahl für das Synchronisieren des aktuellen App-Zustands
• Wird geliefert, wenn der Watch verfügbar wird

Benutzerinfo-Übertragung (transferUserInfo)

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

Plattformhinweise

iOS

• Benötigt iOS 15.0 oder später
• Verwendet 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 geeigneter Fehler ab
• getInfo() returns isSupported: false

Web

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

Gemeinsame Verwendungsfälle

1. Daten SynchronisierungDaten auf Wach- und Telefon synchron halten
2. Fernsteuerung: Mobilfunkfunktionen über das Uhrwerk steuern
3. Benachrichtigungen: Benutzerdefinierte Benachrichtigungen an das Uhrwerk senden
4. Krankheitsdaten: Fitness- und Gesundheitsmetriken teilen
5. Mediensteuerung: Musikwiedergabe von der Uhr steuern
6. Smart Home: Geräte von der Uhr aus steuern

Problembehandlung

Uhr nicht erreichbar:

• Stellen Sie sicher, dass der Watch in Bluetooth-Range 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 Watch-App WCSessionDelegate implementiert
• Verwenden Sie transferUserInfo für eine sichere Lieferung

Sitzung nicht aktiviert:

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

Weitermachen von Getting Started

Wenn Sie "Getting Started" verwenden Getting Started um native Plugin-Arbeit zu planen, verbinden Sie es mit Using @capgo/capacitor-watch für die native Fähigkeit in Using @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 das Produktworkflow in Ionic Enterprise Plugin Alternativen.