Créer une application watchOS

Ce guide vous accompagne dans la création d'une watchOS watchOS de zéro, incluant la configuration du projet dans Xcode, l'intégration du CapgoWatchSDK et le build d'une application fonctionnelle avec SwiftUI.

Pour Wear OS, utilisez Créer une app Wear OS plutôt.

Prerequisites

Avant de commencer, assurez-vous d'avoir :

• Xcode 15 ou une version ultérieure (à télécharger sur le Mac App Store)
• macOS Sonoma ou version ultérieure (pour la dernière version de watchOS SDK)
• Un projet iOS Capacitor existant (exécutez npx cap add ios si ce n’est pas déjà fait)
• Compte Apple Developer (un compte gratuit suffit pour le développement)

Aperçu de la structure du projet

Une fois ce guide terminé, votre projet aura cette structure :

• Répertoireios/

  • RépertoireApp/

    • RépertoireApp/ (votre application iOS principale)

      • …
    • App.xcodeproj
    • App.xcworkspace (utilisez ceci pour ouvrir le projet)
    • Podfile
  • RépertoireMyWatch/ (nouvelle watch app)

    • RépertoireMyWatch/ (source de la watch app)

      • MyWatchApp.swift
      • ContentView.swift
      • RépertoireAssets.xcassets/

        • …
    • MyWatch.xcodeproj

Étape 1 : Ouvrez votre projet iOS dans Xcode

1. Accédez au projet Capacitor ios/App dossier
2. Ouvrez App.xcworkspace (pas .xcodeproj) en double-cliquant dessus
3. Attendez que Xcode indexe le projet

Attention

Ouvrez toujours le .xcworkspace fichier, et non .xcodeproj. L'espace de travail inclut les dépendances CocoaPods nécessaires à votre projet.

Étape 2 : ajouter une cible watchOS

1. Dans Xcode, allez dans Fichier → Nouveau → Cible…

2. Dans le sélecteur de template :

   • Sélectionnez watchOS onglet en haut
   • Choisissez cible
   • Cliquez Suivant

3. Configurez votre application watch :

   • Nom du produit: MyWatch (ou le nom de votre choix)
   • Équipe: Sélectionnez votre équipe Apple Developer
   • Identifiant d'organisation: Doit correspondre à votre application iOS (ex : app.capgo)
   • Identifiant de bundle: Sera généré automatiquement (ex : app.capgo.myapp.watchkitapp)
   • Langue: Swift
   • Interface utilisateur: SwiftUI
   • Type d'application Watch: App (pas App pour une application iOS existante)
   • Décocher Inclure Notification Scene (sauf si vous en avez besoin)
   • Décocher Inclure Complication (sauf si vous en avez besoin)

4. Cliquez Terminer

5. Lorsqu'on vous demande « Activate ‘MyWatch’ scheme? », cliquez sur Activate

Step 3: Configure Watch App Settings

1. Dans le Project Navigator (barre latérale gauche), sélectionnez votre projet (l'icône bleue en haut)

2. Sélectionnez votre cible watch (ex : « MyWatch ») dans la liste des targets

3. Accéder au General :

   • Nom d'affichage: Le nom affiché sous l'icône de l'app (ex : « My App »)
   • Identifiant de bundle: Doit se terminer par .watchkitapp
   • Version: Faites correspondre la version de votre app iOS
   • Build: Match your iOS app build number

4. Accéder à Signature et capacités onglet :

   • Activer Gérer automatiquement la signature
   • Sélectionnez votre Équipe
   • Xcode créera automatiquement les profils de provisionnement

5. Définissez Infos de déploiement:

   • Déploiements minimums: watchOS 9.0 ou plus récent

Étape 4 : Ajouter CapgoWatchSDK via Swift Package Manager

Le CapgoWatchSDK fournit un outil prêt à l'emploi WatchConnector classe pour la communication.

1. Dans Xcode, allez dans Fichier → Ajouter des dépendances de package…

2. Dans le champ de recherche, saisissez :

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

3. Appuyez sur Entrée et attendez que Xcode récupère le package

4. Configurez le package :

   • Règle de dépendance: « Jusqu'à la prochaine version majeure » avec « 8.0.0 »
   • Cliquez Ajouter un package

5. Choisissez les produits à ajouter :

   • IMPORTANT: Sélectionnez uniquement CapgoWatchSDK
   • Assurez-vous qu'il est ajouté à votre cible watch (ex : « MyWatch »), pas à l'app iOS
   • Cliquez Ajouter un package

Astuce

Le CapgoWatchSDK est spécifiquement conçu pour les apps watchOS. Il fournit WatchConnector, un ObservableObject qui gère toute la complexité de WatchConnectivity pour vous.

Étape 5 : Implémenter l'app Watch

Créons maintenant l'app Watch code. Remplacez les fichiers auto-générés par les suivants :

5.1 Créer le point d'entrée de l'app

Modifier 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 Créer la vue principale

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

Étape 6 : Configurer l'app iOS pour WatchConnectivity

Votre app iOS nécessite également la capacité WatchConnectivity.

1. Dans le Project Navigator, sélectionnez votre projet

2. Sélectionnez votre Cible de l'app iOS (pas la cible watch)

3. Accéder à Signature et capacités onglet

4. Cliquez + Capability

5. Rechercher et ajouter WatchConnectivity (si disponible) ou peut être ajouté automatiquement

6. Le plugin Capacitor gère la partie iOS automatiquement, mais assurez-vous que votre Info.plist contient :

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

Étape 7 : Build et exécution

Lancer sur le simulateur

1. Sélectionnez votre scheme watch dans le sélecteur de scheme (en haut de la fenêtre Xcode)

2. Choisissez un simulateur Apple Watch :

   • Cliquez sur le sélecteur d'appareil à côté du scheme
   • Sélectionnez un simulateur Apple Watch (ex : « Apple Watch Series 9 (45mm) »)

3. Cliquez sur les Exécutez bouton (▶️) ou appuyez sur Cmd + R

4. Le simulateur iOS se lancera avec l'iPhone et l'Apple Watch

Exécuter sur un appareil physique

1. Connectez votre iPhone via USB

2. Assurez-vous que votre Apple Watch est jumelée à cet iPhone

3. Sélectionnez votre scheme de watch

4. Sélectionnez votre Apple Watch physique dans la liste des appareils

5. Cliquez Exécutez

6. First time: You may need to trust your computer on both devices

Astuce

Pour déboguer les deux apps simultanément :

1. Lancez d'abord l'app iOS
2. Lancez ensuite l'app watch avec « Debug → Attach to Process » pour la watch

Étape 8 : Tester la communication

De l'iPhone (Capacitor) vers la Watch

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

De la Watch vers l'iPhone

L'application Watch utilise 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)")
}

Gérer les messages sur l'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'] }
  });
});

Avancé : délégué personnalisé pour plus de contrôle

Si vous avez besoin de plus de contrôle, implémentez 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'application Watch n'apparaît pas sur la montre

1. Assurez-vous que les bundle IDs sont correctement liés (le bundle ID de l'app Watch doit être le bundle ID de l'app iOS + .watchkitapp)
2. Vérifiez que les deux apps sont signées avec la même équipe
3. Sur un appareil physique : ouvrez l'app Watch sur l'iPhone → Ma montre → faites défiler pour trouver votre app → activez l'interrupteur

Les messages ne sont pas reçus

1. Vérifiez que les deux apps ont activé WCSession
2. Vérifier isReachable avant d'envoyer des messages
3. Pour une livraison garantie, utilisez transferUserInfo au lieu de sendMessage
4. Assurez-vous que les listeners sont enregistrés avant que l'autre appareil n'envoie des messages

Erreur « Session Not Activated »

1. Appelez WatchConnector.shared.activate() tôt dans le cycle de vie de l'app
2. Sur iOS, le plugin s'active automatiquement — assurez-vous que le plugin est importé
3. Vérifiez que la capacité WatchConnectivity est ajoutée à la cible iOS

Erreurs de build avec CapgoWatchSDK

1. Assurez-vous que le package est ajouté à la cible watch, et non à la cible iOS
2. Nettoyer le dossier de build : Produit → Nettoyer le dossier de build (Cmd + Shift + K)
3. Réinitialiser les caches de packages : Fichier → Packages → Reset Package Caches

Problèmes de simulateur

1. Réinitialisez les simulateurs : Appareil → Effacer tout le contenu et les réglages
2. Assurez-vous que les simulateurs iOS et watchOS sont des paires compatibles
3. Les deux simulateurs doivent être lancés pour que la communication fonctionne

Étapes suivantes

• Créer une app Wear OS pour les montres Android
• Référence API - Consultez la documentation API
• Patterns de communication - Quand utiliser chaque méthode
• App exemple - Exemple complet et fonctionnel

Continuer après Créer une app watchOS

Si vous utilisez Créer une app watchOS pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-watch pour la fonctionnalité native dans « Utiliser @capgo/capacitor-watch », Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.