시작하기

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

   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

   iOS에 대한 필수 설정:

   1. Xcode에서 iOS 앱에 WatchConnectivity 기능을 추가하세요.
   2. Xcode 프로젝트에서 watchOS 앱 대상 만들기
   3. watchOS 앱에서 WatchConnectivity 구현 (Watch App Implementation 참조)

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

   안드로이드

   Apple Watch는 iOS에서만 지원됩니다. 안드로이드에서는 "Apple Watch는 iOS에서만 지원됩니다." 오류와 함께 모든 메서드가 거부됩니다. getInfo() method 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);
   });

앱 구현

시계 앱 구현을 위해 시계 앱은 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)

시계에 인터랙티브 메시지를 전송합니다. 시계가 연결되어야 합니다.

매개 변수:

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

updateApplicationContext(options: UpdateContextOptions)

응용 프로그램 컨텍스트를 업데이트합니다. 최신 값만 유지됩니다.

매개 변수:

• context: Object - 동기화할 컨텍스트 데이터

transferUserInfo(options: TransferUserInfoOptions)

유저 정보 전송을 위한 신뢰할 수 있는 전송 대기열에 유저 정보를 넣습니다.

매개 변수:

• userInfo: Object - 전송할 유저 정보

replyToMessage(options: ReplyMessageOptions)

메시지에 대한 응답을 보내는 메소드입니다.

매개 변수:

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

getInfo()

watch 연결 상태를 가져옵니다.

반환 값: WatchInfo object with:

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

getPluginVersion()

이벤트

Section titled “Events”

설명	Capgo 플러그인 버전을 가져옵니다.
messageReceived	시계에서 오는 간단한 메시지
messageReceivedWithReply	__CAPGO_KEEP_0__에 대한 응답을 기대하는 메시지 (callbackId 포함)
applicationContextReceived	시계에서 오는 컨텍스트 업데이트
userInfoReceived	시계에서 오는 사용자 정보 전송
reachabilityChanged	시계와의 연결 상태가 변경되었습니다
activationStateChanged	세션 활성화 상태가 변경되었습니다

통신 패턴

시계가 접근 가능해야 함 (sendMessage)sendMessage)

• 시계가 접근 가능해야 함
• 시계가 접근 가능해야 함
• 시계 감시가 사용 가능하지 않으면 즉시 실패합니다.

응용 프로그램 컨텍스트 (updateApplicationContext)

• 최신 값만 제공 - 이전 값은 덮어씌워집니다.
• 현재 앱 상태同步에 최적입니다.
• 시계가 사용 가능해질 때 전달됩니다.

사용자 정보 전송 (transferUserInfo)

• 순서대로 큐에 넣어 전달됩니다.
• 중요한 데이터가 전달되어야 하는 경우에 최적입니다.
• 시계가 일시적으로 사용 불가능해도 작동합니다.

플랫폼 참고 사항

iOS

• iOS 15.0 이상이 필요합니다.
• WatchConnectivity 프레임워크 사용
• 플러그인 로드 시 세션 자동 활성화
• 컨텍스트 및 사용자 정보를 위한 배경 전송 지원

Android

• 지원되지 않음 (애플 워치는 iOS 전용)
• 모든 메소드는 적절한 오류로 거부
• getInfo() returns isSupported: false

웹

• 지원하지 않음
• 모든 메서드는 사용할 수 없음 오류로 거부합니다.
• getInfo() 반환 isSupported: false

일반적인 사용 사례

1. 데이터 동기화: 전화기와腕목 기기 간 데이터를 동기화합니다.
2. :腕목 기기에서 전화기 기능을 제어합니다.:腕목 기기에서 알림을 받습니다.
3. Section titled “Notifications”: 사용자 지정 알림을 시계로 전송하세요.
4. 건강 데이터: 건강 및 운동 데이터를 공유하세요.
5. 미디어 제어: 시계에서 음악 재생을 제어하세요.
6. 스마트 홈: 손목에서 장치 제어하세요.

문제 해결

시계 접근 불가:

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

받지 못한 메시지:

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

세션 활성화되지 않음:

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