Erstellung einer Uhr-App

Diese Anleitung führt Sie durch die Erstellung einer watchOS-Kompanion-App von Grund auf, einschließlich Projekt-Einrichtung in Xcode, Integration des CapgoWatchSDK und der Erstellung einer funktionsfähigen Uhr-App mit SwiftUI.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Xcode 15 oder später (herunterladen vom Mac App Store)
• macOS Sonoma oder später (für die neueste watchOS SDK)
• Ein bestehendes Capacitor iOS-Projekt (ausführen npx cap add ios wenn Sie noch nicht getan haben)
• Ein Apple-Entwicklerkonto (ein kostenloses Konto reicht für die Entwicklung aus)

Übersicht über die Projektstruktur

Nach Abschluss dieser Anleitung wird Ihr Projekt diese Struktur haben:

• Verzeichnisios/

  • VerzeichnisApp/

    • VerzeichnisApp/ (Ihr Haupt-App für iOS)

      • …
    • App.xcodeproj
    • App.xcworkspace (Verwenden Sie dies, um das Projekt zu öffnen)
    • Podfile
  • VerzeichnisMyWatch/ (neues Watch-App)

    • VerzeichnisMyWatch/ (Quelle für das Watch-App)

      • MyWatchApp.swift
      • ContentView.swift
      • VerzeichnisAssets.xcassets/

        • …
    • MyWatch.xcodeproj

Schritt 1: Öffnen Sie Ihr iOS-Projekt in Xcode

1. Navigieren Sie zu Ihrem Capacitor-Projekt ios/App Ordner
2. Öffnen App.xcworkspace nicht .xcodeprojdurch Doppelklicken
3. Warten Sie, bis Xcode das Projekt indexiert

Vorsicht

Öffnen Sie immer das .xcworkspace Datei, nicht .xcodeprojDie Workspace enthält CocoaPods-Abhängigkeiten, die Ihr Projekt benötigt.

Schritt 2: Fügen Sie ein watchOS-Ziel hinzu

1. In Xcode gehen Sie zu Datei → Neues → Ziel…

2. In der Vorlagenauswahl:

   • Wählen Sie watchOS Registerkarte oben
   • Wählen Sie App
   • Klicken Sie auf Weiter

3. Ihre Uhr-App konfigurieren:

   • __CAPGO_KEEP_0__: MyWatch (oder Ihr bevorzugter Name)
   • Team:: Wählen Sie Ihr Apple-Entwicklerteam
   • Organisations-Identifier:: Sollte Ihrem iOS-App entsprechen (z.B., app.capgo)
   • Bundle-Identifier:: Wird automatisch generiert (z.B., app.capgo.myapp.watchkitapp)
   • Sprache:Swift
   • Benutzeroberfläche:: SwiftUI
   • Arten von Apple Watch Apps: App (nicht App für bestehende iOS-App)
   • Ablehnen Benachrichtigungsszenario einschließen (falls Sie es benötigen)
   • Ablehnen Komplikation einschließen (falls Sie es benötigen)

4. Klicken Fertigstellen

5. Wenn Sie aufgefordert werden, ‘MyWatch’-Schematismus zu aktivieren, klicken Sie Aktivieren

Schritt 3: Konfiguriere Watch-App-Einstellungen

1. Wählen Sie in der Project Navigator (linke Seitenleiste) Ihr Projekt (das blaue Icon oben) aus

2. Wählen Sie Ihr Watch-Target (z.B. “MeinWatch”) aus der Liste der Ziele

3. Gehe zur Allgemein Registerkarte:

   • Anzeigename: Der Name, der unter der App-Icon angezeigt wird (z.B. “Meine App”)
   • Bundle-Identifier: Soll mit .watchkitapp
   • Version: Deine iOS-Anwendungsversion anpassen
   • Build: Deine iOS-Anwendungsbauversion anpassen

4. Zu Zertifizierung und Fähigkeiten tab:

   • Aktivieren Automatisch die Zertifizierung verwalten
   • Wähle dein Team
   • Xcode erstellt die Bereitstellungsprofile automatisch

5. Konfiguration Bereitstellungsinformationen:

   • Mindestanforderungen an die Bereitstellung: watchOS 9.0 oder höher

Schritt 4: Fügen Sie CapgoWatchSDK über Swift Package Manager hinzu

Das CapgoWatchSDK bietet eine fertige Lösung für die Kommunikation. WatchConnector In Xcode gehen Sie zu

1. Datei → Hinzufügen von Abhängigkeiten… Im Suchfeld eingeben:

2. Auf die Zwischenablage kopieren

   https://github.com/Cap-go/capacitor-watch.git

3. Drücken Sie Enter und warten Sie, bis Xcode das Paket herunterlädt

4. Konfigurieren Sie das Paket:

   • Abhängigkeitsregel: „Bis zur nächsten Hauptversion“ mit „8.0.0“
   • Klicken Sie Paket hinzufügen

5. Wählen Sie, welche Produkte hinzugefügt werden sollen:

   • WICHTIG: Wählen Sie nur CapgoWatchSDK
   • Stellen Sie sicher, dass es zu Ihrem Beobachtungsziel (z. B. „MeinBeobachtungsziel“), nicht dem iOS-App-ziel hinzugefügt wurde
   • Klicken Sie Paket hinzufügen

Tipp

Es ist speziell für watchOS-Anwendungen konzipiert. Es bietet CapgoWatchSDK , einen ObservableObject, der alle WatchConnectivity-Komplexitäten für Sie handhabt. WatchConnectorSchritt 5: Implementieren Sie die Watch-App

Abschnitt mit dem Titel „Schritt 5: Implementieren Sie die Watch-App“

Now let’s create the watch app code. Replace the auto-generated files with the following:

Abschnitt mit dem Titel „5.1 Erstellen Sie den Anwendungsstartpunkt“

Bearbeiten MyWatch/MyWatchApp.swift:

import SwiftUI
import CapgoWatchSDK

@main
struct MyWatchApp: App {
    init() {
        // Activate WatchConnectivity when app launches
        WatchConnector.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

5.2 Erstellen Sie die Hauptansicht

Bearbeiten MyWatch/ContentView.swift:

import SwiftUI
import 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 status
struct 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: Konfigurieren Sie die iOS-Anwendung für WatchConnectivity

Ihre iOS-Anwendung benötigt auch die WatchConnectivity-Fähigkeit.

1. Wählen Sie in der Projektnavigator Ihr Projekt

2. Wählen Sie Ihr iOS-App-Ziel (keine Uhrzielziel)

3. Zu Signierung & Fähigkeiten Registerkarte

4. Klicken Sie + Fähigkeit

5. Suchen Sie nach und fügen Sie hinzu WatchConnectivity (wenn verfügbar) oder es wird möglicherweise automatisch hinzugefügt

6. Das Capacitor-Plugin handhabt die iOS-Seite automatisch, aber stellen Sie sicher, dass Ihr Info.plist folgende enthält:

   <key>WKCompanionAppBundleIdentifier</key>
   <string>app.capgo.myapp.watchkitapp</string>

Schritt 7: Erstellen und Ausführen

Auf Simulator ausführen

1. Wählen Sie Ihr Watch-Schema aus dem Schemaselector (oben im Xcode-Fenster)

2. Wählen Sie einen Apple Watch-Simulator:

   • Klicken Sie auf den Geräte-Selector neben dem Schema
   • Wählen Sie einen Apple Watch-Simulator (z.B. „Apple Watch Series 9 (45mm)“)

3. Klicken Sie auf den Ausführen Button (▶️) oder drücken Sie Cmd + R

4. Der iOS-Simulator wird mit iPhone und Apple Watch gestartet

Auf physischem Gerät ausführen

1. Verbinden Sie Ihr iPhone über USB

2. Stellen Sie sicher, dass Ihr Apple Watch mit diesem iPhone pairt ist

3. Wählen Sie Ihr Watch-Schema

4. Wählen Sie Ihr physisches Apple Watch aus der Geräteliste

5. Klicken Sie Ausführen

6. Erstes Mal: Sie müssen Ihrem Computer auf beiden Geräten vertrauen

Tipps

Um beide Apps gleichzeitig zu debuggen:

1. Führen Sie die iOS-App zuerst aus
2. Dann starten Sie das Watch-App mit „Debug → Attach to Process“ für das Watch

Schritt 8: Kommunikation testen

Von iPhone (Capacitor) zu Watch

In Ihrer Capacitor-App:

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

// Check connection
const info = await CapgoWatch.getInfo();
console.log('Watch reachable:', info.isReachable);

// Send a message
if (info.isReachable) {
  await CapgoWatch.sendMessage({
    data: { action: 'update', value: 'Hello from iPhone!' }
  });
}

Von Watch zu iPhone

Die Watch-App verwendet WatchConnector:

// Send message (fire and forget)
WatchConnector.shared.sendMessage(["action": "buttonTapped"])

// Send message with reply
WatchConnector.shared.sendMessage(["request": "getData"]) { reply in
    print("Got reply: \(reply)")
}

Nachrichten auf iPhone bearbeiten

// Listen for messages from watch
await CapgoWatch.addListener('messageReceived', (event) => {
  console.log('Message from watch:', event.message);
  // { action: 'buttonTapped' }
});

// Handle messages that need a reply
await 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: Benutzerdefinierte Delegate für mehr Kontrolle

Wenn Sie mehr Kontrolle benötigen, implementieren Sie WatchConnectorDelegate:

import SwiftUI
import 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 = handler
WatchConnector.shared.activate()

Fehlersuche

App auf Uhr nicht sichtbar

1. Stellen Sie sicher, dass die Bundle-IDs korrekt miteinander in Beziehung stehen (die Bundle-ID der Uhr-App sollte die Bundle-ID der iOS-App sein + .watchkitapp)
2. Überprüfen Sie, ob beide Apps mit demselben Team signiert sind
3. Auf physischem Gerät: Öffnen Sie die Watch-App auf dem iPhone → Meine Uhr → scrollen Sie, um Ihre App zu finden → ON schalten

Nicht empfangene Nachrichten

1. Stellen Sie sicher, dass beide Apps die WCSession aktiviert haben
2. Überprüfen isReachable Bevor Nachrichten gesendet werden
3. Für eine sichere Zustellung verwenden Sie transferUserInfo anstatt sendMessage
4. Stellen Sie sicher, dass Hörer registriert sind, bevor das andere Gerät Nachrichten sendet

Fehler „Sitzung nicht aktiviert“

1. Aufrufen WatchConnector.shared.activate() früh im App-Lebenszyklus
2. Bei iOS aktiviert sich der Plugin automatisch - stellen Sie sicher, dass das Plugin importiert ist
3. Überprüfen Sie, dass die WatchConnectivity-Fähigkeit zur iOS-Zielgruppe hinzugefügt wurde

CapgoWatchSDK-Verbindungsfehler

1. Stellen Sie sicher, dass das Paket zur watch-Zielgruppehinzugefügt ist, nicht zur iOS-Zielgruppe
2. Ordner für den Clean Build löschen: Produkt → Ordner für Clean Build löschen (Cmd + Shift + K)
3. Paket-Caches zurücksetzen: Datei → Pakete → Paket-Caches zurücksetzen

Simulator-Probleme

1. Die Simulatoren zurücksetzen: Gerät → Alle Inhalte und Einstellungen löschen
2. Stellen Sie sicher, dass iOS- und watchOS-Simulatoren kompatible Paare sind
3. Beide Simulatoren müssen läuft, damit die Kommunikation funktioniert

Nächste Schritte

• API-Referenz - API-Dokumentation abschließen
• Kommunikationsmuster - Wann jede Methode verwenden
• Beispiel-App - Vollständiges funktionierendes Beispiel