Erste Schritte

Installation

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

1. Paket installieren

   bun add @capgo/capacitor-watch

2. Mit nativen Projekten synchronisieren

   bunx cap sync

3. Plugin konfigurieren

   Grundlegendes Anwendungsbeispiel:

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

   Erforderliches iOS-Setup:

   1. Füge deiner iOS-App in Xcode die WatchConnectivity Capability hinzu
   2. Erstelle ein watchOS App-Target in deinem Xcode-Projekt
   3. Implementiere WatchConnectivity in deiner watchOS App (siehe unten)

   Das Plugin aktiviert die WCSession automatisch beim Laden.

   Android

   Erforderliches Wear OS Setup:

   1. Füge einen Wear OS Modul in dein Android-Projekt (wie bei der applicationId und Signing der Phone-App).
   2. Deklariere die capgo_watch Capability im Wear-Modul (siehe Erstellen einer Wear OS-App).
   3. Implementiere Data Layer Listener auf der Watch via Plugin-Pfaden (/capgo/message, /capgo/context, und andere).

   Das Phone-Plugin registriert beim Laden Wearable API Listener. Nutze getInfo() um verbundene Nodes und die Erkennung der Watch-App zu prüfen.

   Schritte im Detail: Erstellen einer Wear OS-App.

4. Antwort erfordernde Nachrichten verarbeiten

   // 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. App-State 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. User-Infos 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. Konnektivität ü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);
   });

Quickstart

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

Beispiel: updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

Beispiel: transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

Häufige Stolperfallen

• Listener: Handles beim Unmounten von Screens entfernen.
• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

Watch-App Implementierung

Deine watchOS-App muss WatchConnectivity implementieren. Hier ist ein SwiftUI-Beispiel:

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)

Sendet eine interaktive Nachricht an die Watch. Die Watch muss erreichbar sein.

Parameter:

• data: Objekt – Die an die Watch zu sendenden Daten

updateApplicationContext(options: UpdateContextOptions)

Aktualisiert den Application Context. Es wird nur der neueste Wert behalten.

Parameter:

• context: Objekt – Die zu synchronisierenden Kontextdaten

transferUserInfo(options: TransferUserInfoOptions)

Queue user info for reliable delivery.

Parameter:

• userInfo: Object – Die zu übertragenden Benutzerinfos

replyToMessage(options: ReplyMessageOptions)

Antwortet auf eine Nachricht, die eine Rückmeldung angefordert hat.

Parameter:

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

getInfo()

Ruft den Watch-Konnektivitätsstatus ab.

Rückgabe: WatchInfo Objekt mit:

• isSupported: boolean - Gibt an, ob watch APIs auf dieser Plattform verfügbar sind
• isPaired: boolean - Apple Watch gekoppelt (iOS) oder mindestens ein Wear OS Node verbunden (Android)
• isWatchAppInstalled: boolean - Companion Watch App installiert (iOS) oder capgo_watch Capability erkannt (Android)
• isReachable: boolean - Ob die Watch für Messaging sofort erreichbar ist
• activationState: number - Session-Status (iOS WCSession; Android 2, wenn ein Node verbunden ist, sonst 0)

getPluginVersion()

Ruft die native Plugin-Version ab.

Events

Event	Beschreibung
messageReceived	Einfache Nachricht von der Watch
messageReceivedWithReply	Nachricht mit Antwort-Erwartung (inkl. callbackId)
applicationContextReceived	Kontext-Update von der Watch
userInfoReceived	User-Info-Transfer von der Watch
reachabilityChanged	Watch-Verbindung geändert (nur iOS)
activationStateChanged	Session-Aktivierungsstatus geändert (nur iOS)

Kommunikationsmuster

Sofortige Nachrichtenübermittlung (sendMessage)

• Watch muss erreichbar sein
• Ideal für interaktive, zeitkritische Kommunikation
• Schlägt sofort fehl, wenn watch nicht verfügbar ist

Application Context (updateApplicationContext)

• Nur der aktuellste Wert – vorherige Werte werden überschrieben
• Ideal zum Synchronisieren des aktuellen App-States
• Wird geliefert, sobald watch verfügbar ist

Übertragung von Benutzerinfos (transferUserInfo)

• In der Reihenfolge eingereiht und zugestellt
• Ideal für wichtige Daten, die sicher ankommen müssen
• Funktioniert auch, wenn watch vorübergehend nicht erreichbar ist

Plattform-Hinweise

Siehe den Plattform-Support-Tabelle in der Plugin-Übersicht für eine Matrix pro Methode.

iOS (Apple Watch)

• Erfordert iOS 15.0 oder neuer
• Nutzt das WatchConnectivity-Framework
• Session wird beim Plugin-Load automatisch aktiviert
• Unterstützt Background Delivery für Context und User Info
• Emittiert reachabilityChanged und activationStateChanged

Android (Wear OS)

• Erfordert Google Play Services mit Wear OS Data Layer (play-services-wearable, im Plugin enthalten)
• Phone- und Wear-APKs müssen denselben gleich applicationId und signing key
• Watch-App muss Capability deklarieren capgo_watch
• Gibt es nicht emittiert reachabilityChanged oder activationStateChanged; poll getInfo() bei Bedarf
• Setup-Guide: Erstellen einer Wear OS-App

Web

• Watch-Messaging wird im Browser nicht unterstützt
• getInfo() löst auf mit isSupported: false und andere Felder mit sicheren Standardwerten
• getPluginVersion() löst auf mit { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, und replyToMessage mit einem Fehler für nicht verfügbare Ressourcen ablehnen
• addListener löst einen Handle über Capacitor auf WebPlugin, aber Watch-Events werden im Browser nicht unterstützt (Callbacks werden nie ausgeführt)

Häufige Anwendungsfälle

1. Data Sync: Watch- und Telefondaten synchron halten
2. Fernsteuerung: Telefonfunktionen über die Watch steuern
3. Benachrichtigungen: Eigene Benachrichtigungen an die Watch senden
4. Gesundheitsdaten: Fitness- und Gesundheitsdaten teilen
5. Mediensteuerung: Musikwiedergabe über die Watch steuern
6. Smart Home: Geräte direkt vom Handgelenk aus steuern

Fehlerbehebung

Watch nicht erreichbar:

• Sicherstellen, dass die Watch in Bluetooth-Reichweite ist
• Prüfen, ob beide Apps laufen
• Verifizieren, dass WCSession auf beiden Seiten aktiviert ist

Nachrichten nicht empfangen:

• Prüfen, ob Listener vor dem Senden registriert sind
• Sicherstellen, dass die Watch-App WCSessionDelegate implementiert
• Nutzt transferUserInfo für eine garantierte Zustellung

Session wird nicht aktiviert:

• WatchConnectivity-Capability in Xcode hinzufügen
• Prüfen, ob die Watch-App die passende Bundle ID hat
• Sicherstellen, dass beide Apps kompatible OS-Versionen nutzen

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Verwendung von @capgo/capacitor-watch für die native Funktion in „Verwendung von @capgo/capacitor-watch“, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.