시작하기

설치

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

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

   Android

   Wear OS 설정을 위한 필수 구성:

   1. Xcode에서 웨어 OS 모듈 안드로이드 프로젝트에 추가하세요 (폰 앱과 동일한) applicationId 서명도 동일합니다.
   2. 웨어 모듈에서 capgo_watch 웨어 OS 앱 만들기 워치에서 데이터 레이어 리스너 구현하기 (다음과 같은 경로)).
   3. 다른 것들도 포함합니다./capgo/message, /capgo/context폰 플러그인은 워치웨어 __CAPGO_KEEP_0__ 리스너를 로드할 때 등록합니다. 연결된 노드와 워치 앱이 감지되는지 확인하려면

   Capgo Wearable API 이벤트 리스너를 로드할 때 등록합니다. 사용 getInfo() capability

   전체 단계 워치에서 데이터 레이어 리스너 구현하기 (다음과 같은 경로).

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

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 참조

Methods

sendMessage(options: SendMessageOptions)

시계에 이메시지를 전송합니다. 시계가 연결되어야 합니다.

Parameters:

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

updateApplicationContext(options: UpdateContextOptions)

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

Parameters:

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

transferUserInfo(options: TransferUserInfoOptions)

신뢰할 수 있는 전달을 위해 사용자 정보를 대기열에 넣습니다.

매개 변수:

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

replyToMessage(options: ReplyMessageOptions)

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

매개 변수:

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

getInfo()

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

반환: WatchInfo 객체에:

• isSupported: boolean - 이 플랫폼에서 watch API가 사용 가능 여부
• isPaired: boolean - Apple Watch pair (iOS) 또는 Android에서 Wear OS 노드가 연결된 적이 있는지 여부
• isWatchAppInstalled: boolean - iOS companion watch 앱 설치 여부 capgo_watch : boolean - watch가 즉시 메시징을 위해 사용 가능 여부
• isReachable: number - 세션 상태 (iOS WCSession; Android 2 노드가 연결된 경우, 0이 아닌 경우)
• activationState버전 가져오기

getPluginVersion()

이벤트

이벤트

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

통신 패턴

즉시 메시징 (sendMessage)sendMessage)

• 시계가 연결되어야 함
• 인터랙티브 및 시간敏감적인 통신을 위한 최고의 옵션
• 시계가 사용 가능하지 않으면 즉시 실패

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

• 최신 값만 전달 - 이전 값은 덮어씌워짐
• 현재 앱 상태 동기화를 위한 최고의 옵션
• 시계가 사용 가능할 때 전달

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

• 순서대로 큐에 저장되어 전달
• 중요한 데이터를 전달해야 하는 경우 최고의 옵션
• 시계가 일시적으로 사용 불가하더라도 작동

플랫폼 참고 사항

다음에 플러그인 개요에서 메서드별 매트릭스를 확인할 수 있습니다. iOS (Apple Watch)

iOS (Apple Watch) 섹션

• WatchConnectivity 프레임워크를 사용합니다.
• 플러그인 로드 시 세션 자동 활성화
• 배경 전송을 통한 컨텍스트 및 사용자 정보 지원
• 발행
• Emits reachabilityChanged 및 activationStateChanged

안드로이드 (웨어 OS)

• 구글 플레이 서비스의 Wear OS 데이터 레이어 (play-services-wearable플러그인에 포함된 것
• 폰과 웨어 APK는 동일한 인증 키 applicationId 및 워치 앱은 기능을 광고해야합니다.
• 하지 않습니다 capgo_watch
• 하지 않습니다 same emit reachabilityChanged 또는 activationStateChanged; poll getInfo() ;
• 투표 필요한 경우

설정 가이드:

• 웹
• getInfo() 웹 섹션 isSupported: false 브라우저에서 시계 메시징이 지원되지 않습니다.
• getPluginVersion() 웹 섹션 { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo와 replyToMessage 사용할 수 없는 오류로 거부합니다.
• addListener Capacitor를 통해 핸들러를 해결합니다. WebPlugin브라우저에서 watch 이벤트는 지원되지 않으며 (콜백이 실행되지 않음)

일반적인 사용 사례

1. 데이터 동기화: watch와 전화 데이터를 동기화합니다.
2. 원격 제어: watch에서 전화 기능을 제어합니다.
3. 알림: watch를 위한 사용자 지정 알림을 보냅니다.
4. 건강 데이터: 신체 활동 및 건강 지표 공유
5. 미디어 제어:腕목에서 음악 재생을 제어
6. 스마트 홈: 손목에서 장치 제어

문제 해결

손목이 연결되지 않음:

• 손목이 블루투스 범위 내에 있는지 확인하십시오
• 앱이 모두 실행 중인지 확인하십시오
• WCSession이 양쪽에서 활성화되어 있는지 확인하십시오

받지 못한 메시지:

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

세션 활성화되지 않음:

• Xcode에서 WatchConnectivity 기능이 추가되어 있는지 확인하세요
• watch 앱이 동반 앱 ID를 가지고 있는지 확인하세요
• 두 앱이 호환 가능한 OS 버전을 대상으로 하고 있는지 확인하세요

Getting Started에서 계속 진행하세요

Getting Started에서 계속 진행하는 경우 시작하기 자연스러운 플러그인 작업을 계획하기 위해, Capgo 사용자 가이드 @capgo/capacitor-watch Using @capgo/capacitor-watch Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 아이오닉 엔터프라이즈 플러그인 대안 아이오닉 엔터프라이즈 플러그인 대안