시작하기

설치

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에서 iOS 앱에 WatchConnectivity 기능을 추가하세요
   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 이벤트에서 callback ID
• data: Object - 응답 데이터

getInfo()

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

반환: WatchInfo object with:

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

getPluginVersion()

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

이벤트

설명	시ンプル한 시계에서 오는 메시지
messageReceived	메시지에 응답을 기대하는 메시지 (callbackId 포함)
messageReceivedWithReply	__CAPGO_KEEP_0__
applicationContextReceived	시계 업데이트
userInfoReceived	시계에서 사용자 정보 전송
reachabilityChanged	시계 연결 상태가 변경되었습니다
activationStateChanged	세션 활성화 상태가 변경되었습니다

통신 패턴

즉시 메시징 (sendMessage)sendMessage)

• 인터랙티브 및 시간 민감한 통신에 적합
• 시계가 사용 가능하지 않으면 즉시 실패
• 응용 프로그램 컨텍스트 (

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

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

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

• 순서대로 큐에 넣어져 전달됩니다.
• 중요한 데이터가 전달되어야 할 때 가장 적합합니다.
• 워치가 일시적으로 연결되지 않아도 작동합니다.

플랫폼 참고 사항

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

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

Android

• 지원되지 않습니다. (애플 워치는 iOS 전용입니다.)
• 모든 메소드는 적절한 오류를 반환합니다.
• getInfo() returns isSupported: false

Web

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

일반적인 사용 사례

1. 데이터 동기화: Keep watch and phone data in sync
2. 원격 제어: Control phone features from watch
3. 알림: Send custom notifications to watch
4. 건강 데이터기록 공유
5. 미디어 제어시계에서 음악 재생을 제어하세요
6. 스마트 홈시계에서 장치 제어

문제 해결

시계가 Bluetooth 범위 내에 있는지 확인하세요

• 모든 앱이 실행 중인지 확인하세요
• WCSession이 양쪽에서 활성화되어 있는지 확인하세요
• 메시지가 받지 못하는 경우

메시지가 받지 못하는 경우

• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__ transferUserInfo __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ native 플러그인 작업을 계획하려면, 그것을 Using @capgo/capacitor-watch native 기능을 사용하는 @capgo/capacitor-watch Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항, 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안의 제품 워크플로우