Creare un'app watchOS

Questa guida ti guida attraverso la 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 watch funzionale con SwiftUI.

Requisiti preliminari

Prima di iniziare, assicurati di avere:

• Xcode 15 o successivo (scarica dal Mac App Store)
• macOS Sonoma o successivo (per il watchOS più recente SDK)
• Un progetto iOS esistente Capacitor (esegui npx cap add ios se non hai fatto così)
• account di sviluppatore Apple 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/ (la tua app iOS principale)

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

    • DirectoryMyWatch/ (fonte 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 .xcodeprojdoppiamente cliccando su di esso
3. Aspetta che Xcode indichi il progetto

Attenzione

Apri sempre il .xcworkspace file, non .xcodeproj. Il workspace include le dipendenze di 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 template:

   • Scegli watchOS tab in alto
   • Scegli App
   • Clicca Avanti

3. Configura la tua app per orologio:

   • Nome del prodotto: MyWatch (o il nome che preferisci)
   • Team: Seleziona il tuo team di sviluppatore 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 la scena di notifica (a meno che non ne abbia bisogno)
   • Disabilita Includi Complicazione (se non ne hai bisogno)

4. Clicca Concludi

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

Passo 3: Configura Impostazioni dell'App dell'Orologio

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

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

3. Vai al Generale tab:

   • Nome a schermoNome a schermo: Il nome visualizzato sotto l'icona dell'applicazione (ad esempio, "Mia App")
   • Identificatore BundleIdentificatore Bundle: Deve concludersi con .watchkitapp
   • VersioneVersione: Corrispondi alla versione del tuo app iOS
   • CostruzioneCostruzione: Corrispondi al numero di costruzione del tuo app iOS

4. Vai a Firma e Capacità tab:

   • Abilita Gestisci automaticamente la firma
   • Seleziona il tuo Team
   • context:Pagina/Area: Sito web di marketing Capgo. Ruolo: Etichetta breve UI o elemento di navigazione. Visualizzato in: pagina sla.astro. Chiave messaggio `team_plan` (Piano di squadra).

5. L'Xcode creerà i profili di provisioning automaticamente Imposta:

   • Informazioni di distribuzioneMinimi di distribuzione

: watchOS 9.0 o successivo

Sezione intitolata “Passo 4: Aggiungi CapgoWatchSDK tramite Gestore dei pacchetti Swift” WatchConnector classe per la comunicazione.

1. In Xcode, vai a File → Aggiungi Dipendenze del Pacchetto…

2. In campo di ricerca, digita:

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

3. Tieni premuto 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 i prodotti da aggiungere:

   • IMPORTANTE: Scegli solo CapgoWatchSDK
   • Assicurati che sia aggiunto al tuo (ad esempio, “MyWatch”), non all'app iOS Clicca
   • Aggiungi Pacchetto Consiglio

Questo

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

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

L'App iOS ha bisogno anche della capacità di WatchConnectivity.

1. Scegli il tuo progetto nel Navigatore dei progetti

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

3. Vai a Autenticazione e Capacità tab

4. Clicca + Capacità

5. Cerca e aggiungi WatchConnectivity (se disponibile) oppure 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>

Passo 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 di dispositivo accanto al schema
   • Seleziona un simulatore Apple Watch (ad esempio “Apple Watch Series 9 (45mm)”)

3. Clicca sul Esegui tasto (▶️) o premi Cmd + R

4. L'iPhone 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 sincronizzato con quell'iPhone

3. Seleziona il tuo schema di watch

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

5. Clicca Esegui

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

Consiglio

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

Nell'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'applicazione 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 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()

Risoluzione dei problemi

L'App non compare sull'orologio

1. Assicurati che gli ID bundle siano correttamente correlati (l'ID bundle dell'app per orologio dovrebbe essere l'ID bundle dell'app iOS + .watchkitapp)
2. Verifica che entrambe le app siano firmate con lo stesso team
3. Sullo strumento fisico: Apri l'app per orologio sul tuo iPhone → Il mio orologio → scorri per trovare la tua app → attiva ON

I messaggi non vengono ricevuti

1. Verifica che entrambe le app abbiano attivato WCSession
2. Controlla isReachable prima di inviare i 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

Errore di "Sessione non attivata"

1. Chiamare WatchConnector.shared.activate() contexto: "Passo 2 di migrazione di Appflow"
2. Pagina/Area: Appflow - confronto e migrazione (copertina marketing). Ruolo: Testo del sito web. Visualizzato in: pagina ionic-appflow.astro. Preservare i termini di prodotto e marchio Capgo e i termini tecnici esattamente. Chiave di messaggio `appflow_migration_step2` (Passo 2 di migrazione di Appflow).
3. all'inizio del ciclo di vita dell'app

Sul iOS, il plugin si attiva automaticamente - assicurati di aver importato il plugin

1. Errori di compilazione con CapgoWatchSDK Sottosezione intitolata "Errori di compilazione con CapgoWatchSDK"Non iOS target
2. Pulisci cartella di build: Prodotto → Pulisci Cartella di Build (Cmd + Shift + K)
3. Ripristina cache dei pacchetti: File → Pacchetti → Ripristina Cache dei Pacchetti

Issue 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 consentire la comunicazione

Passaggi successivi

• API Reference - Documentazione completa di API
• Modelli di comunicazione - Quando utilizzare ogni metodo
• Esempio di App - Esempio di app funzionante

Continua da Creazione di un'app watchOS

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