시작하기

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 기능을 추가하려면 다음 명령어를 사용하세요:

npx 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.

만약 Manual Setup을 선호한다면, 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요.

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에서 WatchConnectivity 기능을 iOS 앱에 추가하세요
   2. Xcode 프로젝트에 watchOS 앱 목표를 생성하세요
   3. watchOS 앱에서 WatchConnectivity를 implement하세요 (아래의 Watch App Implementation 참조)

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

   안드로이드

   Apple Watch는 iOS에서만 지원됩니다. 안드로이드에서는 모든 메소드는 "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)

시계를 사용할 수 있는지 확인하여 시계에 인터랙티브 메시지를 전송합니다.

매개 변수:

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

updateApplicationContext(options: UpdateContextOptions)

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

매개 변수:

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

transferUserInfo(options: TransferUserInfoOptions)

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

매개 변수:

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

replyToMessage(options: ReplyMessageOptions)

메시지에 대한 응답을 보내세요.

매개 변수:

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

getInfo()

시계 연결 상태를 가져오세요.

반환: WatchInfo object with:

• isSupported: boolean - WatchConnectivity가 사용 가능합니다.
• isPaired : boolean - Pair된 watch 여부
• isWatchAppInstalled : boolean - Watch 앱 설치 여부
• isReachable : boolean - Watch 접근 가능 여부
• activationState : number - 세션 상태 (0/1/2)

getPluginVersion()

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

Events

Event	Description
messageReceived	watch에서 보내는 간단한 메시지
messageReceivedWithReply	메시지에 응답을 기대며 callbackId를 포함합니다.
applicationContextReceived	Context update from watch
userInfoReceived	유저 정보 전송
reachabilityChanged	Watch 연결 상태가 변경되었습니다
activationStateChanged	세션 활성화 상태가 변경되었습니다

통신 패턴

즉시 메시징 (sendMessage)sendMessage)

• 인터랙티브 및 시간에 민감한 통신에 적합합니다
• watch가 사용 가능하지 않으면 즉시 실패합니다
• 애플리케이션 컨텍스트

즉시 메시징 (sendMessage)updateApplicationContext)

• 최신 값만 - 이전 값은 덮어씌어집니다.
• 현재 앱 상태 동기화에 가장 적합합니다.
• 시계가 사용 가능해질 때 전달됩니다.

사용자 정보 전송 (transferUserInfo)transferUserInfo)

• 중요한 데이터를 전달해야 하는 경우 가장 적합합니다.
• 시계가 일시적으로 연결되지 않아도 작동합니다.
• 플랫폼 참고 사항

iOS

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

• iOS 15.0 이상이 필요합니다.
• WatchConnectivity 프레임워크를 사용합니다.
• 플러그인 로드 시 세션은 자동으로 활성화됩니다.
• 배경 전송을 지원하며 사용자 정보도 지원합니다.

Android

• Apple Watch는 iOS만 지원하므로 지원되지 않습니다.
• 모든 메소드는 적절한 오류를 반환합니다.
• getInfo() returns isSupported: false

Web

• Not supported
• All methods reject with unavailable error
• getInfo() returns isSupported: false

일반적인 사용 사례

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

문제 해결

목걸이가 연결되지 않습니다:

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

메시지가 수신되지 않습니다:

• __CAPGO_KEEP_0__
• __CAPGO_KEEP_1__
• __CAPGO_KEEP_2__ transferUserInfo __CAPGO_KEEP_3__

__CAPGO_KEEP_4__

• __CAPGO_KEEP_5__
• __CAPGO_KEEP_6__
• __CAPGO_KEEP_7__

__CAPGO_KEEP_8__

__CAPGO_KEEP_10__ __CAPGO_KEEP_11__ native 플러그인 작업을 계획하려면 Using @capgo/capacitor-watch native 기능을 사용하는 Using @capgo/capacitor-watch Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리 Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안