시작하기

1. 패키지를 설치하세요.

   bun add @capgo/capacitor-watch

2. 원시 프로젝트와 동기화

   bunx cap sync

3. 플러그인을 구성

   기본 사용 예시:

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

   워치로 메시지를 전송:

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOS

   iOS 설정: 필수

   1. iOS 앱에 WatchConnectivity 기능을 Xcode에 추가하세요
   2. Xcode 프로젝트에 watchOS 앱 목표를 생성하세요
   3. watchOS 앱에서 WatchConnectivity를 implement하세요 (Watch App Implementation 참조)

   플러그인은 플러그인이 로드될 때 WCSession을 자동으로 활성화합니다.

   Android

   Apple Watch는 iOS에서만 지원됩니다. Android에서는 "Apple Watch는 iOS에서만 지원됩니다." 오류로 모든 메소드가 거부됩니다. getInfo() 메소드 isSupported: false.

4. 응답이 필요한 메시지를 처리하세요

   // 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. 애플리케이션 상태를 동기화하세요

   // 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. 신뢰할 수 있는 사용자 정보 전송

   // 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. 네트워크 연결 모니터링

   // 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 구현

watchOS 앱은 WatchConnectivity를 구현해야 합니다. 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 참조

메서드

sendMessage(options: SendMessageOptions)

__CAPGO_KEEP_0__

매개 변수:

• data: Object - 시계에 전송할 데이터

updateApplicationContext(options: UpdateContextOptions)

응용 프로그램 컨텍스트 업데이트.

최신 값만 유지됩니다.

• context매개 변수:

transferUserInfo(options: TransferUserInfoOptions)

제목: transferUserInfo(options: TransferUserInfoOptions)

사용자 정보를 신뢰할 수 있는 전달을 위해 큐합니다.

• userInfo매개 변수:

replyToMessage(options: ReplyMessageOptions)

제목: replyToMessage(options: ReplyMessageOptions)

매개 변수:

• callbackId: string - messageReceivedWithReply 이벤트에서 callback ID
• data: Object - 응답 데이터

getInfo()

시계와의 연결 상태를 가져옵니다.

반환: WatchInfo 객체에 포함:

• isSupported: boolean - WatchConnectivity가 사용 가능 여부
• isPaired: boolean - 시계가 pair되어 있는지 여부
• isWatchAppInstalled: boolean - 시계 앱이 설치되어 있는지 여부
• isReachable: boolean - 시계가 접근 가능 한지 여부
• activationState: number - 세션 상태 (0/1/2)

getPluginVersion()

원시 플러그인 버전을 가져옵니다.

이벤트

이벤트	설명
messageReceived	시계에서 단순한 메시지
messageReceivedWithReply	시계에서 메시지에 응답을 기대하는 (callbackId를 포함)
applicationContextReceived	시계에서 컨텍스트 업데이트
userInfoReceived	시계와의 연결 상태가 변경되었습니다.
reachabilityChanged	세션 활성화 상태가 변경되었습니다.
activationStateChanged	getPluginVersion()를 호출하는 방법

통신 패턴

즉시 메시징 (sendMessage)

• __CAPGO_KEEP_0__가 도달 가능해야 함
• 인터랙티브 및 시간敏감적인 통신을 위한 최고
• __CAPGO_KEEP_0__가 사용 가능하지 않으면 즉시 실패

애플리케이션 컨텍스트 (updateApplicationContext)

• __CAPGO_KEEP_0__의 최신 값만 전달 - 이전 값은 덮어씌움
• 현재 앱 상태를 동기화하는 데 적합
• __CAPGO_KEEP_0__가 사용 가능해질 때 전달

사용자 정보 전송 (transferUserInfo)

• 순서대로 큐에 넣고 전달
• 중요한 데이터를 전달해야 하는 경우 가장 좋음
• 시계가 일시적으로 연결되지 않은 경우에도 작동

플랫폼 정보

iOS

• iOS 15.0 이상이 필요
• WatchConnectivity 프레임워크 사용
• 플러그인 로드 시 세션 자동 활성화
• 백그라운드 전송을 통한 컨텍스트 및 사용자 정보 지원

Android

• 지원하지 않음 (Apple Watch는 iOS 전용)
• 모든 메소드는 적절한 오류로 거부
• getInfo() returns isSupported: false

웹

• 지원하지 않음
• 모든 메소드는 사용할 수 없는 오류로 거부
• getInfo() returns isSupported: false

일반적인 사용 사례

1. 데이터 동기화: 전화기와腕목 시계의 데이터를 동기화하세요
2. 원격 제어:腕목 시계에서 전화기 기능을 제어하세요
3. 通知: 사용자 지정 알림을腕목 시계로 전송하세요
4. 건강 데이터: 운동 및 건강 지표를 공유하세요
5. 미디어 제어:腕목 시계에서 음악 재생을 제어하세요
6. 스마트 홈: 손목에서 장치를 제어하세요

문제 해결

시계가 접근할 수 없음:

• 시계가 블루투스 범위 내에 있는지 확인하세요
• 두 앱이 모두 실행 중인지 확인하세요
• WCSession이 양쪽에서 활성화되어 있는지 확인하세요

메시지가 받을 수 없음:

• 리스너가 메시지를 보내기 전에 등록되어 있는지 확인하세요
• WCSessionDelegate를 구현하고 있는지 시계 앱을 확인하세요
• 사용 transferUserInfo 보장된 전달을 위해

__CAPGO_KEEP_0__

• Xcode에서 WatchConnectivity 기능이 추가되어 있는지 확인하세요.
• 시계 앱이 동반 앱 ID를 가지고 있는지 확인하세요.
• 모든 앱이 호환 가능한 OS 버전을 대상으로 하고 있는지 확인하세요.