Démarrage

1. Installez le package

   bun add @capgo/capacitor-watch

2. Synchronisez avec les projets natifs

   bunx cap sync

3. Configurez le plugin

   Exemple de base d'utilisation :

   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 à 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 requise iOS :

   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'application Watch ci-dessous)

   Le plugin active automatiquement la session WC lorsque le plugin charge.

   Android

   L'Apple Watch n'est pris en charge que sur iOS. Sur Android, toutes les méthodes rejettent avec l'erreur « L'Apple Watch n'est pris en charge que sur iOS ». getInfo() La méthode renvoie isSupported: false.

4. Gérer les messages qui nécessitent 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
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { 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 informations d'utilisateur de manière 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);
   });

Implémenter l'application Watch

Votre application watchOS doit implémenter WatchConnectivity. Voici un exemple 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)")
    }
}

API Référence

Méthodes

sendMessage(options: SendMessageOptions)

Envoyer un message interactif à l'horloge. Exige que l'horloge soit accessible.

Paramètres :

• data : Objet - Les données à envoyer à l'horloge

updateApplicationContext(options: UpdateContextOptions)

Mettre à jour le contexte de l'application. Seule la valeur la plus récente est conservée.

Paramètres :

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

transferUserInfo(options: TransferUserInfoOptions)

Enfile les informations de l'utilisateur pour une livraison fiable.

Paramètres :

• userInfo: Objet - Les informations de l'utilisateur à transférer

replyToMessage(options: ReplyMessageOptions)

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

Paramètres :

• callbackId: chaîne de caractères - L'ID de rappel du messageReceivedWithReply
• data: Objet - Les données de réponse

getInfo()

Obtenir l'état de connectivité de l'horloge.

Retourne : WatchInfo objet avec :

• isSupported : boolean - Le WatchConnectivity est disponible
• isPaired : boolean - Un montre est pairé
• isWatchAppInstalled : boolean - L'application de montre est installée
• isReachable : boolean - La montre est accessible
• activationState : nombre - État de session (0/1/2)

getPluginVersion()

Obtenez la version native du plugin.

Événements

Événement	Description
messageReceived	Message simple du montreur
messageReceivedWithReply	Message attendant une réponse (inclut callbackId)
applicationContextReceived	Mise à jour de contexte du montreur
userInfoReceived	Transfert d'informations de l'utilisateur du montreur
reachabilityChanged	État de connectivité du montreur modifié
activationStateChanged	État d'activation de la session modifié

Modèles de communication

Message instantané (sendMessage)

• Exige que le montreur soit accessible
• Meilleur pour la communication interactive et sensible à l'heure
• Échoue immédiatement si la surveillance n'est pas disponible

Contexte d'application (updateApplicationContext)

• Seulement la dernière valeur - les valeurs précédentes sont effacées
• Meilleur pour la synchronisation de l'état actuel de l'application
• Livré lorsque la surveillance devient disponible

Transfert d'informations de l'utilisateur (transferUserInfo)

• En file d'attente et livré dans l'ordre
• Meilleur pour les données importantes qui doivent être livrées
• Fonctionne même lorsque la surveillance est temporairement inatteignable

Notes de plateforme

iOS

• Exige iOS 15.0 ou ultérieur
• Utilise le framework WatchConnectivity
• La session s'active automatiquement lors du chargement du plugin
• Supporte la livraison en arrière-plan pour le contexte et les informations utilisateur

Android

• Non pris en charge (l'Apple Watch est uniquement disponible sous iOS)
• Toutes les méthodes rejettent avec un erreur appropriée
• getInfo() returns isSupported: false

Web

• Non pris en charge
• Toutes les méthodes rejettent avec une erreur indisponible
• getInfo() renvoie isSupported: false

Utilisations courantes

1. Synchronisation de donnéesGardez à l'œil et synchronisez les données de téléphone et montre
2. Contrôle à distanceContrôlez les fonctionnalités de téléphone depuis votre montre
3. Notifications: Envoie des notifications personnalisées à l'horloge
4. État de santé: Partage des métriques de fitness et de santé
5. Contrôle de médias: Contrôle de la lecture de musique depuis l'horloge
6. Smart Home: Contrôle des appareils depuis votre poignet

Dépannage

L'horloge n'est pas accessible :

• Assurez-vous que l'horloge est dans la zone de couverture Bluetooth
• Vérifiez que les deux applications sont en cours d'exécution
• Vérifiez que WCSession est activé des deux côtés

Messages non reçus :

• Vérifiez que les écouteurs sont enregistrés avant d'envoyer
• Vérifiez que l'application montre l'horloge implémente WCSessionDelegate
• Utilisez 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'application montre l'horloge a l'ID de bundle de l'application de compagnon
• Vérifiez que les deux applications ciblent des versions OS compatibles