watchOS 앱 만들기

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 지시를 복사하세요.

이 가이드는 watchOS 동반 앱을 처음부터 만들기 위해 Xcode에서 프로젝트 설정, CapgoWatchSDK 통합 및 SwiftUI를 사용하여 기능적인 watch 앱을 빌드하는 방법을 안내합니다.

필수 조건

시작하기 전에 다음을 확인하세요:

Xcode 15 이상 (Mac 앱 스토어에서 다운로드)
macOS Sonoma 이상 (최신 watchOS SDK)
기존 Capacitor iOS 프로젝트 (실행) npx cap add ios 만약 아직도)
Apple Developer 계정 (개발을 위해 무료 계정이 작동합니다)

프로젝트 구조 개요

이 가이드를 완료한 후 프로젝트는 다음 구조를 가집니다:

디렉토리ios/
- 디렉토리App/
  - 디렉토리App/ (iOS 앱)
    …
  - App.xcodeproj
  - App.xcworkspace (프로젝트를 열기 위해 사용하세요)
  - Podfile
- 디렉토리MyWatch/ (새로운 watch 앱)
  - 디렉토리MyWatch/ (watch 앱 소스)
    MyWatchApp.swift
    ContentView.swift
    폴더Assets.xcassets/
    …
  - MyWatch.xcodeproj

1단계: Xcode에서 iOS 프로젝트를 열어보세요.

Xcode에서 Capacitor 프로젝트로 이동하세요. ios/App 폴더
열기 App.xcworkspace (아니오,) .xcodeprojXcode가 프로젝트를 인덱싱하는 것을 기다리세요.
Xcode에서 프로젝트를 인덱싱하는 것을 기다리세요.

Step 2: watchOS Target을 추가하세요

Xcode에서 File → New → Target…
템플릿 선택기에서
- watchOS watchOS 위쪽 탭
- 선택 앱
- 클릭 다음
시계 앱을 구성하세요:
- 제품 이름: MyWatch (또는 선호하는 이름)
- 팀: Apple Developer 팀을 선택하세요
- : iOS 앱과 일치해야 합니다 (예: : 앱 식별자 app.capgo)
- Bundle Identifier: __CAPGO_KEEP_0__ (예: app.capgo.myapp.watchkitapp)
- 언어: Swift
- 사용자 인터페이스: SwiftUI
- 워치 앱 유형: 앱 (기존 iOS 앱을 위한 앱이 아닌)
- 해제 알림 장면 포함 (만약 필요하지 않다면)
- 해제 복잡성 포함 (필요한 경우 제외)
클릭 완료
‘MyWatch’ 스키마 활성화할까요?'라는 메시지가 나올 때 클릭 활성화

3단계: 시계 앱 설정 구성

프로젝트 탐색기(왼쪽 사이드바)에서 프로젝트를 선택하세요(상단 blue 아이콘)
시계 대상(예: “MyWatch”)을 선택하세요
‘General’으로 이동하세요 일반 탭:
- 표시 이름: 앱 아이콘 아래에 표시되는 이름 (예: "My App")
- 패키지 식별자: .watchkitapp
- 버전: iOS 앱 버전과 일치
- 빌드: iOS 앱 빌드 번호와 일치
로 이동 인증 및 기능 탭:
- 켜기 자동으로 서명 관리
- 선택하세요 팀
- Xcode는 자동으로 배포 프로파일을 생성합니다.
설정 배포 정보:
- 최소 배포: watchOS 9.0 이상

4단계: Swift Package Manager를 통해 CapgoWatchSDK를 추가하세요

CapgoWatchSDK는 사용하기 쉬운 SDK를 제공합니다. WatchConnector __CAPGO_KEEP_0__

Xcode에서 파일 → 패키지 의존성 추가…

검색란에 입력:

https://github.com/Cap-go/capacitor-watch.git

엔터를 누르고 Xcode가 패키지를 가져올 때까지 기다리세요.
패키지를 설정하세요:
- 의존성 규칙: '다음 주요 버전까지' '8.0.0'
- 클릭 패키지 추가
어떤 제품을 추가할지 선택:
- 중요: Only select CapgoWatchSDK
- 앱에 추가하십시오. (e.g., “MyWatch”), iOS 앱이 아닌 클릭 패키지 추가
- 팁 팁

5단계: 시계 앱 구현

시계 앱을 만들겠습니다 code. 다음 파일을 생성하여 자동 생성된 파일을 대체하세요:

5.1 앱 진입점 만들기

수정 MyWatch/MyWatchApp.swift:

import SwiftUI
import CapgoWatchSDK

@main
struct MyWatchApp: App {
    init() {
        // Activate WatchConnectivity when app launches
        WatchConnector.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

5.2 메인 뷰 만들기

수정 MyWatch/ContentView.swift:

import SwiftUI
import CapgoWatchSDK

struct ContentView: View {
    // Observe the WatchConnector for automatic UI updates
    @ObservedObject var connector = WatchConnector.shared

    // Local state
    @State private var messageText = ""
    @State private var statusMessage = "Ready"

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                // Connection Status
                ConnectionStatusView(connector: connector)

                Divider()

                // Message Input
                TextField("Message", text: $messageText)
                    .textFieldStyle(.roundedBorder)

                // Send Buttons
                HStack {
                    Button("Send") {
                        sendMessage()
                    }
                    .disabled(!connector.isReachable || messageText.isEmpty)

                    Button("Request") {
                        sendWithReply()
                    }
                    .disabled(!connector.isReachable || messageText.isEmpty)
                }

                Divider()

                // Status
                Text(statusMessage)
                    .font(.caption)
                    .foregroundColor(.secondary)

                // Last Received Message
                if !connector.lastMessage.isEmpty {
                    VStack(alignment: .leading) {
                        Text("Last Message:")
                            .font(.caption)
                            .foregroundColor(.secondary)
                        Text(formatMessage(connector.lastMessage))
                            .font(.caption2)
                    }
                    .frame(maxWidth: .infinity, alignment: .leading)
                }
            }
            .padding()
        }
    }

    private func sendMessage() {
        connector.sendMessage(["text": messageText, "timestamp": Date().timeIntervalSince1970])
        statusMessage = "Message sent"
        messageText = ""
    }

    private func sendWithReply() {
        connector.sendMessage(["text": messageText, "needsReply": true]) { reply in
            DispatchQueue.main.async {
                statusMessage = "Reply: \(formatMessage(reply))"
            }
        }
        messageText = ""
    }

    private func formatMessage(_ message: [String: Any]) -> String {
        message.map { "\($0.key): \($0.value)" }.joined(separator: ", ")
    }
}

// Separate view for connection status
struct ConnectionStatusView: View {
    @ObservedObject var connector: WatchConnector

    var body: some View {
        HStack {
            Circle()
                .fill(connector.isReachable ? Color.green : Color.red)
                .frame(width: 12, height: 12)

            Text(connector.isReachable ? "Connected" : "Disconnected")
                .font(.headline)

            Spacer()

            if connector.isActivated {
                Image(systemName: "checkmark.circle.fill")
                    .foregroundColor(.green)
            }
        }
    }
}

#Preview {
    ContentView()
}

6단계: WatchConnectivity를 위한 iOS 앱 설정

iOS 앱도 WatchConnectivity 기능이 필요합니다.

프로젝트 탐색기에서 프로젝트를 선택하세요
Select your iOS 앱 목표 (시계 목표가 아닌)
다음으로 인증 및 기능 탭
클릭 + 기능
WatchConnectivity 기능을 추가하세요 WatchConnectivity (if available) or it may be added automatically
The Capacitor 플러그인은 iOS 측을 자동으로 처리하지만, Info.plist에 다음 항목이 포함되어야 합니다:
```
<key>WKCompanionAppBundleIdentifier</key>
<string>app.capgo.myapp.watchkitapp</string>
```

7단계: 빌드 및 실행

시뮬레이터에서 실행

Xcode 창 상단의 스킴 선택자에서 시계 스킴을 선택하십시오.
시계 시뮬레이터를 선택하십시오:
- 스킴 옆에 있는 기기 선택자 클릭
- Apple Watch 시뮬레이터를 선택하십시오 (예: “Apple Watch Series 9 (45mm)”
클릭하세요 실행 버튼 (▶️) 또는 Cmd + R
iOS 시뮬레이터는 아이폰과 애플 워치가 모두 실행됩니다.

실제 기기에서 실행

아이폰을 USB로 연결하세요
애플 워치가 아이폰과 pair되어 있어야 합니다.
워치 스케마를 선택하세요
실제 기기에서 사용할 애플 워치를 선택하세요
클릭 실행
처음 사용: 양쪽 기기에서 컴퓨터를 신뢰해야 할 수 있습니다

8단계: 통신 테스트

iPhone (Capacitor)에서 시계로

Capacitor 앱에서:

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

// Check connection
const info = await CapgoWatch.getInfo();
console.log('Watch reachable:', info.isReachable);

// Send a message
if (info.isReachable) {
  await CapgoWatch.sendMessage({
    data: { action: 'update', value: 'Hello from iPhone!' }
  });
}

시계에서 아이폰으로

시계 앱은 WatchConnector:

// Send message (fire and forget)
WatchConnector.shared.sendMessage(["action": "buttonTapped"])

// Send message with reply
WatchConnector.shared.sendMessage(["request": "getData"]) { reply in
    print("Got reply: \(reply)")
}

아이폰에서 메시지 처리

// Listen for messages from watch
await CapgoWatch.addListener('messageReceived', (event) => {
  console.log('Message from watch:', event.message);
  // { action: 'buttonTapped' }
});

// Handle messages that need a reply
await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
  console.log('Request from watch:', event.message);

  // Send reply back
  await CapgoWatch.replyToMessage({
    callbackId: event.callbackId,
    data: { status: 'success', items: ['item1', 'item2'] }
  });
});

고급: 사용자 지정 위임자로 더 많은 제어

더 많은 제어가 필요하다면 implement WatchConnectorDelegate:

import SwiftUI
import CapgoWatchSDK

class WatchHandler: WatchConnectorDelegate {
    func didReceiveMessage(_ message: [String: Any]) {
        print("Received: \(message)")
        // Handle incoming message
    }

    func didReceiveMessageWithReply(_ message: [String: Any],
                                     replyHandler: @escaping ([String: Any]) -> Void) {
        print("Received request: \(message)")
        // Process and send reply
        replyHandler(["status": "processed"])
    }

    func didReceiveApplicationContext(_ context: [String: Any]) {
        print("Context updated: \(context)")
    }

    func didReceiveUserInfo(_ userInfo: [String: Any]) {
        print("User info received: \(userInfo)")
    }

    func reachabilityDidChange(_ isReachable: Bool) {
        print("Reachability changed: \(isReachable)")
    }

    func activationDidComplete(with state: WCSessionActivationState) {
        print("Activation completed: \(state.rawValue)")
    }
}

// In your app setup:
let handler = WatchHandler()
WatchConnector.shared.delegate = handler
WatchConnector.shared.activate()

문제 해결

시계 앱이 시계에 나타나지 않습니다.

__CAPGO_KEEP_0__ ID가 정확히 연결되어 있는지 확인하십시오 (시계 앱 __CAPGO_KEEP_0__ ID는 iOS 앱 __CAPGO_KEEP_0__ ID와 같아야 합니다.) .watchkitapp)
iOS 앱과 시계 앱이 동일한 팀으로 서명되어 있는지 확인하십시오.
물리적 기기에서: iPhone에서 시계 앱을 열고 → My Watch → 앱을 찾으십시오 → 앱을 켜십시오.

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

두 앱 모두 WCSession이 활성화되어 있는지 확인하십시오.
메시지를 보내기 전에 isReachable 보장된 전달을 위해 사용하십시오.
Messages Not Being Received transferUserInfo 대신 sendMessage
다른 기기에서 메시지를 보내기 전에 리스너가 등록되어 있는지 확인하세요

”Session Not Activated” Error

Call WatchConnector.shared.activate() 앱 라이프 사이클의 시작 단계에서 호출하세요
iOS에서 플러그인은 자동으로 활성화되므로 플러그인을 임포트했는지 확인하세요
iOS 대상에 WatchConnectivity 기능이 추가되어 있는지 확인하세요

CapgoWatchSDK와 관련된 빌드 오류

Ensure the package is added to the watch targetiOS가 아닌 대상
빌드 폴더를 정리하세요: 제품 → 빌드 폴더 정리 (Cmd + Shift + K)
패키지 캐시를 초기화하세요: 파일 → 패키지 → 패키지 캐시 초기화

심уля터 문제

심уля터를 초기화하세요: 장치 → 모든 콘텐츠와 설정 삭제
iOS 및 watchOS 심уля터가 호환되는 pairs여야 합니다.
두 심уля터 모두 동작해야 통신이 가능합니다.

다음 단계

API Reference - API 문서의 모든 내용
통신 패턴 - 각 방법을 사용할 때
예제 앱 - 완전한 작동 예제