Creazione di un'app watchOS

Questa guida ti guida nella creazione di un'app di accompagnamento watchOS da zero, inclusa la configurazione del progetto in Xcode, l'integrazione del CapgoWatchSDK e la creazione di un'app orologio funzionale con SwiftUI.

Requisiti

Prima di iniziare, assicurati di avere:

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

Struttura del Progetto: Panoramica

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

• Directoryios/

  • DirectoryApp/

    • DirectoryApp/ (il tuo app iOS principale)

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

    • DirectoryMyWatch/ (sorgenti dell'app orologio)

      • MyWatchApp.swift
      • ContentView.swift
      • DirectoryAssets.xcassets/

        • …
    • MyWatch.xcodeproj

Passo 1: Apri il tuo progetto iOS in Xcode

1. Naviga al tuo progetto Capacitor ios/App cartella
2. Apri App.xcworkspace non .xcodeprojdoppiocliccandolo
3. Aspetta che Xcode indichi il progetto

Attenzione

Sii sempre cauto e apri .xcworkspace file, non .xcodeproj Il workspace include le dipendenze CocoaPods che il tuo progetto necessita.

Passo 2: Aggiungi un Target watchOS

1. In Xcode, vai a File → Nuovo → Target…

2. In il scegli il modello:

   • Scegli watchOS tabella in alto
   • Scegli App
   • Clicca Prossimo

3. Configura la tua app per orologio:

   • Nome del prodotto: MyWatch (o il tuo nome preferito)
   • Team: Seleziona il tuo team di sviluppatore Apple
   • Identificatore dell'organizzazione: Deve corrispondere alla tua app iOS (ad esempio, app.capgo)
   • Identificatore del pacchetto: Sarà generato automaticamente (ad esempio, app.capgo.myapp.watchkitapp)
   • Lingua: Swift
   • Interfaccia utente: SwiftUI
   • Tipo di app per orologioApp (non App per App iOS esistente)
   • Deselezionare Includi la scena di notifica (a meno che non ne abbia bisogno)
   • Deselezionare Includi la complicazione (a meno che non ne abbia bisogno)

4. Clicca Completa

5. Quando verrai chiesto di ‘Attivare lo schema ‘MyWatch’?’, clicca Attiva

Passo 3: Configura Impostazioni dell'App per l'Orologio

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

2. Seleziona il tuo target per l'orologio (ad esempio, “MyWatch”) dalla lista dei target

3. Vai al Generale tabella:

   • Nome a Schermo: Il nome mostrato sotto l'icona dell'app (ad esempio, “Il mio App”)
   • Identificatore della Raccolta: Dovrebbe concludersi con .watchkitapp
   • Versione: Corrisponde alla versione del tuo app iOS
   • Costruzione: Corrisponde al numero di costruzione del tuo app iOS

4. Vai a Firma e Capacità tab:

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

5. Imposta Informazioni di distribuzione:

   • Minime distribuzioni: watchOS 9.0 o successivo

Passo 4: Aggiungi CapgoWatchSDK tramite Gestore di Pacchetti Swift

Il CapgoWatchSDK fornisce una classe pronta all'uso WatchConnector per la comunicazione.

1. In Xcode, vai a File → Aggiungi dipendenze di pacchetto…

2. Nella casella di ricerca, inserisci:

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

3. Premi 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 stato aggiunto al tuo monitora il target (ad esempio, “MyWatch”), non l'app di iOS
   • Clicca Aggiungi Pacchetto

Suggerimento

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 del Watch

Ora creiamo l'app del watch 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

La tua app iOS ha anche bisogno della capacità di WatchConnectivity.

1. Nel Navigatore del progetto, seleziona il tuo progetto

2. Seleziona il tuo Sfoglia l'applicazione iOS (non il target dell'orologio)

3. Vai a Segnatura e 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>

Passaggio 7: Costruisci e Esegui

Esegui sul Simulatore

1. Seleziona il tuo schema di orologio dalla selezione dei schemi (in alto nella finestra di Xcode)

2. Scegli un simulatore di orologio:

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

3. Clicca sul Pulsante (▶️) di Esecuzione Premi il pulsante (▶️) di Esecuzione o premi Cmd + R

4. Il simulatore iOS si avvierà con entrambi l'iPhone e l'Apple Watch

Esegui su Dispositivo Fisico

1. Connetti il tuo iPhone tramite USB

2. Assicurati che l'Apple Watch sia accoppiato a quel iPhone

3. Seleziona lo schema del tuo orologio

4. Seleziona il tuo Apple Watch fisico dalla lista dei dispositivi

5. Clicca Esegui

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

Suggerimento

Per debuggare entrambe le app contemporaneamente:

1. Eseguire l'app di iOS per primo
2. Poi eseguire l'app orologio con “Debug → Attaccare al processo” per l'orologio

Passo 8: Testare la comunicazione

Dal iPhone (Capacitor) all'orologio

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

Dal Watch all'Iphone

L'app 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 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 più controllo

Se hai bisogno di più controllo, 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()

Risoluzione dei problemi

L'app non compare sull'orologio

1. Assicurarsi che gli ID dei pacchetti siano correttamente correlati (l'ID del pacchetto dell'app Watch dovrebbe essere l'ID del pacchetto dell'app iOS + .watchkitapp)
2. Verificare che entrambe le app siano firmate con lo stesso team
3. Su dispositivo fisico: Apri l'app Watch sul iPhone → Il mio Watch → scorri per trovare la tua app → attiva ON

Messaggi Non Ricevuti

1. Verificare che entrambe le app abbiano WCSession attivato
2. Controlla isReachable prima di inviare messaggi
3. Per una consegna garantita, utilizza transferUserInfo invece di sendMessage
4. Assicurarsi che gli ascoltatori siano registrati prima che l'altra dispositivo invii messaggi

Errore “Sessione Non Attivata”

1. Chiama 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. Controlla che la capacità WatchConnectivity sia aggiunta al target iOS

Errori di compilazione con CapgoWatchSDK

1. Assicurati di aver aggiunto il pacchetto al target watche non al target iOS
2. Pulisci il cartello di compilazione: Prodotto → Pulisci Cartello di Compilazione (Cmd + Shift + K)
3. Ripristina cache dei pacchetti: File → Pacchetti → Ripristina Cache dei Pacchetti

Problemi del Simulatore

1. Ripristina 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 garantire la comunicazione

Passaggi Successivi

• API Reference - Documentazione completa di API
• Modelli di comunicazione - Utilizzare ogni metodo
• Esempio di App - Esempio di App completo

Continua da Creare un'app watchOS

Se stai utilizzando Creare un'app watchOS per pianificare il lavoro di plugin nativo, connettilo con Utilizzare @capgo/capacitor-watch per la capacità nativa in Utilizzare @capgo/capacitor-watch Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, I plugin Capgo nel Capacitor per il dettaglio di implementazione dei plugin Capgo nel Capacitor, Aggiunta o Aggiornamento dei Plugin per il dettaglio di implementazione in Aggiunta o Aggiornamento dei Plugin, e Alternative per Plugin Enterprise di Ionic per il flusso di lavoro del prodotto in Alternative per Plugin Enterprise di Ionic.