Créer une application watchOS

Ce guide vous guide à travers la création d'une application de montre watchOS à partir de zéro, y compris la configuration du projet dans Xcode, l'intégration du CapgoWatchSDK et la création d'une application de montre fonctionnelle avec SwiftUI.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Xcode 15 ou ultérieur (télécharger depuis l'App Store Mac)
• macOS Sonoma ou ultérieur (pour le dernier watchOS SDK)
• Un projet iOS existant Capacitor (exécuter npx cap add ios si vous n'avez pas encore)
• compte Apple Developer (un compte gratuit fonctionne pour le développement)

Vue d'ensemble de la structure du projet

Après avoir terminé ce guide, votre projet aura cette structure :

• Répertoireios/

  • RépertoireApp/

    • RépertoireApp/ (votre application iOS principale)

      • …
    • App.xcodeproj
    • App.xcworkspace (utilisez cela pour ouvrir le projet)
    • Podfile
  • RépertoireMyWatch/ (nouvelle application horlogère)

    • RépertoireMyWatch/ (source de l'application horlogère)

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

        • …
    • MyWatch.xcodeproj

Étape 1 : Ouvrez votre projet iOS dans Xcode

1. Naviguez jusqu'à votre projet Capacitor ios/App dossier
2. Ouvrir App.xcworkspace pas .xcodeprojpar double-cliquez dessus
3. Attendez que Xcode indexe le projet

Attention

Ouvrez toujours le .xcworkspace fichier, et non .xcodeprojLe workspace inclut les dépendances CocoaPods dont votre projet a besoin.

Étape 2 : Ajoutez un cible watchOS

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

2. Dans le choix de modèle :

   • Sélectionnez watchOS barre de navigation en haut
   • Choisissez Application
   • Cliquez Suivant

3. Configurez votre application pour montre :

   • Nom du produit: MyWatch (ou votre nom préféré)
   • Équipe Sélectionnez votre équipe de développeurs Apple
   • Identifiant de l'organisation : Doit correspondre à votre application iOS (par exemple, app.capgo)
   • Identifiant de Bundle: sera généré automatiquement (par exemple, app.capgo.myapp.watchkitapp)
   • Langue: sera généré automatiquement (par exemple,
   • Interface utilisateur: SwiftUI
   • Type d'application Watch: Application (pas Application pour Application iOS existante)
   • Désactiver Inclure la scène de notification (sauf si vous en avez besoin)
   • Désactiver Inclure Complication sauf si vous en avez besoin

4. Cliquez Terminer

5. Lorsque vous êtes invité à « Activer le schéma ‘Ma montre’ ? », cliquez Activer

Étape 3 : Configurer les paramètres de l'application horlogère

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

2. Sélectionnez votre cible horlogère (par exemple, « Ma montre ») de la liste des cibles

3. Allez dans le Général tab:

   • Nom d'affichageLe nom affiché sous l'icône de l'application (par exemple, « Mon application »)
   • Identifiant de l'applicationDoit se terminer par .watchkitapp
   • VersionCorrespond à la version de votre application iOS
   • BuildCorrespond à votre numéro de version de build iOS

4. Accédez à Configuration et capacités de signature tab:

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

5. Définir Informations de déploiement:

   • Déploiements minimumsÉtape 4 : Ajouter CapgoWatchSDK via Gestionnaire de packages Swift

Étape 4 : Ajouter CapgoWatchSDK via Gestionnaire de packages Swift

Équipe WatchConnector classe pour la communication.

1. Dans Xcode, allez à 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 de montre (par exemple, « Ma montre »), et non l'application iOS
   • Cliquez Ajouter le package

Conseil

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

Étape 5 : Mettre en œuvre l'application de montre

Créons maintenant l'application de montre code. Remplacez les fichiers générés automatiquement par les éléments suivants :

5.1 Créer l'entrée de l'application

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'application iOS pour WatchConnectivity

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

1. Dans le navigateur de projet, sélectionnez votre projet

2. Sélectionnez votre cible d'application iOS (pas la cible de montre)

3. Allez à Signature et capacités Onglet

4. Cliquez sur Ajouter une capacité

5. Recherchez et ajoutez WatchConnectivity ou il peut être ajouté automatiquement si disponible

6. Le plugin Capacitor gère automatiquement le côté iOS, mais assurez-vous que votre fichier Info.plist contient :

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

Étape 7 : Construire et exécuter

Exécuter sur le simulateur

1. Sélectionnez votre schéma d'horloge dans le sélecteur de schéma (haut de la fenêtre Xcode)

2. Choisissez un simulateur d'horloge :

   • Cliquez sur le sélecteur de périphérique situé à côté du schéma
   • Sélectionnez un simulateur d'Apple Watch (par exemple, « Apple Watch Series 9 (45mm) »)

3. Cliquez sur le bouton Exécuter ou appuyez sur Cmd + R

4. Le simulateur iOS lancera avec les deux iPhone et Apple Watch

Exécuter sur appareil physique

1. Connectez votre iPhone via USB

2. Vérifiez que votre Apple Watch est pairé avec cet iPhone

3. Sélectionnez votre schéma d'horloge

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

5. Cliquez Exécuter

6. Première fois : vous devrez peut-être faire confiance à votre ordinateur sur les deux appareils

Conseil

Pour déboguer les deux applications simultanément :

1. Exécutez l'application iOS en premier
2. Ensuite, exécutez l'application montre avec « Déboguer → Attacher au processus » pour la montre

Étape 8 : Tester la communication

De l'iPhone (Capacitor) à la montre

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 l'horloge à l'iPhone

L'application horloge 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()

Résolution de problèmes

L'application Watch ne s'affiche pas sur la montre

1. Assurez-vous que les identifiants de bundle sont correctement liés (l'identifiant de bundle de l'application Watch doit être l'identifiant de bundle de l'application iOS + .watchkitapp)
2. Vérifiez que les deux applications sont signées avec le même équipe
3. Sur appareil physique : Ouvrez l'application Watch sur l'iPhone → Mon Watch → défilez pour trouver votre application → activez ON

Les messages ne sont pas reçus

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

Erreur de session non activée

1. Appeler WatchConnector.shared.activate() context : fragment de texte HTML d'une chaîne de Capgo UI plus longue (clé parente `appflow_migration_step2`). Page/zone : Comparaison et migration d'Appflow / marketing de copie. Rôle : Phrase de copie du site web. Voir dans : page ionic-appflow.astro. Conservez les termes de produit/marque et les termes de développeur exactement. Clé de message `appflow_migration_step2` (Étape 2 de la migration d'Appflow).
2. tôt dans le cycle de vie de l'application
3. Sur iOS, le plugin s'active automatiquement - assurez-vous que le plugin est importé

Vérifiez que la capacité WatchConnectivity est ajoutée à la cible iOS

1. Sous-titre « Erreurs de construction avec CapgoWatchSDK » Assurez-vous que le package est ajouté à la cible de l'horloge, pas cible iOS
2. Nettoyer le dossier de build : Produit → Nettoyer le dossier de build (Cmd + Maj + K)
3. Réinitialiser les caches de packages : Fichier → Packages → Réinitialiser les caches de packages

Problèmes de simulateur

1. Réinitialiser les simulateurs : Appareil → Effacer tout contenu et paramètres
2. S'assurer que les simulateurs iOS et watchOS sont des paires compatibles
3. Les deux simulateurs doivent être en cours d'exécution pour que la communication fonctionne

Étapes suivantes

• API Reference - Documentation complète de API
• Modèles de communication - Utilisation de chaque méthode
• Exemple d'application - Exemple d'application fonctionnel

Continuez de la section « Création d'une application watchOS »

Si vous utilisez Création d'une application watchOS pour planifier le travail de plugin natif, connectez-l’à En utilisant @capgo/capacitor-watch pour la capacité native dans En utilisant @capgo/capacitor-watch, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, Plugins Capacitor par Capgo pour le détail d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou Mettre à jour les plugins pour le détail d'implémentation dans Ajouter ou Mettre à jour les plugins, et Alternatives de plugins Ionic Enterprise pour le flux de travail du produit dans Alternatives de plugins Ionic Enterprise.