Creazione di un'app watchOS

Questa guida ti guida attraverso la creazione di un watchOS da zero, compresa la configurazione del progetto in Xcode, l'integrazione del CapgoWatchSDK e la creazione di un'app watch funzionale con SwiftUI.

Per Wear OS, utilizza Creazione di un'app Wear OS al suo posto.

Prerequisites

Prima di iniziare, assicurati di avere:

• Xcode 15 o successivo (scarica dal Mac App Store)
• macOS Sonoma o successivo (per l'ultima versione di watchOS SDK)
• Un progetto iOS esistente Capacitor (esegui npx cap add ios se non l'hai già fatto)
• Account Apple Developer (un account gratuito funziona per lo sviluppo)

Panoramica della struttura del progetto

Dopo aver completato questa guida, il tuo progetto avrà questa struttura:

• Directoryios/

  • DirectoryApp/

    • DirectoryApp/ Progetto principale iOS (nome tuo)

      • …
    • App.xcodeproj
    • App.xcworkspace Usa questo per aprire il progetto
    • Podfile
  • DirectoryMioWatch/ (nuova app orologio)

    • DirectoryMioWatch/ (fonte app orologio)

      • MioWatchApp.swift
      • VistaContenuto.swift
      • DirectoryAssets.xcassets/

        • …
    • MyWatch.xcodeproj

Passo 1: Apri il tuo progetto iOS in Xcode

1. Naviga nel tuo progetto Capacitor ios/App cartella
2. Apre App.xcworkspace non .xcodeproj) cliccandolo due volte
3. duplicando il doppio clic

Caution

Apri sempre .xcworkspace file, no .xcodeproj. Il workspace include le dipendenze CocoaPods che il tuo progetto necessita.

Passo 2: Aggiungi un Target watchOS

1. Nell'area di Xcode, vai a File → Nuovo → Target…

2. Nel selettore di template:

   • Seleziona watchOS barra di navigazione in alto
   • App Clicca
   • Click Prossimo

3. Configura il tuo app orologio:

   • Nome del prodotto: MyWatch (o il nome che preferisci)
   • Team: Seleziona il tuo team di sviluppatori Apple
   • Identificatore dell'organizzazione: Deve corrispondere alla tua app iOS (ad esempio, app.capgo)
   • Identificatore del bundle: Sarà generato automaticamente (ad esempio, app.capgo.myapp.watchkitapp)
   • Lingua: Swift
   • Interfaccia Utente: SwiftUI
   • Tipo di App Watch: App (non App per App iOS esistente)
   • Disabilita Includi Scena di Notifica (a meno che non ne abbia bisogno)
   • Disabilita Includi Complicazione (a meno che non ne abbia bisogno)

4. Clicca Concludi

5. When richiesto “Attiva lo schema ‘MyWatch’?”, clicca Attiva

Passo 3: Configura Impostazioni dell'App Watch

1. Nella Navigazione del Progetto (barra laterale sinistra), seleziona il tuo progetto (l'icona blu in alto)

2. Seleziona il tuo target watch (ad esempio, “MyWatch”) dalla lista dei target

3. Vai al Generale tab:

   • Nome Visualizzato: Il nome mostrato sotto l'icona dell'app (ad esempio, “Il mio App”)
   • Identificatore del Bundle: Dovrebbe concludersi con .watchkitapp
   • Versione: Corrispondi alla versione del tuo app iOS
   • CostruzioneSincronizza il numero di build dell'app iOS

4. Vai a Signing & Capabilities tab:

   • : Abilita Gestisci automaticamente la firma
   • Scegli il tuo Team
   • Xcode creerà automaticamente i profili di provisioning.

5. Set Informazioni di distribuzione:

   • Informazioni di distribuzioneMinimi deployment

Passo 4: Aggiungi CapgoWatchSDK tramite Swift Package Manager

Il CapgoWatchSDK fornisce un'applicazione pronta all'uso WatchConnector CapgoWatchSDK fornisce una classe pronta all'uso

1. per la comunicazione. File → Aggiungi Dipendenze del Pacchetto…

2. Nella casella di ricerca, inserisci:

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

3. Tocca Invio e attendi che Xcode recuperi il pacchetto

4. Configura il pacchetto:

   • Regola di dipendenza: “Fino alla prossima versione maggiore” con “8.0.0”
   • Clicca Aggiungi Pacchetto

5. Scegli quali prodotti aggiungere:

   • IMPORTANTE: Seleziona solo CapgoWatchSDK
   • Assicurati che sia aggiunto al tuo target watch ad esempio, “MyWatch”), non l'app iOS
   • Clicca Aggiungi Pacchetto

Tip

Questo CapgoWatchSDK è specificamente progettato per le app watchOS. Fornisce WatchConnector, un ObservableObject che gestisce tutte le complessità di WatchConnectivity per te.

Passo 5: Implementa l'App Watch

Ora creiamo l'app per orologio code. Sostituisci i file generati automaticamente con i seguenti:

5.1 Crea il Punto di Ingresso dell'App

Modifica 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 Crea la vista principale

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

Passo 6: Configura l'app iOS per WatchConnectivity

Sezione intitolata “Passo 6: Configura l'app iOS per WatchConnectivity”

1. L'app iOS richiede anche la capacità di WatchConnectivity.

2. Scegli il tuo Target iOS App (non il target dell'orologio)

3. Vai a Tabella delle firme e delle capacità tab

4. Clicca + Capacità

5. Cerca e aggiungi WatchConnectivity (se disponibile) o potrebbe essere aggiunto automaticamente

6. Il plugin Capacitor gestisce automaticamente il lato iOS, ma assicurati che il tuo Info.plist abbia:

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

Etapo 7: Costruisci e Esegui

Esegui sul Simulatore

1. Scegli il tuo schema di orologio dal selettore dei schemi (in alto nella finestra di Xcode)

2. Scegli un simulatore di orologio:

   • Clicca sul selettore del dispositivo accanto al schema
   • Scegli un simulatore di Apple Watch (ad esempio “Apple Watch Series 9 (45mm)”)

3. Clicca il Run Esegui (▶️) o premi Cmd + R

4. L'iOS Simulator si avvierà con entrambi l'iPhone e l'Apple Watch

Esegui su dispositivo fisico

1. Connetti il tuo iPhone tramite USB

2. Assicurati che il tuo Apple Watch sia associato a quel iPhone

3. Scegli il tuo schema di orologio

4. Scegli il tuo Apple Watch fisico dal elenco dei dispositivi

5. Clicca Esegui

6. Prima volta: potresti dover fidarti del computer su entrambi i dispositivi

Tip

Per debuggare entrambe le app contemporaneamente:

1. Esegui l'app per iOS per primo
2. Poi esegui l'app per orologio con “Debug → Attacca al processo” per l'orologio

Passo 8: Testa la comunicazione

Da iPhone (Capacitor) a Watch

Nella tua app Capacitor:

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!' }
  });
}

Da Watch a iPhone

L'app per orologio utilizza 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)")
}

Gestisci i messaggi su iPhone

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

Avanzato: Delegato personalizzato per un controllo maggiore

Se hai bisogno di un controllo maggiore, implementa 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()

Troubleshooting

L'app non compare sull'orologio

1. Ensure bundle IDs are correctly related (watch app bundle ID should be iOS app bundle ID + .watchkitapp)
2. Verifica che entrambe le app siano firmate con lo stesso team
3. Su dispositivo fisico: Apri l'app Watch su iPhone → Il mio Watch → scorri per trovare la tua app → attiva ON

Non ricevi messaggi

1. Verifica che entrambe le app abbiano WCSession attivato
2. Controlla isReachable prima di inviare messaggi
3. Per una consegna garantita, utilizza transferUserInfo al posto di sendMessage
4. Assicurati che i listener siano registrati prima che l'altro dispositivo invii messaggi

Sottosezione intitolata “Errore di sessione non attivata”

1. Chiamare WatchConnector.shared.activate() all' inizio del ciclo di vita dell'app
2. Sul iOS, il plugin si attiva automaticamente - assicurati di aver importato il plugin
3. Verifica che la capacità di WatchConnectivity sia aggiunta al target iOS

Errori di compilazione con CapgoWatchSDK

1. Assicurati che il pacchetto sia aggiunto al target dell'orologioe non al target iOS
2. Pulisci cartella di compilazione: Prodotto → Pulisci cartella di compilazione (Cmd + Shift + K)
3. Riprista cache dei pacchetti: File → Pacchetti → Riprista Cache dei Pacchetti

Issue del Simulatore

1. Riprista i simulatori: Dispositivo → Cancella Tutti i Contenuti e le Impostazioni
2. Assicurati che i simulatori iOS e watchOS siano coppie compatibili
3. Entrambi i simulatori devono essere in esecuzione per consentire la comunicazione

Next Steps

• Creazione di un'app Wear OS per orologi Android
• Riferimento a API - Documentazione completa di API
• Modelli di comunicazione - Quando utilizzare ogni metodo
• Esempio di App - Esempio di App completo e funzionante

Continua da Creazione di un'app watchOS

Se stai utilizzando Creazione di un'app watchOS per pianificare il lavoro di plugin nativi, connettilo con Utilizza @capgo/capacitor-watch per la capacità nativa in Utilizzo di @capgo/capacitor-watch, Directory Plugin Capgo per il flusso di lavoro del prodotto in Directory Plugin Capgo, Plugin Capacitor di Capgo per il dettaglio di implementazione in Plugin Capacitor di Capgo, Aggiungere o Aggiornare Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare Plugin, e Sostituti di Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Sostituti di Plugin Enterprise Ionic.