Créer une app watchOS
Copiez un prompt de configuration incluant les étapes d'installation et le guide markdown complet pour ce plugin.
Ce guide vous guide dans la création d'un watchOS application compagnon de zéro, incluant la configuration du projet dans Xcode, l’intégration de CapgoWatchSDK et la création d’une application watch fonctionnelle avec SwiftUI.
Pour Wear OS, utilisez Créer une app Wear OS plutôt.
Prerequisites
Section intitulée « Prérequis »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 iossi 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
Section intitulée « 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-le pour ouvrir le projet)
- Podfile
RépertoireMyWatch/ (nouvelle app watch)
RépertoireMyWatch/ (source de l'app watch)
- MyWatchApp.swift
- ContentView.swift
RépertoireAssets.xcassets/
- …
- MyWatch.xcodeproj
Étape 1 : Ouvrez votre projet iOS dans Xcode
Section intitulée « Étape 1 : Ouvrez votre projet iOS dans Xcode »- Accédez à votre projet Capacitor
ios/Appdossier - Ouvrez
App.xcworkspace(pas.xcodeproj) en double-cliquant dessus - Attendez que Xcode indexe le projet
Étape 2 : ajouter une cible watchOS
Section intitulée « Étape 2 : ajouter une cible watchOS »-
Dans Xcode, allez dans Fichier → Nouveau → Cible…
-
Dans le sélecteur de template :
- Sélectionnez watchOS onglet en haut
- Choisissez cible
- Cliquez Suivant
-
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 app iOS (ex. :
app.capgo) - Identifiant du bundle: Sera généré automatiquement (ex. :
app.capgo.myapp.watchkitapp) - Langue: Swift
- Interface utilisateur: SwiftUI
- Type d'application Watch: App (et non « App for Existing iOS App »)
- Décocher Inclure la scène de notification (sauf si nécessaire)
- Décocher Inclure la complication (sauf si nécessaire)
- Nom du produit:
-
Cliquez Terminer
-
Lorsque le prompt « Activate ‘MyWatch’ scheme? » s’affiche, cliquez Activer
Étape 3 : Configurer les réglages de l'app Watch
Section intitulée « Étape 3 : Configurer les réglages de l'app Watch »-
Dans le Project Navigator (barre latérale gauche), sélectionnez votre projet (l'icône bleue en haut)
-
Sélectionnez votre cible watch (ex : « MyWatch ») dans la liste des cibles
-
Allez sur la Général onglet :
- Nom d'affichage : nom affiché sous l'icône de l'app (ex : « Mon App »)
- Identifiant du bundle : doit se terminer par
.watchkitapp - Version : correspond à la version de votre app iOS
- Build: Correspondre au n° de build de votre app iOS
-
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
-
Définissez Infos de déploiement:
- Déploiements minimum: watchOS 9.0 ou version ultérieure
Étape 4 : Ajouter CapgoWatchSDK via Swift Package Manager
Section intitulée « Étape 4 : Ajouter CapgoWatchSDK via Swift Package Manager »The CapgoWatchSDK provides a ready-to-use WatchConnector classe de communication.
-
Dans Xcode, allez dans Fichier → Ajouter des dépendances de package…
-
Dans le champ de recherche, saisissez :
https://github.com/Cap-go/capacitor-watch.git -
Appuyez sur Entrée et attendez que Xcode récupère le package
-
Configurez le package :
- Règle de dépendance: « Jusqu'à la prochaine version majeure » avec « 8.0.0 »
- Cliquez Ajouter un package
-
Choisissez les produits à ajouter :
- IMPORTANT: Sélectionnez uniquement
CapgoWatchSDK - Assurez-vous qu'il est ajouté à votre cible watch (ex : « MyWatch »), et non à l'app iOS
- Cliquez Ajouter un package
- IMPORTANT: Sélectionnez uniquement
Étape 5 : implémenter l’application Watch
Section intitulée « Étape 5 : implémenter l’application Watch »Créons maintenant l’application watch code. Remplacez les fichiers générés automatiquement par les suivants :
5.1 Créer le point d’entrée de l’application
Section intitulée « 5.1 Créer le point d’entrée de l’application »Modifier MyWatch/MyWatchApp.swift:
import SwiftUIimport CapgoWatchSDK
@mainstruct MyWatchApp: App { init() { // Activate WatchConnectivity when app launches WatchConnector.shared.activate() }
var body: some Scene { WindowGroup { ContentView() } }}5.2 Créer la vue principale
Section intitulée « 5.2 Créer la vue principale »Modifier MyWatch/ContentView.swift:
import SwiftUIimport 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 statusstruct 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
Section intitulée « Étape 6 : Configurer l’app iOS pour WatchConnectivity »Votre app iOS a également besoin de la capacité WatchConnectivity.
-
Sélectionnez votre projet dans le Project Navigator
-
Sélectionnez votre Cible iOS App (et non la cible watch)
-
Accéder à Signature et capacités onglet
-
Cliquez + Capacité
-
Rechercher et ajouter WatchConnectivity (si disponible) ou il peut être ajouté automatiquement
-
Le plugin Capacitor gère le côté 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
Section intitulée « Étape 7 : Compiler et exécuter »Lancer sur le simulateur
Section intitulée « Exécuter sur le simulateur »-
Sélectionnez votre schéma watch depuis le sélecteur de schéma (en haut de la fenêtre Xcode)
-
Choisissez un simulateur watch :
- Cliquez sur le sélecteur d’appareil à côté du schéma
- Sélectionnez un simulateur Apple Watch (par ex. « Apple Watch Series 9 (45 mm) »)
-
Cliquez sur les Exécutez bouton (▶️) ou appuyez sur
Cmd + R -
Le simulateur iOS se lancera avec l’iPhone et l’Apple Watch
Lancer sur un appareil physique
Section intitulée « Exécuter sur un appareil physique »-
Connectez votre iPhone via USB
-
Assurez-vous que votre Apple Watch est appairée avec cet iPhone
-
Sélectionnez le schéma de votre montre
-
Sélectionnez votre Apple Watch physique dans la liste des appareils
-
Cliquez Exécutez
-
First time: You may need to trust your computer on both devices
Étape 8 : Tester la communication
Section intitulée « Étape 8 : Tester la communication »De l'iPhone (Capacitor) vers la Watch
Section intitulée « De l'iPhone (Capacitor) vers la Watch »Dans votre application Capacitor :
import { CapgoWatch } from '@capgo/capacitor-watch';
// Check connectionconst info = await CapgoWatch.getInfo();console.log('Watch reachable:', info.isReachable);
// Send a messageif (info.isReachable) { await CapgoWatch.sendMessage({ data: { action: 'update', value: 'Hello from iPhone!' } });}De la Watch vers l'iPhone
Section intitulée « De la Watch vers l'iPhone »L'application Watch utilise WatchConnector:
// Send message (fire and forget)WatchConnector.shared.sendMessage(["action": "buttonTapped"])
// Send message with replyWatchConnector.shared.sendMessage(["request": "getData"]) { reply in print("Got reply: \(reply)")}Gérer les messages sur l'iPhone
Section intitulée « Gérer les messages sur l'iPhone »// Listen for messages from watchawait CapgoWatch.addListener('messageReceived', (event) => { console.log('Message from watch:', event.message); // { action: 'buttonTapped' }});
// Handle messages that need a replyawait 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é : delegate personnalisé pour plus de contrôle
Section intitulée « Avancé : délégué personnalisé pour plus de contrôle »Si vous avez besoin de plus de contrôle, implémentez WatchConnectorDelegate:
import SwiftUIimport 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 = handlerWatchConnector.shared.activate()Troubleshooting
Section intitulée « Dépannage »L'app Watch n'apparaît pas sur la montre
Section intitulée « L’app Watch n’apparaît pas sur la montre »- Vérifiez 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) - Vérifiez que les deux apps sont signées avec la même équipe
- Sur un appareil physique : ouvrez l’app Watch sur l’iPhone → Ma montre → faites défiler pour trouver votre app → activez
Les messages ne sont pas reçus
Section intitulée « Messages non reçus »- Vérifiez que les deux applications ont activé WCSession
- Vérifier
isReachableavant d’envoyer des messages - Pour une livraison garantie, utilisez
transferUserInfoau lieu desendMessage - Assurez-vous que les listeners sont enregistrés avant que l’autre appareil n’envoie des messages
Erreur « Session Not Activated »
Section intitulée « Erreur “Session Not Activated” »- Appelez
WatchConnector.shared.activate()tôt dans le cycle de vie de l’app - Sur iOS, le plugin s’active automatiquement – assurez-vous qu’il est importé
- Vérifiez que la capacité WatchConnectivity est ajoutée à la cible iOS
Erreurs de build avec CapgoWatchSDK
Section intitulée « Erreurs de build avec CapgoWatchSDK »- Vérifiez que le package est ajouté à cible watch, et non à la cible iOS
- Nettoyer le dossier de build : Produit → Nettoyer le dossier de build (Cmd + Shift + K)
- Réinitialiser les caches de packages : Fichier → Packages → Réinitialiser les caches de packages
Problèmes avec le simulateur
Section intitulée « Problèmes de simulateur »- Réinitialisez les simulateurs : Appareil → Effacer tout le contenu et les réglages
- Assurez-vous que les simulateurs iOS et watchOS sont des paires compatibles
- Les deux simulateurs doivent être lancés pour que la communication fonctionne
Étapes suivantes
Section intitulée « É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 d’exemple - Exemple complet et fonctionnel
Continuer depuis « Créer une application watchOS »
Section intitulée « Continuer depuis Créer une application 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.