Erstellen einer watchOS App
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
In diesem Guide lernst du, wie du eine watchOS Companion-App von Grund auf erstellst – inklusive Projekt-Setup in Xcode, Integration des CapgoWatchSDK und dem Erstellen einer funktionalen Watch-App mit SwiftUI.
Für Wear OS nutze Erstellen einer Wear OS-App stattdessen.
Voraussetzungen
Abschnitt: „Voraussetzungen“Before you begin, ensure you have:
- Xcode 15 oder neuer (Download aus dem Mac App Store)
- macOS Sonoma oder neuer (für die neueste watchOS SDK)
- Ein bestehendes Capacitor iOS-Projekt (ausführen
npx cap add ios, falls noch nicht geschehen) - Apple Developer Account (ein kostenloses Konto reicht für die Entwicklung)
Übersicht der Projektstruktur
Abschnitt mit dem Titel „Übersicht der Projektstruktur“Nach Abschluss dieses Guides hat Ihr Projekt diese Struktur:
Verzeichnisios/
VerzeichnisApp/
VerzeichnisApp/ (deine Haupt-iOS-App)
- …
- App.xcodeproj
- App.xcworkspace (nutze dies zum Öffnen des Projekts)
- Podfile
VerzeichnisMyWatch/ (neue Watch-App)
VerzeichnisMyWatch/ (Watch-App-Quellcode)
- MyWatchApp.swift
- ContentView.swift
VerzeichnisAssets.xcassets/
- …
- MyWatch.xcodeproj
Schritt 1: iOS-Projekt in Xcode öffnen
Abschnitt mit dem Titel „Schritt 1: iOS-Projekt in Xcode öffnen“- Navigieren Sie zu Ihrem Capacitor-Projekt
ios/AppOrdner - Öffne
App.xcworkspace(nicht.xcodeproj) durch Doppelklick darauf - Warten Sie, bis Xcode das Projekt indiziert
Schritt 2: watchOS-Target hinzufügen
Abschnitt mit dem Titel „Schritt 2: watchOS-Target hinzufügen“-
Gehe in Xcode zu Datei → Neu → Target…
-
Im Template-Auswahlmenü:
- Wähle watchOS tab at the top
- Wähle App hinzu
- Klicken Weiter
-
Konfiguriere deine Watch-App:
- Produktname:
MyWatch(oder Ihr bevorzugter Name) - Team: Wählen Sie Ihr Apple-Developer-Team aus
- Organisationskennung: Muss mit Ihrer iOS-App übereinstimmen (z. B.
app.capgo) - Bundle-Identifier: Wird automatisch generiert (z. B.
app.capgo.myapp.watchkitapp) - Sprache: Swift
- Benutzeroberfläche: SwiftUI
- Watch-App-Typ: App (nicht „App für bestehende iOS-App“)
- Abwählen Notification Scene einschließen (außer du benötigst sie)
- Abwählen Complication einschließen (außer du benötigst sie)
- Produktname:
-
Klicken Fertigstellen
-
Wenn „Activate ‚MyWatch‘ scheme?“ erscheint, klicke auf Aktivieren
Schritt 3: Watch-App-Einstellungen konfigurieren
Abschnitt: „Schritt 3: Watch-App-Einstellungen konfigurieren“-
Wähle im Project Navigator (linke Seitenleiste) dein Projekt aus (das blaue Icon oben)
-
Wähle dein Watch-Target (z. B. „MyWatch“) aus der Targets-Liste aus
-
Besuchen Sie die Allgemein Tab:
- Anzeigename: Der Name, der unter dem App-Icon angezeigt wird (z. B. „Meine App“)
- Bundle-Identifier: Sollte enden mit
.watchkitapp - Version: Muss mit deiner iOS-App-Version übereinstimmen
- Build: Build-Nummer Ihrer iOS-App angleichen
-
Gehe zu Signing & Capabilities Tab:
- Aktivieren Signierung automatisch verwalten
- Wähle deine Team
- Xcode erstellt Provisioning-Profile automatisch
-
Setzen Sie Deployment-Infos:
- Mindestversionen: watchOS 9.0 oder neuer
Schritt 4: CapgoWatchSDK via Swift Package Manager hinzufügen
Abschnitt mit dem Titel „Schritt 4: CapgoWatchSDK via Swift Package Manager hinzufügen“Das CapgoWatchSDK bietet eine einsatzbereite WatchConnector Klasse für die Kommunikation.
-
Gehe in Xcode zu Ablage → Paketabhängigkeiten hinzufügen…
-
Gib im Suchfeld Folgendes ein:
https://github.com/Cap-go/capacitor-watch.git -
Drücke Enter und warte, bis Xcode das Package lädt
-
Konfiguriere das Package:
- Abhängigkeitsregel: „Bis zur nächsten Major-Version“ mit „8.0.0“
- Klicken Paket hinzufügen
-
Wählen Sie aus, welche Produkte hinzugefügt werden sollen:
- WICHTIG: Nur auswählen
CapgoWatchSDK - Stellen Sie sicher, dass es zu Ihrem watch-Ziel (z. B. „MyWatch“), nicht die iOS-App
- Klicken Paket hinzufügen
- WICHTIG: Nur auswählen
Schritt 5: Watch-App implementieren
Abschnitt mit dem Titel „Schritt 5: Watch-App implementieren“Erstellen Sie nun die Watch-App code. Ersetzen Sie die automatisch generierten Dateien durch die folgenden:
5.1 App-Einstiegspunkt erstellen
Abschnitt mit dem Titel „5.1 App-Einstiegspunkt erstellen“Bearbeiten MyWatch/MyWatchApp.swift:
import SwiftUIimport CapgoWatchSDK
@mainstruct MyWatchApp: App { init() { // Activate WatchConnectivity when app launches WatchConnector.shared.activate() }
var body: some Scene { WindowGroup { ContentView() } }}5.2 Hauptansicht erstellen
Abschnitt mit dem Titel „5.2 Hauptansicht erstellen“Bearbeiten MyWatch/ContentView.swift:
import SwiftUIimport CapgoWatchSDK
struct ContentView: View { // Observe the WatchConnector for automatic UI updates @ObservedObject var connector = WatchConnector.shared
// Local state @State private var messageText = "" @State private var statusMessage = "Ready"
var body: some View { ScrollView { VStack(spacing: 16) { // Connection Status ConnectionStatusView(connector: connector)
Divider()
// Message Input TextField("Message", text: $messageText) .textFieldStyle(.roundedBorder)
// Send Buttons HStack { Button("Send") { sendMessage() } .disabled(!connector.isReachable || messageText.isEmpty)
Button("Request") { sendWithReply() } .disabled(!connector.isReachable || messageText.isEmpty) }
Divider()
// Status Text(statusMessage) .font(.caption) .foregroundColor(.secondary)
// Last Received Message if !connector.lastMessage.isEmpty { VStack(alignment: .leading) { Text("Last Message:") .font(.caption) .foregroundColor(.secondary) Text(formatMessage(connector.lastMessage)) .font(.caption2) } .frame(maxWidth: .infinity, alignment: .leading) } } .padding() } }
private func sendMessage() { connector.sendMessage(["text": messageText, "timestamp": Date().timeIntervalSince1970]) statusMessage = "Message sent" messageText = "" }
private func sendWithReply() { connector.sendMessage(["text": messageText, "needsReply": true]) { reply in DispatchQueue.main.async { statusMessage = "Reply: \(formatMessage(reply))" } } messageText = "" }
private func formatMessage(_ message: [String: Any]) -> String { message.map { "\($0.key): \($0.value)" }.joined(separator: ", ") }}
// Separate view for connection statusstruct ConnectionStatusView: View { @ObservedObject var connector: WatchConnector
var body: some View { HStack { Circle() .fill(connector.isReachable ? Color.green : Color.red) .frame(width: 12, height: 12)
Text(connector.isReachable ? "Connected" : "Disconnected") .font(.headline)
Spacer()
if connector.isActivated { Image(systemName: "checkmark.circle.fill") .foregroundColor(.green) } } }}
#Preview { ContentView()}Schritt 6: iOS-App für WatchConnectivity konfigurieren
Abschnitt mit dem Titel „Schritt 6: iOS-App für WatchConnectivity konfigurieren“Ihre iOS-App benötigt ebenfalls die WatchConnectivity-Funktion.
-
Wählen Sie Ihr Projekt im Project Navigator aus
-
Wähle deine iOS-App-Ziel (nicht das Watch-Ziel)
-
Gehe zu Signing & Capabilities Tab
-
Klicken + Capability
-
Suchen und hinzufügen WatchConnectivity (falls verfügbar) oder es wird möglicherweise automatisch hinzugefügt
-
Das Capacitor-Plugin übernimmt die iOS-Seite automatisch, aber stellen Sie sicher, dass Ihre Info.plist Folgendes enthält:
<key>WKCompanionAppBundleIdentifier</key><string>app.capgo.myapp.watchkitapp</string>
Schritt 7: Build und Run
Abschnitt mit dem Titel „Schritt 7: Build and Run“Im Simulator ausführen
Abschnitt mit dem Titel „Im Simulator ausführen“-
Wähle dein Watch-Schema im Schema-Auswahlmenü (oben im Xcode-Fenster) aus
-
Wähle einen Watch-Simulator aus:
- Klicke auf den Geräteauswahl neben dem Schema
- Wähle einen Apple Watch-Simulator aus (z. B. „Apple Watch Series 9 (45mm)“)
-
Klicke auf das Ausführen Button (▶️) oder drücke
Cmd + R -
Der iOS-Simulator startet mit iPhone und Apple Watch
Auf echtem Gerät ausführen
Abschnitt mit dem Titel „Auf echtem Gerät ausführen“-
iPhone per USB verbinden
-
Stelle sicher, dass deine Apple Watch mit diesem iPhone gekoppelt ist
-
Wähle dein Watch-Scheme aus
-
Wähle deine physische Apple Watch aus der Geräteliste aus
-
Klicken Ausführen
-
Beim ersten Mal: Eventuell musst du deinem Computer auf beiden Geräten vertrauen
Schritt 8: Kommunikation testen
Abschnitt: „Schritt 8: Kommunikation testen“Vom iPhone (Capacitor) zur Watch
Abschnitt: „Vom iPhone (Capacitor) zur Watch“In deiner Capacitor-App:
import { CapgoWatch } from '@capgo/capacitor-watch';
// Check connectionconst info = await CapgoWatch.getInfo();console.log('Watch reachable:', info.isReachable);
// Send a messageif (info.isReachable) { await CapgoWatch.sendMessage({ data: { action: 'update', value: 'Hello from iPhone!' } });}Von der Watch zum iPhone
Abschnitt: „Von der Watch zum iPhone“Die Watch-App nutzt WatchConnector:
// Send message (fire and forget)WatchConnector.shared.sendMessage(["action": "buttonTapped"])
// Send message with replyWatchConnector.shared.sendMessage(["request": "getData"]) { reply in print("Got reply: \(reply)")}Nachrichten auf dem iPhone verarbeiten
Abschnitt: „Nachrichten auf dem iPhone verarbeiten“// Listen for messages from watchawait CapgoWatch.addListener('messageReceived', (event) => { console.log('Message from watch:', event.message); // { action: 'buttonTapped' }});
// Handle messages that need a replyawait CapgoWatch.addListener('messageReceivedWithReply', async (event) => { console.log('Request from watch:', event.message);
// Send reply back await CapgoWatch.replyToMessage({ callbackId: event.callbackId, data: { status: 'success', items: ['item1', 'item2'] } });});Erweitert: Custom Delegate für mehr Kontrolle
Abschnitt mit dem Titel „Erweitert: Custom Delegate für mehr Kontrolle“Wenn du mehr Kontrolle brauchst, implementiere WatchConnectorDelegate:
import SwiftUIimport CapgoWatchSDK
class WatchHandler: WatchConnectorDelegate { func didReceiveMessage(_ message: [String: Any]) { print("Received: \(message)") // Handle incoming message }
func didReceiveMessageWithReply(_ message: [String: Any], replyHandler: @escaping ([String: Any]) -> Void) { print("Received request: \(message)") // Process and send reply replyHandler(["status": "processed"]) }
func didReceiveApplicationContext(_ context: [String: Any]) { print("Context updated: \(context)") }
func didReceiveUserInfo(_ userInfo: [String: Any]) { print("User info received: \(userInfo)") }
func reachabilityDidChange(_ isReachable: Bool) { print("Reachability changed: \(isReachable)") }
func activationDidComplete(with state: WCSessionActivationState) { print("Activation completed: \(state.rawValue)") }}
// In your app setup:let handler = WatchHandler()WatchConnector.shared.delegate = handlerWatchConnector.shared.activate()Fehlerbehebung
Abschnitt mit dem Titel „Troubleshooting“Watch App erscheint nicht auf der Watch
Abschnitt mit dem Titel „Watch App erscheint nicht auf der Watch“- Stelle sicher, dass die Bundle IDs korrekt verknüpft sind (die Bundle ID der Watch-App muss die iOS-App Bundle ID +
.watchkitapp) - Prüfe, ob beide Apps mit demselben Team signiert sind
- Auf einem physischen Gerät: Watch App auf dem iPhone öffnen → Meine Watch → zu deiner App scrollen → Schalter auf AN
Nachrichten kommen nicht an
Abschnitt mit dem Titel „Nachrichten werden nicht empfangen“- Prüfen, ob in beiden Apps WCSession aktiviert ist
- Prüfen
isReachablebevor Nachrichten gesendet werden - Für garantierte Zustellung verwenden Sie
transferUserInfoanstattsendMessage - Stellen Sie sicher, dass die Listener registriert sind, bevor das andere Gerät Nachrichten sendet
Fehler „Session Not Activated“
Abschnitt mit dem Titel „Fehler „Session Not Activated““- Rufe
WatchConnector.shared.activate()früh im App-Lebenszyklus - Auf iOS wird das Plugin automatisch aktiviert – sicherstellen, dass es importiert ist
- Prüfen, ob die WatchConnectivity-Fähigkeit dem iOS-Ziel hinzugefügt wurde
Build-Fehler mit CapgoWatchSDK
Abschnitt mit dem Titel „Build-Fehler mit CapgoWatchSDK“- Sicherstellen, dass das Paket dem watch-Zielhinzugefügt wurde, nicht dem iOS-Ziel
- Build-Ordner leeren: Produkt → Build-Ordner leeren (Cmd + Shift + K)
- Paket-Caches zurücksetzen: Datei → Pakete → Paket-Caches zurücksetzen
Simulator-Probleme
Abschnitt mit dem Titel „Simulator-Probleme“- Simulatoren zurücksetzen: Gerät → Alle Inhalte und Einstellungen löschen
- Stellen Sie sicher, dass die iOS- und watchOS-Simulatoren kompatible Paare sind
- Beide Simulatoren müssen laufen, damit die Kommunikation funktioniert
Nächste Schritte
Abschnitt „Nächste Schritte“- Erstellen einer Wear OS-App für Android-Uhren
- API Referenz - API Dokumentation abschließen
- Kommunikationsmuster - Wann du welche Methode nutzt
- Beispiel-App - Vollständiges, funktionierendes Beispiel
Weiterlesen: Erstellen einer watchOS App
Abschnitt mit dem Titel „Weiterlesen: Erstellen einer watchOS App“Wenn du es nutzt Erstellen einer watchOS App 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.