Prise en main

Prêt à coller

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

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

Utilisez ensuite la prompt suivante :

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 la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la 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 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 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'application Watch ci-dessous)

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

   Android

   Configuration Wear OS requise :

   1. Ajoutez un Module Wear OS à votre projet Android (même applicationId et signature que l'application téléphone).
   2. Déclarez la capgo_watch capacité dans le module Wear OS (voir Créer une application Wear OS).
   3. Implémentez les écouteurs du niveau de données sur l'horloge à l'aide des chemins du plugin./capgo/message, /capgo/contextet autres).

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

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

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 (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 informations 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émentation de l'application Watch

Votre application watchOS doit mettre en œuvre 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)

Update application context. Only latest value is kept.

Paramètres :

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

transferUserInfo(options: TransferUserInfoOptions)

Queue user info for reliable delivery.

Paramètres :

• userInfo: Object - The user info to transfer

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 événement
• data : Objet - Les données de réponse

getInfo()

Obtenir l'état de connectivité de la montre.

Renvoies : WatchInfo objet avec :

• isSupported: boolean - Les APIs de montre sont-elles disponibles sur cette plateforme
• isPaired: boolean - Montre Apple pairée (iOS) ou au moins un nœud Wear OS connecté (Android)
• isWatchAppInstalled: boolean - Application de montre de compagnie installée (iOS) ou capgo_watch : boolean - Capacité détectée (Android)
• isReachable: boolean - La montre est-elle accessible pour un échange instantané de messages
• activationState: nombre - État de session (iOS WCSession; Android 2 lorsqu'un nœud est connecté, 0 sinon)

getPluginVersion()

Récupérer la version native du plugin

Événements

Événement	Description
messageReceived	Message simple du montre
messageReceivedWithReply	Message attend une réponse (inclut callbackId)
applicationContextReceived	Mise à jour du contexte du montre
userInfoReceived	Transfert d'informations de l'utilisateur du montre
reachabilityChanged	Watch connectivity changed (iOS only)
activationStateChanged	État d'activation de la session a changé (iOS uniquement)

Modèles de communication

Messagerie immédiate (sendMessage)sendMessage)

• Requiert que le montre soit accessible
• Idéal pour la communication interactive et sensible à l'heure.
• Échoue immédiatement si le montre n'est pas disponible

Contexte de l'application (updateApplicationContext)

• Seule la dernière valeur - les valeurs précédentes sont effacées
• Best for syncing current app state
• Livré lorsque le montre 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 le montre est temporairement inatteignable

Remarques sur la plateforme

Voir la tableau de support de la plateforme Consultez l'aperçu du plugin pour une matrice détaillée.

iOS (Apple Watch)

• Exige iOS 15.0 ou ultérieur
• Utilise le framework WatchConnectivity
• La session s'active automatiquement lors du chargement du plugin.
• Supports background delivery for context and user info
• Émet reachabilityChanged et activationStateChanged

Android (Wear OS)

• Exige les services Google Play avec le layer de données Wear OS (play-services-wearableinclus avec le plugin)
• Les APKs téléphone et montre doivent partager la même applicationId et clé de signature
• Watch app must advertise capability capgo_watch
• Fait pas emit reachabilityChanged ou activationStateChangedou getInfo() Setup guide :
• Créer une application Wear OS Créer une application Wear OS

Web

• et d'autres champs aux valeurs par défaut de sécurité
• getInfo() se résout avec isSupported: false lorsqu'il est nécessaire
• getPluginVersion() se résout avec { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, et replyToMessage refuse avec une erreur indisponible
• addListener résout un handle via Capacitor WebPlugin, but watch events are unsupported in the browser (callbacks never run)

Utilisations courantes

1. Syncrodonnées: Keep watch and phone data in sync
2. Contrôl’à distance: Control phone features from watch
3. NotificationsEnvoyer des notifications personnalisées à la montre
4. Données de Santé: Partagez les métriques de fitness et de santé
5. Contrôle de Média: Contrôlez la lecture musicale depuis votre montre
6. Smart Home: Contrôlez les appareils depuis votre poignet

Troubleshooting

Votre montre n'est pas accessible :

• Ensure watch is within Bluetooth range
• Vérifiez que les deux applications sont en cours d'exécution
• Vérifiez que la session WC est activée 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 de montre implémente WCSessionDelegate
• Utilisez transferUserInfo pour une livraison garantie

Session ne s'active pas :

• Assurez-vous que la capacité WatchConnectivity est ajoutée dans Xcode
• Check that watch app has the companion bundle ID
• Verify both apps target compatible OS versions

Continuez de la section « Continuez de Getting Started »

Si vous utilisez Prise en main 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 aux plugins Enterprise Ionic pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin.