시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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 capability 추가
   2. Xcode 프로젝트에 watchOS 앱 타겟 생성
   3. watchOS 앱에 WatchConnectivity를 구현하세요 (아래 'Watch 앱 구현' 섹션 참조)

   플러그인이 로드되면 WCSession이 자동으로 활성화됩니다.

   Android

   필수 Wear OS 설정:

   1. 다음 Wear OS 모듈을 Android 프로젝트에 추가하세요 (폰 앱과 동일한 applicationId 서명 방식 사용).
   2. 해당 기능을 capgo_watch wear 모듈에 선언하세요 (아래 Wear OS 앱 만들기).
   3. 플러그인 경로를 사용해 watch에서 Data Layer 리스너를 구현하세요 (/capgo/message, /capgo/context기타 포함).

   phone 플러그인은 로드될 때 Wearable API 리스너를 등록합니다. 다음을 사용하세요: getInfo() 연결된 노드와 watch 앱이 감지되는지 확인하려면 사용하세요.

   전체 단계: Wear OS 앱 만들기.

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 (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         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);
   });

빠른 시작

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

예시: updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

예시: transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

자주 하는 실수

• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 네이티브 동기화: 실행 bunx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

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)

워치로 인터랙티브 메시지를 전송합니다. 워치와 연결된 상태여야 합니다.

파라미터:

• data: Object - 워치로 전송할 데이터

updateApplicationContext(options: UpdateContextOptions)

애플리케이션 컨텍스트를 업데이트합니다. 최신 값만 유지됩니다.

파라미터:

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

transferUserInfo(options: TransferUserInfoOptions)

안정적인 전달을 위해 사용자 정보를 큐에 저장합니다.

파라미터:

• userInfo: Object - 전송할 사용자 정보

replyToMessage(options: ReplyMessageOptions)

응답을 요청한 메시지에 답장합니다.

파라미터:

• callbackId: string - messageReceivedWithReply 이벤트의 콜백 ID
• data: Object - 답장 데이터

getInfo()

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

반환값: WatchInfo 다음 항목을 포함하는 object:

• isSupported: boolean - 해당 플랫폼에서 watch API 사용 가능 여부
• isPaired: boolean - Apple Watch 페어링됨(iOS) 또는 Wear OS 노드 1개 이상 연결됨(Android)
• isWatchAppInstalled: boolean - Companion watch 앱 설치됨(iOS) 또는 capgo_watch 기능 감지됨(Android)
• isReachable: boolean - 즉시 메시징을 위해 워치에 연결 가능한 상태인지 여부
• activationState: number - 세션 상태 (iOS WCSession; Android는 노드 연결 시 2, 그 외 0)

getPluginVersion()

네이티브 플러그인 버전을 가져옵니다.

이벤트

이벤트	설명
messageReceived	watch에서 보낸 간단한 메시지
messageReceivedWithReply	답장을 기다리는 메시지 (callbackId 포함)
applicationContextReceived	watch에서 보낸 컨텍스트 업데이트
userInfoReceived	watch에서 전달된 사용자 정보
reachabilityChanged	watch 연결 상태 변경 (iOS 전용)
activationStateChanged	세션 활성화 상태 변경 (iOS 전용)

통신 패턴

즉시 메시징 (sendMessage)

• watch 연결이 가능한 상태여야 함
• 상호작용이 필요하거나 실시간성이 중요한 통신에 적합
• watch 사용 불가 시 즉시 실패

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

• 최신 값만 유지 - 이전 값은 덮어씌워짐
• 현재 앱 상태 동기화에 최적
• watch가 사용 가능해지면 전달됨

사용자 정보 전송 (transferUserInfo)

• 큐에 저장되어 순서대로 전달됨
• 반드시 전달되어야 하는 중요 데이터에 최적
• watch 연결이 일시적으로 끊겨도 작동함

플랫폼 참고 사항

참고하세요: 예제 앱의 플랫폼 지원 표 플러그인 개요에서 메서드별 매트릭스를 확인하세요.

iOS (Apple Watch)

• iOS 15.0 이상 필요
• WatchConnectivity framework 사용
• 플러그인 로드 시 세션 자동 활성화
• context 및 user info에 대한 백그라운드 전달 지원
• 발생(Emits) reachabilityChanged 및 activationStateChanged

Android (Wear OS)

• Wear OS Data Layer를 포함한 Google Play services가 필요합니다 (play-services-wearable, 플러그인에 포함됨)
• Phone과 wear APK는 동일한 동일한 것을 공유하고 applicationId 및 서명 키를 공유해야 합니다
• Watch 앱은 capability를 알려야 합니다 capgo_watch
• 여부 하지 마세요 emit reachabilityChanged 또는 activationStateChanged; 폴링 getInfo() 필요할 때
• 설정 가이드: Wear OS 앱 만들기

웹

• 브라우저에서는 Watch 메시징을 지원하지 않습니다
• getInfo() 다음 값으로 resolve됩니다 isSupported: false 및 기타 필드는 안전한 기본값으로 설정됩니다
• getPluginVersion() 다음 값으로 resolve됩니다 { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, 그리고 replyToMessage unavailable 에러로 거부
• addListener Capacitor를 통해 핸들을 resolve함 WebPlugin, 하지만 브라우저에서는 watch 이벤트가 지원되지 않음 (콜백은 실행되지 않음)

주요 사용 사례

1. 데이터 동기화: watch와 휴대폰 데이터를 동기화 상태로 유지
2. 원격 제어: watch에서 휴대폰 기능 제어
3. 알림: watch로 커스텀 알림 전송
4. 건강 데이터: 피트니스 및 건강 지표 공유
5. 미디어 컨트롤: 워치에서 음악 재생 제어
6. 스마트 홈: 손목에서 기기 제어

문제 해결

워치 연결 불가:

• 워치가 Bluetooth 범위 내에 있는지 확인하세요
• 양쪽 앱이 모두 실행 중인지 확인하세요
• 양측 모두 WCSession이 활성화되었는지 확인하세요

메시지 수신 실패:

• 전송 전 리스너가 등록되었는지 확인하세요
• watch app에 WCSessionDelegate가 구현되었는지 확인하세요
• 사용 transferUserInfo 확실한 전달을 위해

세션이 활성화되지 않는 경우:

• Xcode에서 WatchConnectivity capability가 추가되었는지 확인하세요
• watch app에 companion bundle ID가 설정되었는지 확인하세요
• 두 앱의 대상 OS 버전이 호환되는지 확인하세요

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-watch 사용하기 @capgo/capacitor-watch를 사용하여 네이티브 기능을 구현하려면, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.