Getting Started

Installation

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten Ihrem AI-Tool mit der folgenden Befehl hinzu:

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

Verwenden Sie dann die folgende Anweisung:

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

   Beispiel für grundlegende Verwendung:

   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

   Benötigte iOS-Einrichtung:

   1. Die WatchConnectivity-Fähigkeit in Ihrem iOS-App in Xcode hinzufügen
   2. Einen watchOS-App-Ziel in Ihrem Xcode-Projekt erstellen
   3. WatchConnectivity in Ihrer watchOS-App implementieren (siehe Watch-App-Implementierung unten)

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

   Android

   Benötigte Wear OS-Einrichtung:

   1. Ein Wear OS-Modul zu Ihrem Android-Projekt (gleich applicationId und Signierung wie die Telefon-App).
   2. Erklären Sie die capgo_watch Fähigkeit im Wear-Modul (siehe Erstellung einer Wear-OS-Anwendung).
   3. Implementieren Sie Datenlayer-Händer auf dem Uhren-Plugin mit den Plugin-Pfaden (/capgo/message, /capgo/contextund andere).

   Das Telefon-Plugin registriert Wearable API-Händer, wenn es geladen wird. Verwenden Sie getInfo() um verbundene Knoten zu prühen und zu prühen, ob die Uhren-App erkannt wird.

   Full steps: Erstellung einer Wear-OS-Anwendung.

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 (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         result,
       },
     });
   });

5. Anwendungszustand synchronisieren

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

Watch App-Implementierung

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

API Referenz

Methoden

sendMessage(options: SendMessageOptions)

Ein interaktives Nachricht senden an das Uhren-Gerät. Erfordert, dass das Uhren-Gerät erreichbar ist.

Parameter:

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

updateApplicationContext(options: UpdateContextOptions)

Die Anwendungskontext aktualisieren. Nur der neueste Wert wird gespeichert.

Parameter:

• context: Objekt - Die Synchronisationsdaten im Kontext

transferUserInfo(options: TransferUserInfoOptions)

Queue user info for reliable delivery.

Parameter:

• userInfo: Objekt - Die zu übertragenden Benutzerinformationen

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

Verbindungsstatus der Uhr abrufen.

Rückgabewerte: WatchInfo Objekt mit:

• isSupported: boolean - Ob Watch-APIs auf dieser Plattform verfügbar sind
• isPaired: boolean - Apple Watch paired (iOS) oder zumindest ein Wear OS-Node verbunden (Android)
• isWatchAppInstalled: boolean - Begleitende Uhr-App installiert (iOS) oder capgo_watch : boolean - Fähigkeit erkannt (Android)
• isReachable: boolean - Ob die Uhr für sofortige Nachrichten erreichbar ist
• activationState: number - Sitzungsstatus (iOS WCSession; Android 2, wenn ein Node verbunden ist, 0 sonst)

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	Watch-Verbindung geändert (nur iOS)
activationStateChanged	Aktivierungsstatus der Sitzung geändert (nur iOS)

Kommunikationsmuster

Echtzeitkommunikation (sendMessage)sendMessage)

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

Anwendungskontext (updateApplicationContext)

• Nur der aktuellste Wert - vorherige Werte werden überschrieben
• Best for syncing current app state
• Wird geliefert, wenn der Watch verfügbar wird

Benutzerinformationen übertragen (transferUserInfo)

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

Plattformhinweise

Siehe das plattformübergreifende Unterstützungsübersicht auf der Pluginübersicht für eine Methode-für-Methode-Matrix

iOS (Apple Watch)

• 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
• Emittiert reachabilityChanged und activationStateChanged

Android (Wear OS)

• Benötigt Google Play-Dienste mit Wear OS-Datenschicht (play-services-wearableinklusive im Plugin)
• Phone- und Wear-APKs müssen den selben applicationId und Signaturschlüssel
• Die Uhranwendung muss die Fähigkeit anbieten capgo_watch
• Kann nicht emit reachabilityChanged oder activationStateChanged; Abstimmung getInfo() wenn benötigt
• Setup-Anleitung: Erstellung einer Wear OS-Anwendung

Web

• Die Watch-Messaging-Funktion wird im Browser nicht unterstützt
• getInfo() resolves with isSupported: false und andere Felder bei sicheren Standardwerten
• getPluginVersion() resolves with { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, und replyToMessage wird mit einem Fehler aufgrund von Nichtverfügbarkeit abgelehnt
• addListener löst eine Verbindung über Capacitor auf WebPlugin, aber Watch-Ereignisse sind im Browser nicht unterstützt (Callbacks werden nie ausgeführt)

Gängige Anwendungsfälle

1. Data SyncSynchronisiere Daten von Uhr und Telefon
2. Fernsteuerung: Steuern Sie Telefon-Funktionen vom Watch aus
3. Benachrichtigungen: Benachrichtigungen an den Watch senden
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 Watch-App die WCSessionDelegate implementiert
• Use transferUserInfo für eine garantierte Zustellung

Sitzung nicht aktiviert:

• Ensure WatchConnectivity capability is added in Xcode
• Überprüfen Sie, ob die Watch-App die Begleit-Bundle-ID hat
• Verify both apps target compatible OS versions

Fortsetzen Sie mit Getting Started

Wenn Sie Capgo verwenden Anfängskonfiguration um native Plugin-Arbeit zu planen, verbinden Sie es mit Mit @capgo/capacitor-watch zur Verwendung der native Fähigkeit in Mit @capgo/capacitor-watch, Capgo-Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor-Plugins von Capgo zur Implementierungsdetail in Capacitor-Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins, und Ionische Unternehmens-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen.