Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-watch` plugin in my project.

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

1. Installer le package

   bun add @capgo/capacitor-watch

2. Synchroniser avec les projets natifs

   bunx cap sync

3. Configurer le plugin

   Exemple d'utilisation de base :

   import { CapgoWatch } from '@capgo/capacitor-watch';
   
   // Check watch connectivity status
   const info = await CapgoWatch.getInfo();
   console.log('Watch paired:', info.isPaired);
   console.log('Watch reachable:', info.isReachable);
   
   // Listen for messages from watch
   await CapgoWatch.addListener('messageReceived', (event) => {
     console.log('Message from watch:', event.message);
   });

   Envoyer un message à la Watch :

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOS

   Configuration iOS requise :

   1. Ajoutez la capacité WatchConnectivity à votre application iOS dans Xcode
   2. Créez une cible d'application watchOS dans votre projet Xcode
   3. Implémentez WatchConnectivity dans votre application watchOS (voir l'implémentation de l'app Watch ci-dessous)

   Le plugin active automatiquement la WCSession lors de son chargement.

   Android

   Configuration requise pour Wear OS :

   1. Ajoutez une Module Wear OS à votre projet Android (même applicationId signature que l'application téléphone).
   2. Déclarez la capgo_watch capability dans le module wear (voir Créer une app Wear OS).
   3. Implémentez les écouteurs Data Layer sur la montre via les chemins du plugin (/capgo/message, /capgo/context, et autres).

   Le plugin téléphone enregistre des écouteurs API Wearable lors du chargement. Utilisez getInfo() pour vérifier les nœuds connectés et si l'application montre est détectée.

   Étapes complètes : Créer une app Wear OS.

4. Gérer les messages nécessitant une réponse

   // Listen for messages that need a response
   await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
     console.log('Request from watch:', event.message);
   
     // Process the request
     const result = await processWatchRequest(event.message);
   
     // Send reply back to watch (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         result,
       },
     });
   });

5. Synchroniser l'état de l'application

   // Update application context (latest value only)
   await CapgoWatch.updateApplicationContext({
     context: {
       theme: 'dark',
       userId: '123',
       lastSync: Date.now()
     }
   });
   
   // Listen for context updates from watch
   await CapgoWatch.addListener('applicationContextReceived', (event) => {
     console.log('Context from watch:', event.context);
   });

6. Transférer les infos utilisateur de façon fiable

   // Queue data for reliable delivery (even when watch is offline)
   await CapgoWatch.transferUserInfo({
     userInfo: {
       recordId: '456',
       action: 'created',
       data: { name: 'Item 1' }
     }
   });
   
   // Listen for user info transfers
   await CapgoWatch.addListener('userInfoReceived', (event) => {
     console.log('User info from watch:', event.userInfo);
   });

7. Surveiller la connectivité

   // Track reachability changes
   await CapgoWatch.addListener('reachabilityChanged', (event) => {
     console.log('Watch reachable:', event.isReachable);
     if (event.isReachable) {
       // Watch is now available for interactive messaging
     }
   });
   
   // Track session activation state
   await CapgoWatch.addListener('activationStateChanged', (event) => {
     // 0 = notActivated, 1 = inactive, 2 = activated
     console.log('Session state:', event.state);
   });

Démarrage rapide

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

Exemple : updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

Exemple : transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

Erreurs courantes

• Écouteurs: supprimez les handles lors du démontage des écrans.
• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Implémentation de l'app Watch

Votre app watchOS doit implémenter WatchConnectivity. Voici un exemple en SwiftUI :

import SwiftUI
import WatchConnectivity

@main
struct MyWatchApp: App {
    init() {
        WatchViewModel.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class WatchViewModel: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WatchViewModel()

    @Published var lastMessage: [String: Any] = [:]

    func activate() {
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    // Send message to iPhone
    func sendToPhone(_ data: [String: Any]) {
        guard WCSession.default.isReachable else {
            print("iPhone not reachable")
            return
        }
        WCSession.default.sendMessage(data, replyHandler: nil)
    }

    // Send message with reply
    func sendToPhoneWithReply(_ data: [String: Any], completion: @escaping ([String: Any]) -> Void) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(data, replyHandler: completion)
    }

    // Receive message from iPhone
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = message
        }
    }

    // Receive application context
    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = applicationContext
        }
    }

    // Required delegate methods
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        print("Watch session activated: \(activationState.rawValue)")
    }
}

Référence API

Méthodes

sendMessage(options: SendMessageOptions)

Envoie un message interactif à la montre. La montre doit être joignable.

Paramètres :

• data: Objet - Les données à envoyer à la montre

updateApplicationContext(options: UpdateContextOptions)

Met à jour le contexte de l'application. Seule la dernière valeur est conservée.

Paramètres :

• context: Objet - Les données de contexte à synchroniser

transferUserInfo(options: TransferUserInfoOptions)

Queue user info for reliable delivery.

Paramètres :

• userInfo: Objet - Les infos utilisateur à transférer

replyToMessage(options: ReplyMessageOptions)

Répondre à un message qui a sollicité une réponse.

Paramètres :

• callbackId: string - L'ID de callback de l'événement messageReceivedWithReply
• data: Objet - Les données de la réponse

getInfo()

Obtenir le statut de connectivité de la montre.

Retourne : WatchInfo objet avec :

• isSupported: booléen - Indique si les API watch sont disponibles sur cette plateforme
• isPaired: booléen - Apple Watch jumelée (iOS) ou au moins un nœud Wear OS connecté (Android)
• isWatchAppInstalled: booléen - Application compagnon installée (iOS) ou capgo_watch capacité détectée (Android)
• isReachable: booléen - Indique si la montre est joignable pour une messagerie immédiate
• activationState: nombre - État de la session (iOS WCSession ; Android 2 si un nœud est connecté, 0 sinon)

getPluginVersion()

Récupérer la version du plugin natif.

Événements

Événement	Description
messageReceived	Message simple de la montre
messageReceivedWithReply	Message en attente de réponse (inclut le callbackId)
applicationContextReceived	Mise à jour du contexte depuis watch
userInfoReceived	Transfert d'infos utilisateur depuis la montre
reachabilityChanged	Changement de connectivité de la Watch (iOS uniquement)
activationStateChanged	Changement d'état d'activation de la session (iOS uniquement)

Patterns de communication

Messagerie immédiate (sendMessage)

• Nécessite que la montre soit joignable
• Idéal pour les communications interactives et urgentes
• Échoue immédiatement si watch n'est pas disponible

Contexte de l'application (updateApplicationContext)

• Uniquement la dernière valeur - les précédentes sont écrasées
• Idéal pour synchroniser l'état actuel de l'app
• Livré dès que watch devient disponible

Transfert d'infos utilisateur (transferUserInfo)

• Mis en file d'attente et livré dans l'ordre
• Idéal pour les données critiques devant être livrées
• Fonctionne même si watch est temporairement injoignable

Notes de plateforme

Consultez le tableau de compatibilité des plateformes sur l'aperçu du plugin pour une matrice méthode par méthode.

iOS (Apple Watch)

• Nécessite iOS 15.0 ou une version ultérieure
• Utilise le framework WatchConnectivity
• La session s'active automatiquement au chargement du plugin
• Supports background delivery for context and user info
• Émet reachabilityChanged et activationStateChanged

Android (Wear OS)

• Nécessite les services Google Play avec Wear OS Data Layer (play-services-wearable, inclus avec le plugin)
• Phone and wear APKs must share the même applicationId et clé de signature
• L'application de la montre doit déclarer sa capacité capgo_watch
• Émet pas émet reachabilityChanged ou activationStateChanged; poll getInfo() si nécessaire
• Guide d'installation : Créer une app Wear OS

Le Web

• Le watch messaging n'est pas supporté dans le navigateur
• getInfo() se résout avec isSupported: false and other fields at safe defaults
• getPluginVersion() se résout avec { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, et replyToMessage rejeter avec une erreur d'indisponibilité
• addListener résout un handle via Capacitor WebPlugin, mais les événements watch ne sont pas supportés dans le navigateur (les callbacks ne s'exécutent jamais)

Cas d'usage courants

1. Data Sync: Keep watch and phone data in sync
2. Contrôl’à distance: Control phone features from watch
3. Notifications: Envoyez des notifications personnalisées à la montre
4. Données de santé: Partagez vos données de santé et de fitness
5. Contrôle média: Contrôlez la lecture musicale depuis la montre
6. Domotique: Contrôlez vos appareils depuis votre poignet

Troubleshooting

Montre injoignable :

• Assurez-vous que la montre est à portée Bluetooth
• Vérifiez que les deux applications sont lancées
• Vérifiez que WCSession est activée des deux côtés

Messages non reçus :

• Vérifiez que les listeners sont enregistrés avant l'envoi
• Vérifiez que l'app Watch implémente WCSessionDelegate
• Utiliser transferUserInfo pour une livraison garantie

La session ne s'active pas :

• Assurez-vous que la capacité WatchConnectivity est ajoutée dans Xcode
• Vérifiez que l'app Watch possède le bundle ID compagnon
• Vérifiez que les deux apps ciblent des versions d'OS compatibles

Continuer depuis Getting Started

Si vous utilisez Prise en main 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.