@plevo/expo-watch-connectivity

Expo module wrapping Apple's WatchConnectivity framework for seamless communication between React Native/Expo apps and Apple Watch apps.

Installation

npx expo install @plevo/expo-watch-connectivity

Usage

import { WatchConnectivity } from '@plevo/expo-watch-connectivity';

// Activate the session (required before any communication)
await WatchConnectivity.activate();

// Check if Watch is reachable for real-time messaging
if (WatchConnectivity.sessionState.isReachable) {
  const reply = await WatchConnectivity.sendMessage({ action: 'ping' });
  console.log('Watch replied:', reply);
}

// Listen for incoming messages
const subscription = WatchConnectivity.addMessageListener(({ message, replyId }) => {
  console.log('Received from Watch:', message);
  
  // Reply if the Watch expects a response
  if (replyId) {
    WatchConnectivity.replyToMessage(replyId, { status: 'ok' });
  }
});

// Background sync via application context (latest-wins)
await WatchConnectivity.updateApplicationContext({
  theme: 'dark',
  lastSync: Date.now(),
});

// Background transfer via user info (queued FIFO)
WatchConnectivity.transferUserInfo({ notification: 'New data available' });

// File transfer
WatchConnectivity.transferFile('/path/to/file.pdf', { name: 'Document' });

// Cleanup
subscription.remove();

API Reference

State Properties

| Property | Type | Description | |----------|------|-------------| | isSupported | boolean | Whether WatchConnectivity is supported (always false on Android) | | sessionState | SessionState | Current session state including pairing, reachability, etc. | | applicationContext | Record<string, unknown> | Most recently sent application context | | receivedApplicationContext | Record<string, unknown> | Most recently received application context | | outstandingUserInfoTransfers | UserInfoTransferInfo[] | Pending user info transfers | | outstandingFileTransfers | FileTransferInfo[] | Pending file transfers |

Methods

Lifecycle

• activate(): Promise<ActivationState> - Activate the WatchConnectivity session

Real-time Messaging (requires isReachable)

• sendMessage(message): Promise<Record<string, unknown>> - Send message and get reply
• sendMessageData(base64Data): Promise<string> - Send raw data and get reply
• replyToMessage(replyId, reply): void - Reply to an incoming message
• replyToMessageData(replyId, base64Data): void - Reply with raw data

Background Sync

• updateApplicationContext(context): Promise<void> - Update application context (latest-wins)
• transferUserInfo(userInfo): UserInfoTransferInfo - Queue user info transfer (FIFO)
• transferCurrentComplicationUserInfo(userInfo): UserInfoTransferInfo - Transfer for complications
• transferFile(url, metadata?): FileTransferInfo - Transfer a file

Event Listeners

All listeners return an EventSubscription with a .remove() method for cleanup.

| Listener | Event Type | Description | |----------|------------|-------------| | addSessionStateListener | SessionStateChangedEvent | Session state changes | | addReachabilityListener | ReachabilityChangedEvent | Reachability changes | | addActivationListener | ActivationDidCompleteEvent | Activation completed | | addMessageListener | MessageReceivedEvent | Message received | | addMessageDataListener | MessageDataReceivedEvent | Data message received | | addApplicationContextListener | ApplicationContextReceivedEvent | Context received | | addUserInfoListener | UserInfoReceivedEvent | User info received | | addFileListener | FileReceivedEvent | File received | | addFileTransferProgressListener | FileTransferProgressEvent | Transfer progress | | addFileTransferCompletedListener | FileTransferCompletedEvent | Transfer completed | | addUserInfoTransferCompletedListener | UserInfoTransferCompletedEvent | User info transfer completed |

Integration with expo-apple-targets

This module is designed to work seamlessly with @bacons/expo-apple-targets for Apple Watch app development.

Shared App Groups

To share data between your main app and Watch app via UserDefaults:

app.json:

{
  "expo": {
    "ios": {
      "entitlements": {
        "com.apple.security.application-groups": ["group.com.yourapp.shared"]
      }
    }
  }
}

targets/watch/expo-target.config.js:

module.exports = (config) => ({
  type: "watch",
  entitlements: {
    "com.apple.security.application-groups": 
      config.ios.entitlements["com.apple.security.application-groups"],
  },
});

Platform Support

| Platform | Support | |----------|---------| | iOS | ✅ Full support | | Android | ❌ Returns isSupported: false | | Web | ❌ Not supported |

License

MIT