Getting Started

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Then use the following prompt:

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

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

1. Install the package

   bun add @capgo/capacitor-watch

2. Sync with native projects

   bunx cap sync

3. Configure the plugin

   Basic Usage Example:

   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);
   });

   Send a Message to 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

   Required iOS Setup:

   1. Add the WatchConnectivity capability to your iOS app in Xcode
   2. Create a watchOS app target in your Xcode project
   3. Implement WatchConnectivity in your watchOS app (see Watch App Implementation below)

   The plugin automatically activates the WCSession when the plugin loads.

   Android

   Required Wear OS setup:

   1. Add a Wear OS module to your Android project (same applicationId and signing as the phone app).
   2. Declare the capgo_watch capability in the wear module (see Creating a Wear OS app).
   3. Implement Data Layer listeners on the watch using the plugin paths (/capgo/message, /capgo/context, and others).

   The phone plugin registers Wearable API listeners when it loads. Use getInfo() to check connected nodes and whether the watch app is detected.

   Full steps: Creating a Wear OS app.

4. Handle messages that require a reply

   // 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. Sync application state

   // 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. Transfer user info reliably

   // 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. Monitor connectivity

   // 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);
   });

Watch App Implementation

Your watchOS app needs to implement WatchConnectivity. Here’s a SwiftUI example:

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 Reference

Methods

sendMessage(options: SendMessageOptions)

Send an interactive message to the watch. Requires watch to be reachable.

Parameters:

• data: Object - The data to send to the watch

updateApplicationContext(options: UpdateContextOptions)

Update application context. Only latest value is kept.

Parameters:

• context: Object - The context data to sync

transferUserInfo(options: TransferUserInfoOptions)

Queue user info for reliable delivery.

Parameters:

• userInfo: Object - The user info to transfer

replyToMessage(options: ReplyMessageOptions)

Reply to a message that requested a response.

Parameters:

• callbackId: string - The callback ID from messageReceivedWithReply event
• data: Object - The reply data

getInfo()

Get watch connectivity status.

Returns: WatchInfo object with:

• isSupported: boolean - Whether watch APIs are available on this platform
• isPaired: boolean - Apple Watch paired (iOS) or at least one Wear OS node connected (Android)
• isWatchAppInstalled: boolean - Companion watch app installed (iOS) or capgo_watch capability detected (Android)
• isReachable: boolean - Whether the watch is reachable for immediate messaging
• activationState: number - Session state (iOS WCSession; Android 2 when a node is connected, 0 otherwise)

getPluginVersion()

Get the native plugin version.

Events

Event	Description
messageReceived	Simple message from watch
messageReceivedWithReply	Message expecting a reply (includes callbackId)
applicationContextReceived	Context update from watch
userInfoReceived	User info transfer from watch
reachabilityChanged	Watch connectivity changed (iOS only)
activationStateChanged	Session activation state changed (iOS only)

Communication Patterns

Immediate Messaging (sendMessage)

• Requires watch to be reachable
• Best for interactive, time-sensitive communication
• Fails immediately if watch is not available

Application Context (updateApplicationContext)

• Latest value only - previous values are overwritten
• Best for syncing current app state
• Delivered when watch becomes available

User Info Transfer (transferUserInfo)

• Queued and delivered in order
• Best for important data that must be delivered
• Works even when watch is temporarily unreachable

Platform Notes

See the platform support table on the plugin overview for a method-by-method matrix.

iOS (Apple Watch)

• Requires iOS 15.0 or later
• Uses WatchConnectivity framework
• Session automatically activates on plugin load
• Supports background delivery for context and user info
• Emits reachabilityChanged and activationStateChanged

Android (Wear OS)

• Requires Google Play services with Wear OS Data Layer (play-services-wearable, included with the plugin)
• Phone and wear APKs must share the same applicationId and signing key
• Watch app must advertise capability capgo_watch
• Does not emit reachabilityChanged or activationStateChanged; poll getInfo() when needed
• Setup guide: Creating a Wear OS app

Web

• Watch messaging is not supported in the browser
• getInfo() resolves with isSupported: false and other fields at safe defaults
• getPluginVersion() resolves with { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, and replyToMessage reject with an unavailable error
• addListener resolves a handle via Capacitor WebPlugin, but watch events are unsupported in the browser (callbacks never run)

Common Use Cases

1. Data Sync: Keep watch and phone data in sync
2. Remote Control: Control phone features from watch
3. Notifications: Send custom notifications to watch
4. Health Data: Share fitness and health metrics
5. Media Control: Control music playback from watch
6. Smart Home: Control devices from your wrist

Troubleshooting

Watch not reachable:

• Ensure watch is within Bluetooth range
• Check that both apps are running
• Verify WCSession is activated on both sides

Messages not received:

• Check that listeners are registered before sending
• Verify the watch app implements WCSessionDelegate
• Use transferUserInfo for guaranteed delivery

Session not activating:

• Ensure WatchConnectivity capability is added in Xcode
• Check that watch app has the companion bundle ID
• Verify both apps target compatible OS versions

Keep going from Getting Started

If you are using Getting Started to plan native plugin work, connect it with Using @capgo/capacitor-watch for the native capability in Using @capgo/capacitor-watch, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.