watchOS 앱 만들기
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
이 가이드는 watchOS 컴패니언 앱을 처음부터 만드는 방법을 안내합니다. Xcode에서 프로젝트 설정, CapgoWatchSDK 통합, SwiftUI로 기능적인 워치 앱 구축까지 포함합니다.
대상: Wear OS, 사용하세요 Wear OS 앱 만들기 대신 사용하세요.
사전 요구사항
“사전 준비 사항” 섹션시작하기 전에 다음 사항을 확인하세요:
- Xcode 15 이상 (Mac App Store에서 다운로드)
- macOS Sonoma 이상 (최신 watchOS SDK용)
- 기존 Capacitor iOS 프로젝트 (실행
npx cap add ios하지 않았다면) - Apple Developer 계정 (개발에는 무료 계정으로 충분합니다)
프로젝트 구조 개요
“프로젝트 구조 개요” 섹션이 가이드를 완료하면 프로젝트 구조는 다음과 같습니다:
디렉토리ios/
디렉토리App/
디렉토리App/ (메인 iOS 앱)
- …
- App.xcodeproj
- App.xcworkspace (프로젝트를 열 때 사용)
- Podfile
디렉토리MyWatch/ (새 워치 앱)
디렉토리MyWatch/ (워치 앱 소스)
- MyWatchApp.swift
- ContentView.swift
디렉토리Assets.xcassets/
- …
- MyWatch.xcodeproj
1단계: Xcode에서 iOS 프로젝트 열기
“1단계: Xcode에서 iOS 프로젝트 열기” 섹션- Capacitor 프로젝트의
ios/App폴더 - 열기
App.xcworkspace(아님.xcodeproj)를 더블클릭하여 - Xcode가 프로젝트를 인덱싱할 때까지 기다리세요
2단계: watchOS 타겟 추가
“2단계: watchOS 타겟 추가” 섹션-
Xcode에서 다음으로 이동하세요: 파일 → 새로 만들기 → 대상…
-
템플릿 선택기에서:
- 선택 watchOS 상단 탭
- 선택 앱
- 클릭 다음
-
watch 앱 구성:
- 제품 이름:
MyWatch(또는 원하는 이름) - 팀: Apple Developer 팀을 선택하세요
- 조직 식별자: iOS 앱과 일치해야 합니다 (예:
app.capgo) - Bundle Identifier: 자동으로 생성됩니다 (예:
app.capgo.myapp.watchkitapp) - 언어: Swift
- 사용자 인터페이스: SwiftUI
- Watch 앱 유형: App (기존 iOS App용 App 아님)
- 체크 해제 Notification Scene 포함 (필요한 경우가 아니면)
- 체크 해제 Complication 포함 (필요한 경우가 아니면)
- 제품 이름:
-
클릭 완료
-
“Activate ‘MyWatch’ scheme?” 프롬프트가 뜨면, 클릭 활성화
3단계: Watch App 설정 구성
“3단계: Watch App 설정 구성” 섹션-
Project Navigator(왼쪽 사이드바)에서 프로젝트(상단의 파란색 아이콘)를 선택하세요
-
targets 목록에서 watch target(예: “MyWatch”)을 선택하세요
-
다음으로 이동하세요: 일반 탭:
- 표시 이름: 앱 아이콘 아래에 표시되는 이름(예: “My App”)
- Bundle Identifier: 다음으로 끝나야 합니다
.watchkitapp - 버전: iOS 앱 버전과 일치시키세요
- 빌드: iOS 앱 빌드 번호와 일치
-
다음으로 이동: Signing & Capabilities 탭:
- 활성화 Signing 자동 관리
- 선택하세요 팀
- Xcode가 프로비저닝 프로필을 자동으로 생성합니다
-
설정 배포 정보:
- 최소 배포 버전: watchOS 9.0 이상
4단계: Swift Package Manager로 CapgoWatchSDK 추가
“4단계: Swift Package Manager를 통해 CapgoWatchSDK 추가” 섹션CapgoWatchSDK는 바로 사용할 수 있는 WatchConnector 클래스를 제공합니다.
-
Xcode에서 다음으로 이동하세요: 파일 → 패키지 의존성 추가…
-
검색 필드에 다음을 입력하세요:
https://github.com/Cap-go/capacitor-watch.git -
Enter 키를 누르고 Xcode가 패키지를 가져올 때까지 기다립니다
-
패키지 구성:
- 의존성 규칙: “8.0.0”으로 “다음 메이저 버전까지”
- 클릭 패키지 추가
-
추가할 제품을 선택하세요:
- 중요: 다음만 선택하세요
CapgoWatchSDK - 다음에 추가되었는지 확인하세요 watch 대상 (예: “MyWatch”), iOS 앱이 아닙니다
- 클릭 패키지 추가
- 중요: 다음만 선택하세요
5단계: Watch 앱 구현
“5단계: Watch 앱 구현” 섹션이제 watch app code을(를) 만들어 보겠습니다. 자동 생성된 파일을 다음 내용으로 교체하세요:
5.1 앱 진입점 생성
“5.1 앱 진입점 생성” 섹션편집 MyWatch/MyWatchApp.swift:
import SwiftUIimport CapgoWatchSDK
@mainstruct MyWatchApp: App { init() { // Activate WatchConnectivity when app launches WatchConnector.shared.activate() }
var body: some Scene { WindowGroup { ContentView() } }}5.2 메인 뷰 생성
“5.2 메인 뷰 생성” 섹션편집 MyWatch/ContentView.swift:
import SwiftUIimport 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 statusstruct 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 앱 설정
“단계 6: WatchConnectivity를 위한 iOS 앱 구성” 섹션iOS 앱에도 WatchConnectivity 기능이 필요합니다.
-
프로젝트 선택
-
선택하세요 iOS 앱 타깃 (워치 타깃이 아님)
-
다음으로 이동: Signing & Capabilities 탭
-
클릭 + Capability 추가
-
검색하여 추가 WatchConnectivity (사용 가능한 경우) 또는 자동으로 추가될 수 있습니다
-
Capacitor 플러그인이 iOS 쪽을 자동으로 처리하지만, Info.plist에 다음 항목이 있는지 확인하세요:
<key>WKCompanionAppBundleIdentifier</key><string>app.capgo.myapp.watchkitapp</string>
7단계: 빌드 및 실행
“7단계: 빌드 및 실행” 섹션시뮬레이터에서 실행
“시뮬레이터에서 실행” 섹션-
스키마 선택기(Xcode 창 상단)에서 워치 스키마를 선택하세요
-
워치 시뮬레이터를 선택하세요:
- 스키마 옆의 디바이스 선택기를 클릭하세요
- Apple Watch 시뮬레이터를 선택하세요 (예: “Apple Watch Series 9 (45mm)”)
-
Members 섹션에서 실행 버튼(▶️)을 클릭하거나
Cmd + R -
iOS 시뮬레이터가 iPhone과 Apple Watch 모두와 함께 실행됩니다
실제 기기에서 실행
“실제 디바이스에서 실행” 섹션-
USB로 iPhone 연결
-
해당 iPhone과 Apple Watch가 페어링되어 있는지 확인
-
워치 스킴 선택
-
기기 목록에서 물리적 Apple Watch 선택
-
클릭 실행
-
최초 사용 시: 두 기기 모두에서 컴퓨터를 신뢰하도록 설정해야 할 수 있습니다
8단계: 통신 테스트
“8단계: 통신 테스트” 섹션iPhone (Capacitor)에서 Watch로
“iPhone (Capacitor)에서 Watch로” 섹션Capacitor 앱에서:
import { CapgoWatch } from '@capgo/capacitor-watch';
// Check connectionconst info = await CapgoWatch.getInfo();console.log('Watch reachable:', info.isReachable);
// Send a messageif (info.isReachable) { await CapgoWatch.sendMessage({ data: { action: 'update', value: 'Hello from iPhone!' } });}Watch에서 iPhone으로
“Watch에서 iPhone으로” 섹션Watch 앱은 다음을 사용합니다 WatchConnector:
// Send message (fire and forget)WatchConnector.shared.sendMessage(["action": "buttonTapped"])
// Send message with replyWatchConnector.shared.sendMessage(["request": "getData"]) { reply in print("Got reply: \(reply)")}iPhone에서 메시지 처리하기
“iPhone에서 메시지 처리하기” 섹션// Listen for messages from watchawait CapgoWatch.addListener('messageReceived', (event) => { console.log('Message from watch:', event.message); // { action: 'buttonTapped' }});
// Handle messages that need a replyawait 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'] } });});고급: 더 세밀한 제어를 위한 Custom Delegate
“고급: 더 많은 제어를 위한 Custom Delegate” 섹션더 많은 제어가 필요하면 다음을 구현하세요 WatchConnectorDelegate:
import SwiftUIimport 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 = handlerWatchConnector.shared.activate()문제 해결
“문제 해결” 섹션Watch에 Watch App이 나타나지 않을 때
“Watch 앱이 Watch에 표시되지 않음” 섹션- Bundle ID가 올바르게 연결되었는지 확인하세요 (watch app bundle ID는 iOS app bundle ID +
.watchkitapp) - 두 앱 모두 같은 팀으로 서명되었는지 확인하세요
- 실제 기기에서: iPhone에서 Watch 앱 열기 → My Watch → 앱을 찾을 때까지 스크롤 → ON으로 전환
메시지가 수신되지 않을 때
“메시지가 수신되지 않음” 섹션- 양쪽 앱에서 WCSession이 활성화되어 있는지 확인하세요
- 체크 항목
isReachable메시지를 보내기 전에 - 메시지 전달을 보장하려면 다음을 사용하세요
transferUserInfo를 전달하고sendMessage - 상대 기기에서 메시지를 보내기 전에 리스너가 등록되어 있는지 확인하세요
“Session Not Activated” 에러
“Session Not Activated” 에러 섹션- 호출하세요
WatchConnector.shared.activate()앱 라이프사이클 초기에 - iOS에서는 플러그인이 자동으로 활성화되므로, 플러그인이 import되었는지 확인하세요
- iOS target에 WatchConnectivity capability가 추가되어 있는지 확인하세요
CapgoWatchSDK 빌드 에러
“CapgoWatchSDK 빌드 오류” 섹션- 패키지가 다음 항목에 추가되었는지 확인하세요: watch 대상(iOS target이 아님)
- 빌드 폴더 정리: 제품 → Clean Build Folder (Cmd + Shift + K)
- 패키지 캐시 초기화: File → Packages → Reset Package Caches
Simulator 관련 이슈
“Simulator Issues” 섹션- 시뮬레이터를 초기화하세요: Device → 모든 콘텐츠 및 설정 지우기
- iOS와 watchOS 시뮬레이터가 호환되는 쌍인지 확인하세요
- 통신이 작동하려면 두 시뮬레이터가 모두 실행 중이어야 합니다
다음 단계
“다음 단계” 섹션- Wear OS 앱 만들기 Android 워치의 경우
- API 레퍼런스 - 완전한 API 문서
- 통신 패턴 - 각 방법의 사용 시점
- 예제 앱 - 전체 동작 예시
watchOS App 만들기 다음 단계
“watchOS 앱 만들기”에서 계속하기 섹션사용 중이라면 watchOS 앱 만들기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-watch 사용하기 @capgo/capacitor-watch 사용하기에서 네이티브 기능을 위해, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.