Getting Started

설치

Capgo의 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를 implement해야 합니다. 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 - Pairing 여부
• isWatchAppInstalled: boolean - Watch 앱 설치 여부
• isReachable: boolean - Watch 접속 가능 여부
• activationState: number - 세션 상태 (0/1/2)

getPluginVersion()

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

이벤트

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

통신 패턴

즉시 메시징 (sendMessage)sendMessage)

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

Application Context (updateApplicationContext)

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

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

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

iOS

최신 값만 - 이전 값은 덮어씌워집니다.

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

Android

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

Web

• 지원되지 않음
• 모든 메서드는 unavailable 오류로 거부합니다
• getInfo() 반환 isSupported: false

일반적인 사용 사례

1. 데이터 동기화: 시계와 전화 데이터를 동기화합니다
2. 원격 제어: 시계에서 전화 기능을 제어합니다
3. 通知: 시계에 사용자 지정 알림을 전송합니다
4. 건강 데이터: __CAPGO_KEEP_0__
5. 미디어 제어: __CAPGO_KEEP_1__
6. 스마트 홈: __CAPGO_KEEP_2__

문제 해결

페이지 제목

• 페이지 제목
• 페이지 제목
• 페이지 제목

페이지 제목

• 리스너가 등록되어 있는지 확인하기 전에 보내기
• Watch 앱이 WCSessionDelegate를 implement하는지 확인하기
• 사용 transferUserInfo 보장된 전달을 위해

Session이 활성화되지 않는 경우:

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

Getting Started에서 계속하기

Getting Started를 사용하는 경우 Getting Started 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, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체