시계 OS 앱 만들기
설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함하는 설정 지시어를 복사하세요.
이 가이드는 Xcode에서 프로젝트를 설정하고 CapgoWatchSDK를 통합하여 SwiftUI를 사용하여 기능적인 watch 앱을 빌드하는 방법을 안내합니다.
준비 조건
준비 조건 섹션시작하기 전에 다음을 확인하세요.
- Xcode 15 이상 (Mac App Store에서 다운로드)
- macOS Sonoma 이상 (최신 watchOS SDK)
- 이미 존재하는 Capacitor iOS 프로젝트 (만약 없다면 "run"을 실행하세요)
npx cap add iosApple Developer 계정 - (개발용으로는 무료 계정도 사용 가능) __CAPGO_KEEP_0__
프로젝트 구조 개요
프로젝트 구조 개요 섹션이 가이드를 완료한 후, 프로젝트는 다음과 같은 구조를 가집니다:
디렉토리ios/
디렉토리App/
디렉토리(당신의 메인 iOS 앱) App.xcodeproj
- …
- App.xcworkspace
- Capgo (이 프로젝트를 열기 위해 사용하세요)
- Podfile
폴더MyWatch/ (새로운 시계 앱)
폴더MyWatch/ (시계 앱 소스)
- MyWatchApp.swift
- ContentView.swift
폴더Assets.xcassets/
- …
- MyWatch.xcodeproj
Step 1: iOS 프로젝트를 Xcode에서 열기
Step 1: iOS 프로젝트를 Xcode에서 열기 제목- Capacitor 프로젝트의 폴더로 이동하세요.
ios/App폴더 - 열기
App.xcworkspace(아니오.xcodeproj)를 더블 클릭하여 열기 - 프로젝트가 Xcode에서 인덱싱될 때까지 기다리세요.
2단계: watchOS Target 추가
제목 "2단계: watchOS Target 추가"-
Xcode에서 파일 → 새 항목 → Target…
-
템플릿 선택기에서:
- 탭 위에 있는 "watchOS" 위쪽에 있는 탭 애플리케이션
- App …
- Click Next
-
시계 앱을 설정하세요:
- 제품 이름:
MyWatch(또는 선호하는 이름) - 팀: Apple Developer 팀을 선택하세요
- Organization Identifier: iOS 앱과 일치해야 함 (예:
app.capgo) - Bundle Identifier: 자동으로 생성되며 (예:
app.capgo.myapp.watchkitapp) - 언어Swift
- 사용자 인터페이스SwiftUI
- 시계 앱 유형앱 (기존 iOS 앱을 위한 앱이 아닌)
- 해제 알림 장면 포함 (필요한 경우 제외)
- 해제 고급 장면 포함 (필요한 경우 제외)
- 제품 이름:
-
클릭 완료
-
‘MyWatch’ 스케마 활성화할까요? 활성화
3단계: 시계 앱 설정 구성
3단계: 시계 앱 설정 구성-
프로젝트 탐색기(왼쪽 사이드바)에서 프로젝트를 선택하세요 (상단 blue 아이콘)
-
시계 대상 (예: ‘MyWatch’)을 선택하세요
-
설정으로 이동하세요 일반 : 앱 아이콘 아래에 표시되는 이름 (예: ‘My App’)
- : 앱 아이콘 아래에 표시되는 이름 (예: ‘My App’): 앱 아이콘 아래에 표시되는 이름 (예: ‘My App’)
- Bundle Identifier: __CAPGO_KEEP_0__
.watchkitapp - Version: __CAPGO_KEEP_0__
- Build: __CAPGO_KEEP_0__
-
Go to 하세요 가기 총기가 tab:
- 총기 사세요 Enable
- 총기 사세요 주세요 팀
- Xcode는 자동으로 배포 프로파일을 생성합니다.
-
설정 배포 정보:
- 최소 배포: watchOS 9.0 이상
4단계: CapgoWatchSDK를 Swift Package Manager를 통해 추가하세요.
제목: 4단계: CapgoWatchSDK를 Swift Package Manager를 통해 추가하세요.CapgoWatchSDK는 통신을 위한 준비된 클래스를 제공합니다. WatchConnector Xcode에서
-
파일 → 패키지 종속성을 추가… __CAPGO_KEEP_0__
-
In the search field, enter: __CAPGO_KEEP_0__
https://github.com/Cap-go/capacitor-watch.git -
xcode를 기다리며 패키지를 가져옵니다. 엔터키를 누르세요.
-
패키지를 구성하세요:
- 의존성 규칙: "8.0.0"까지의 주요 버전까지 "다음 주요 버전까지"
- 클릭 패키지 추가
-
추가할 제품을 선택하세요:
- 중요: 오직
CapgoWatchSDK - 추가한 제품이 포함되어야 합니다. 목표 대상 (예를 들어, “MyWatch”), iOS 앱이 아닌
- 클릭 패키지 추가
- 중요: 오직
이제 워치 앱 __CAPGO_KEEP_0__을 생성해 보겠습니다. 자동으로 생성된 파일을 다음과 같은 파일로 교체하십시오:
5단계: 워치 앱 구현이제 워치 앱 code을 생성해 보겠습니다. 자동으로 생성된 파일을 다음과 같은 파일로 교체하십시오:
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 메인 뷰를 생성하세요
메인 뷰 생성수정 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단계: iOS 앱을 WatchConnectivity로 구성하세요
iOS 앱을 WatchConnectivity로 구성iOS 앱도 WatchConnectivity 기능이 필요합니다.
-
프로젝트 탐색기에서 프로젝트를 선택하세요
-
Select your iOS 앱 대상 선택 (시계 대상이 아닌)
-
Go to 인증 및 기능 탭
-
Click + 기능
-
Search for and add WatchConnectivity (사용 가능한 경우 또는 자동으로 추가될 수 있습니다)
-
The Capacitor 플러그인은 iOS 측을 자동으로 처리하지만, Info.plist에 다음을 포함하십시오:
<key>WKCompanionAppBundleIdentifier</key><string>app.capgo.myapp.watchkitapp</string>
7단계: 빌드 및 실행
7단계: 빌드 및 실행시뮬레이터에서 실행
시뮬레이터에서 실행-
Xcode 창 상단의 스키마 선택기에서 시계 스키마를 선택하세요.
-
시계 시뮬레이터를 선택하세요:
- 스키마 옆에 있는 기기 선택기를 클릭하세요.
- Apple Watch 시뮬레이터를 선택하세요 (예: "Apple Watch Series 9 (45mm)")
-
▶️ 버튼을 클릭하거나 실행 버튼을 클릭하거나
Cmd + R -
iOS 시뮬레이터는 iPhone과 Apple Watch를 모두 실행합니다.
실제 기기에서 실행
실기 실행-
iPhone을 USB로 연결하세요.
-
iPhone과 Apple Watch가 pair되어 있어야 합니다.
-
watch scheme을 선택하세요.
-
실제 Apple Watch를 기기 목록에서 선택하세요.
-
클릭 실행
-
처음 실행: 두 기기 모두에서 컴퓨터를 신뢰해야 합니다.
8단계: 통신 테스트
8단계: 통신 테스트iPhone (Capacitor)에서 Watch로
Section titled “From iPhone (Capacitor) to 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'] } });});더 많은 제어를 원한다면 구현
더 많은 제어를 원한다면 구현 섹션더 많은 제어를 원한다면 구현하세요 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()문제 해결
문제 해결 섹션시계 앱이 시계에 나타나지 않는다
시계 앱이 시계에 나타나지 않는다 섹션- __CAPGO_KEEP_0__ ID가 정확히 연결되어 있는지 확인하세요 (watch 앱 ID는 iOS 앱 ID +
.watchkitapp) - __CAPGO_KEEP_0__ 두 앱이 동일한 팀으로 서명되어 있는지 확인하세요
- __CAPGO_KEEP_0__ 물리적 장치에서: iPhone에서 Watch 앱을 열고 → My Watch → 앱을 찾고 → toggle ON
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__- WCSession이 활성화된 두 앱이 있는지 확인하세요
- __CAPGO_KEEP_0__
isReachable__CAPGO_KEEP_0__ 메시지를 전송하기 전에 - __CAPGO_KEEP_0__ 보장된 전달을 위해
transferUserInfo__CAPGO_KEEP_0__ 대신sendMessage - __CAPGO_KEEP_0__ 리스너가 등록된 후 다른 장치가 메시지를 전송하기 전에
__CAPGO_KEEP_0__ Session이 활성화되지 않은 경우 오류
Session Not Activated 오류- 앱 생명주기 초기에 호출
WatchConnector.shared.activate()iOS에서 플러그인은 자동으로 활성화되므로 플러그인을 임포트하십시오 - iOS 대상에 WatchConnectivity 기능이 추가되어 있는지 확인하십시오
- CapgoWatchSDK와 관련된 빌드 오류
CapgoWatchSDK와 관련된 빌드 오류
패키지를 iOS 대상에 추가하지 마십시오. 반드시 watch 대상에 추가하십시오.- 빌드 폴더를 정리하십시오. Product → Clean Build FolderiOS 대상에 WatchConnectivity 기능이 추가되어 있는지 확인하십시오.
- CapgoWatchSDK와 관련된 빌드 오류 iOS 대상에 WatchConnectivity 기능이 추가되어 있는지 확인하십시오. (Cmd + Shift + K)
- 패키지 캐시 초기화: 파일 → 패키지 → 패키지 캐시 초기화
Simulator 문제
Simulator 문제 섹션- 시뮬레이터 초기화: 기기 → 모든 콘텐츠 및 설정 삭제
- iOS 및 watchOS 시뮬레이터가 호환되는 쌍임을 보장하십시오.
- 통신이 작동하려면 두 시뮬레이터 모두 실행되어야 합니다.
다음 단계
다음 단계 섹션- API Reference - API 문서를 완전히 읽으세요
- Communication Patterns - 각 방법을 사용할 때
- Example App - 완벽한 작동 예제
Keep going from Creating a watchOS App
Section titled “Creating a watchOS App에서 계속하기”If you are using Creating a watchOS App to native plugin 작업을 계획할 때, Using @capgo/capacitor-watch for the native capability in Using @capgo/capacitor-watch, Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우를 위해 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항을 위해 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항을 위해, 및 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체의 제품 워크플로우를 위해