시작하기
이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함하는 설정 명령어를 복사하세요.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-watch`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/watch/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
-
패키지를 설치하세요.
터미널 창 bun add @capgo/capacitor-watch -
원시 프로젝트와 동기화
터미널 창 bunx cap sync -
플러그인을 구성
기본 사용 예시:
import { CapgoWatch } from '@capgo/capacitor-watch';// Check watch connectivity statusconst info = await CapgoWatch.getInfo();console.log('Watch paired:', info.isPaired);console.log('Watch reachable:', info.isReachable);// Listen for messages from watchawait CapgoWatch.addListener('messageReceived', (event) => {console.log('Message from watch:', event.message);});워치로 메시지를 전송:
// Check if watch is reachable firstconst info = await CapgoWatch.getInfo();if (info.isReachable) {await CapgoWatch.sendMessage({data: { action: 'refresh', timestamp: Date.now() }});}iOS 설정: 필수
- iOS 앱에 WatchConnectivity 기능을 Xcode에 추가하세요
- Xcode 프로젝트에 watchOS 앱 목표를 생성하세요
- watchOS 앱에서 WatchConnectivity를 implement하세요 (Watch App Implementation 참조)
플러그인은 플러그인이 로드될 때 WCSession을 자동으로 활성화합니다.
Apple Watch는 iOS에서만 지원됩니다. Android에서는 "Apple Watch는 iOS에서만 지원됩니다." 오류로 모든 메소드가 거부됩니다.
getInfo()메소드isSupported: false. -
응답이 필요한 메시지를 처리하세요
// Listen for messages that need a responseawait CapgoWatch.addListener('messageReceivedWithReply', async (event) => {console.log('Request from watch:', event.message);// Process the requestconst result = await processWatchRequest(event.message);// Send reply back to watchawait CapgoWatch.replyToMessage({callbackId: event.callbackId,data: { result }});}); -
애플리케이션 상태를 동기화하세요
// Update application context (latest value only)await CapgoWatch.updateApplicationContext({context: {theme: 'dark',userId: '123',lastSync: Date.now()}});// Listen for context updates from watchawait CapgoWatch.addListener('applicationContextReceived', (event) => {console.log('Context from watch:', event.context);}); -
신뢰할 수 있는 사용자 정보 전송
// 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 transfersawait CapgoWatch.addListener('userInfoReceived', (event) => {console.log('User info from watch:', event.userInfo);}); -
네트워크 연결 모니터링
// Track reachability changesawait CapgoWatch.addListener('reachabilityChanged', (event) => {console.log('Watch reachable:', event.isReachable);if (event.isReachable) {// Watch is now available for interactive messaging}});// Track session activation stateawait CapgoWatch.addListener('activationStateChanged', (event) => {// 0 = notActivated, 1 = inactive, 2 = activatedconsole.log('Session state:', event.state);});
Watch App 구현
Watch App 구현 섹션watchOS 앱은 WatchConnectivity를 구현해야 합니다. SwiftUI 예시입니다.
import SwiftUIimport WatchConnectivity
@mainstruct 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 참조
API 참조 섹션메서드
메시지 전송sendMessage(options: SendMessageOptions)
시계에 상호 작용하는 메시지를 전송합니다. 시계가 연결되어야 합니다.__CAPGO_KEEP_0__
매개 변수:
data: Object - 시계에 전송할 데이터
updateApplicationContext(options: UpdateContextOptions)
제목: updateApplicationContext(options: UpdateContextOptions)응용 프로그램 컨텍스트 업데이트.
최신 값만 유지됩니다.
context매개 변수:
transferUserInfo(options: TransferUserInfoOptions)
: Object - 동기화할 컨텍스트 데이터제목: transferUserInfo(options: TransferUserInfoOptions)
사용자 정보를 신뢰할 수 있는 전달을 위해 큐합니다.
userInfo매개 변수:
replyToMessage(options: ReplyMessageOptions)
: Object - 전송할 사용자 정보제목: replyToMessage(options: ReplyMessageOptions)
매개 변수:
callbackId: string - messageReceivedWithReply 이벤트에서 callback IDdata: Object - 응답 데이터
getInfo()
getInfo() 제목시계와의 연결 상태를 가져옵니다.
반환: WatchInfo 객체에 포함:
isSupported: boolean - WatchConnectivity가 사용 가능 여부isPaired: boolean - 시계가 pair되어 있는지 여부isWatchAppInstalled: boolean - 시계 앱이 설치되어 있는지 여부isReachable: boolean - 시계가 접근 가능 한지 여부activationState: number - 세션 상태 (0/1/2)
getPluginVersion()
getPluginVersion()를 호출하는 방법원시 플러그인 버전을 가져옵니다.
이벤트
이벤트| 이벤트 | 설명 |
|---|---|
messageReceived | 시계에서 단순한 메시지 |
messageReceivedWithReply | 시계에서 메시지에 응답을 기대하는 (callbackId를 포함) |
applicationContextReceived | 시계에서 컨텍스트 업데이트 |
userInfoReceived | 시계와의 연결 상태가 변경되었습니다. |
reachabilityChanged | 세션 활성화 상태가 변경되었습니다. |
activationStateChanged | getPluginVersion()를 호출하는 방법 |
통신 패턴
통신 패턴 섹션즉시 메시징 (sendMessage)
즉시 메시징 (sendMessage)- __CAPGO_KEEP_0__가 도달 가능해야 함
- 인터랙티브 및 시간敏감적인 통신을 위한 최고
- __CAPGO_KEEP_0__가 사용 가능하지 않으면 즉시 실패
애플리케이션 컨텍스트 (updateApplicationContext)
애플리케이션 컨텍스트 (updateApplicationContext)- __CAPGO_KEEP_0__의 최신 값만 전달 - 이전 값은 덮어씌움
- 현재 앱 상태를 동기화하는 데 적합
- __CAPGO_KEEP_0__가 사용 가능해질 때 전달
사용자 정보 전송 (transferUserInfo)
사용자 정보 전송 (transferUserInfo) 섹션- 순서대로 큐에 넣고 전달
- 중요한 데이터를 전달해야 하는 경우 가장 좋음
- 시계가 일시적으로 연결되지 않은 경우에도 작동
플랫폼 정보
플랫폼 정보 섹션iOS
iOS 섹션- iOS 15.0 이상이 필요
- WatchConnectivity 프레임워크 사용
- 플러그인 로드 시 세션 자동 활성화
- 백그라운드 전송을 통한 컨텍스트 및 사용자 정보 지원
Android
Android- 지원하지 않음 (Apple Watch는 iOS 전용)
- 모든 메소드는 적절한 오류로 거부
getInfo()returnsisSupported: false
웹
웹- 지원하지 않음
- 모든 메소드는 사용할 수 없는 오류로 거부
getInfo()returnsisSupported: false
일반적인 사용 사례
일반적인 사용 사례- 데이터 동기화: 전화기와腕목 시계의 데이터를 동기화하세요
- 원격 제어:腕목 시계에서 전화기 기능을 제어하세요
- 通知: 사용자 지정 알림을腕목 시계로 전송하세요
- 건강 데이터: 운동 및 건강 지표를 공유하세요
- 미디어 제어:腕목 시계에서 음악 재생을 제어하세요
- 스마트 홈: 손목에서 장치를 제어하세요
문제 해결
제목 '문제 해결'시계가 접근할 수 없음:
- 시계가 블루투스 범위 내에 있는지 확인하세요
- 두 앱이 모두 실행 중인지 확인하세요
- WCSession이 양쪽에서 활성화되어 있는지 확인하세요
메시지가 받을 수 없음:
- 리스너가 메시지를 보내기 전에 등록되어 있는지 확인하세요
- WCSessionDelegate를 구현하고 있는지 시계 앱을 확인하세요
- 사용
transferUserInfo보장된 전달을 위해
__CAPGO_KEEP_0__
- Xcode에서 WatchConnectivity 기능이 추가되어 있는지 확인하세요.
- 시계 앱이 동반 앱 ID를 가지고 있는지 확인하세요.
- 모든 앱이 호환 가능한 OS 버전을 대상으로 하고 있는지 확인하세요.