Prise en main

Installation

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

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

Ensuite, utilisez 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. Installez 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 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 « Apple Watch n'est pris en charge que sur iOS ». getInfo() La méthode retourne isSupported: false.

4. Gérez 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. Synchronisation de 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émentation de 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)")
    }
}

Référence de API

Méthodes

sendMessage(options: SendMessageOptions)

Envoyer un message interactif à l'horloge. Cela nécessite 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 dernière valeur est conservée.

Paramètres :

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

transferUserInfo(options: TransferUserInfoOptions)

File d'attente 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 - L'ID de rappel provenant de l'événement messageReceivedWithReply
• data : objet - Les données de réponse

getInfo()

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

Renvoie : WatchInfo un objet avec :

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

getPluginVersion()

Récupérer la version native du plugin

Événements

Événement	Description
messageReceived	Message simple du watch
messageReceivedWithReply	Message en attente de réponse (inclut callbackId)
applicationContextReceived	Actualisation du contexte à partir de l'horloge
userInfoReceived	Transfert d'informations de l'utilisateur à partir de l'horloge
reachabilityChanged	État de la connectivité de l'horloge a changé
activationStateChanged	État d'activation de la session a changé

Modèles de communication

Envoi de messages instantanés (sendMessage)

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

Contexte de l'application (updateApplicationContext)

• Seulement la dernière valeur - les valeurs précédentes sont effacées
• Idéal pour synchroniser l'état actuel de l'application
• Envoyé lorsque le montre devient disponible

Transfert d'informations utilisateur (transferUserInfo)

• En file d'attente et envoyé dans l'ordre
• Idéal pour les données importantes qui doivent être envoyées
• Fonctionne même lorsque le montre est temporairement inatteignable

Notes de plateforme

iOS

• Exige iOS 15.0 ou une version ultérieure
• Utilise le framework WatchConnectivity
• La session est automatiquement activée lors du chargement du plugin
• Supporte la livraison en arrière-plan pour le contexte et les informations de l'utilisateur

Android

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

Web

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

Utilisations courantes

1. Synchronisation de données : Conservez les données de l'horloge et du téléphone en synchronisation
2. Contrôl’à distance : Contrôlez les fonctionnalités du téléphone à partir de l'horloge
3. Notifications : Envoyez des notifications personnalisées à l'horloge
4. Données de santé: Partagez les métriques de fitness et de santé
5. Contrôle de médias: Contrôlez la lecture de musique depuis votre montre
6. Maison intelligente: Contrôlez les appareils depuis votre poignet

Résolution de problèmes

Votre montre n'est pas accessible :

• Vérifiez que la montre est dans la zone de couverture Bluetooth
• 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

Les messages ne sont pas reçus :

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

Continuez de la section « Continuez de Getting Started »

Si vous utilisez Getting Started 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 d'entreprise Ionic pour le flux de travail du produit dans Alternatives de plugins d'entreprise Ionic.