Erstellung einer watchOS-App

Diese Anleitung führt Sie durch die Erstellung einer watchOS-Kompanion-App von Grund auf, einschließlich der Projektierung in Xcode, der 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)
• Apple-Entwicklerkonto (Ein kostenloses Konto reicht für die Entwicklung aus)

Übersicht über die Projektstruktur

Nach Abschluss dieses Leitfadens wird Ihr Projekt diese Struktur haben:

• Verzeichnisios/

  • VerzeichnisApp/

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

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

    • VerzeichnisMyWatch/ (Quelle der Uhr-App)

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

        • …
    • MyWatch.xcodeproj

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

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

Achtung

Öffnen Sie immer das .xcworkspace Datei, nicht .xcodeproj.

Der Workspace enthält CocoaPods-Abhängigkeiten, die Ihr Projekt benötigt.

1. Sektion mit dem Titel „Schritt 2: Hinzufügen eines watchOS-Ziels“ In Xcode gehen Sie zu

2. Datei → Neu → Ziel…

   • In der Vorlageauswahl: Wählen Sie aus Oberer Reiter
   • Wählen Sie App
   • Klicken Sie Zurück

3. Konfigurieren Sie Ihre Uhranwendung:

   • Produktname: MyWatch (oder Ihren bevorzugten Namen)
   • Team: Wählen Sie Ihr Apple-Entwicklerteam
   • Organisations-Identifier: Sollte Ihrem iOS-App entsprechen (z.B. app.capgo)
   • Bundle-Bezeichner: Wird automatisch generiert (z.B., app.capgo.myapp.watchkitapp)
   • Sprache:
   • SwiftBenutzeroberfläche
   • : SwiftUIArten von Apple Watch Apps
   • : App (nicht App für bestehende iOS-App) Abwählen Benachrichtigungsszenario einschließen
   • (es sei denn, Sie benötigen es) Komplikation einschließen (außer Sie benötigen es)

4. Klicken Fertigstellen

5. Wenn Sie aufgefordert werden “Aktivieren Sie das ‘Mein-Uhr’-Szenario?”, klicken Sie Aktivieren

Schritt 3: Konfigurieren Sie die Watch-App-Einstellungen

1. Wählen Sie in der Projekt-Navigator-Leiste (links) Ihr Projekt (das blaue Icon oben) aus

2. Wählen Sie Ihr Uhrziel (z.B. “Mein-Uhr”) aus der Liste der Ziele aus

3. Gehe zur Allgemeine Einstellungen tab:

   • AnzeigenameAnzeigename: Der Name, der unter dem App-Icon angezeigt wird (z.B. "Meine App")
   • Bundle-BezeichnerBezeichner sollte mit .watchkitapp
   • VersionVersion: Passen Sie Ihre iOS-App-Version an
   • BuildBuild: Passen Sie Ihre iOS-App-Build-Nummer an

4. Zu Signierung und Fähigkeiten tab:

   • Aktivieren Automatisch die Signierung verwalten
   • Wählen Sie Ihr Team
   • context: Capgo Marketing-Website. Rolle: Kurzbeschreibung oder Navigationspunkt. Anzeige auf: Seite sla.astro. Nachrichtenschlüssel `team_plan` (Team-Plan).

5. Xcode erstellt die Bereitstellungsprofile automatisch Einstellen:

   • Bereitstellungs-InfoMindestbereitstellungen

: ab watchOS 9.0 oder später

Abschnitt mit dem Titel „Schritt 4: Fügen Sie CapgoWatchSDK über Swift Package Manager hinzu“ WatchConnector Klasse für die Kommunikation.

1. Gehe in Xcode zu Datei → Hinzufügen von Paketabhängigkeiten…

2. Im Suchfeld eingeben:

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

3. Drücke Enter und warte, bis Xcode das Paket herunterlädt

4. Konfiguriere das Paket:

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

5. Wähle die Produkte aus, die du hinzufügen möchtest:

   • WICHTIG: Wählen Sie nur CapgoWatchSDK
   • Stellen Sie sicher, dass es zu Ihrem Uhrziel (z.B. "Meine Uhr"), nicht der iOS-Anwendung Klicken Sie
   • Paket hinzufügen Tip

Dieses

wird speziell für Uhr-Anwendungen entwickelt. Es bietet CapgoWatchSDK , eine ObservableObject, die alle WatchConnectivity-Komplexitäten für Sie handhabt. WatchConnectorAdd Package

Schritt 5: Implementieren Sie die Watch-App

Nun erstellen wir die Watch-App code. Ersetzen Sie die automatisch generierten Dateien durch die folgenden:

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 im Projekt-Explorer Ihr Projekt

2. Wählen Sie Ihr iOS-App-Ziel (nicht das Ziel für die Uhr)

3. Gehe zu Zertifizierung und Fähigkeiten Registerkarte

4. Klicken Sie auf Fähigkeit hinzufügen

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

6. Das Plugin Capacitor handhabt die iOS-Seite automatisch, aber stelle sicher, dass dein Info.plist folgende Einträge enthält:

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

Schritt 7: Erstellen und Ausführen

Auf dem Simulator ausführen

1. Wähle in der Scheme-Auswahl (oben im Xcode-Fenster) deine Uhr-App aus

2. Wähle einen Apple Watch-Simulator aus:

   • Klicke auf den Geräteauswahl-Reiter neben der Scheme
   • Wähle einen Apple Watch-Simulator (z.B. “Apple Watch Series 9 (45mm)”

3. Klicken Sie auf den Starten Schaltfläche (▶️) oder drücken Sie Cmd + R

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

Run on Physical Device

1. Verbinden Sie Ihr iPhone über USB

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

3. Wählen Sie Ihr Watch-Schema

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

5. Klicken Sie Starten

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

Tip

Um beide Apps gleichzeitig zu debuggen:

1. Zuerst starten Sie die iOS-App
2. Dann starten Sie die Uhr-App mit "Debug → Attach to Process" für die Uhr

Schritt 8: Kommunikation testen

Von iPhone (Capacitor) zu Uhr

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

Hilfe bei Problemen

Uhr-App erscheint nicht auf Uhr

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

Nachrichten werden nicht empfangen

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

”Sitzung nicht aktiviert”-Fehler

1. Aufrufen WatchConnector.shared.activate() context
2. früh im Lebenszyklus der App
3. Bei iOS aktiviert sich der Plugin automatisch - stellen Sie sicher, dass der Plugin importiert ist

Überprüfen Sie, dass die WatchConnectivity-Fähigkeit zur iOS-Ziel hinzugefügt ist

1. Sektion mit dem Titel “Fehler beim Bauen mit CapgoWatchSDK” Stellen Sie sicher, dass das Paket zur watch-Ziel hinzugefügt ist, nicht Ziel für iOS
2. Ordner für Clean Build: Produkt → Clean Build Ordner (Cmd + Shift + K)
3. Paket-Caches zurücksetzen: Datei → Pakete → Paket-Caches zurücksetzen

Simulator-Probleme

1. Simulatoren zurücksetzen: Gerät → Alle Inhalte und Einstellungen löschen
2. Stellen Sie sicher, dass die 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 - Anwendungsbereiche jeder Methode
• Beispiel-App - Vollständiges funktionierendes Beispiel

Weitermachen von der Erstellung einer watchOS-App

Wenn Sie Erstellung einer watchOS-App um native Plugin-Arbeit zu planen, verbinden Sie es mit Mit @capgo/capacitor-watch zur nativen Fähigkeit in Mit @capgo/capacitor-watch, Capgo Plugin-Verzeichnis zur Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo zur Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin Alternativen zur Produktworkflow in Ionic Enterprise Plugin Alternativen.