본문 바로가기

watchOS 앱 만들기

GitHub

이 가이드는 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 프로젝트 열기” 섹션
  1. Capacitor 프로젝트의 ios/App 폴더
  2. 열기 App.xcworkspace (아님 .xcodeproj)를 더블클릭하여
  3. Xcode가 프로젝트를 인덱싱할 때까지 기다리세요

2단계: watchOS 타겟 추가

“2단계: watchOS 타겟 추가” 섹션
  1. Xcode에서 다음으로 이동하세요: 파일 → 새로 만들기 → 대상…

  2. 템플릿 선택기에서:

    • 선택 watchOS 상단 탭
    • 선택 앱
    • 클릭 다음
  3. watch 앱 구성:

    • 제품 이름: MyWatch (또는 원하는 이름)
    • 팀: Apple Developer 팀을 선택하세요
    • 조직 식별자: iOS 앱과 일치해야 합니다 (예: app.capgo)
    • Bundle Identifier: 자동으로 생성됩니다 (예: app.capgo.myapp.watchkitapp)
    • 언어: Swift
    • 사용자 인터페이스: SwiftUI
    • Watch 앱 유형: App (기존 iOS App용 App 아님)
    • 체크 해제 Notification Scene 포함 (필요한 경우가 아니면)
    • 체크 해제 Complication 포함 (필요한 경우가 아니면)
  4. 클릭 완료

  5. “Activate ‘MyWatch’ scheme?” 프롬프트가 뜨면, 클릭 활성화

3단계: Watch App 설정 구성

“3단계: Watch App 설정 구성” 섹션
  1. Project Navigator(왼쪽 사이드바)에서 프로젝트(상단의 파란색 아이콘)를 선택하세요

  2. targets 목록에서 watch target(예: “MyWatch”)을 선택하세요

  3. 다음으로 이동하세요: 일반 탭:

    • 표시 이름: 앱 아이콘 아래에 표시되는 이름(예: “My App”)
    • Bundle Identifier: 다음으로 끝나야 합니다 .watchkitapp
    • 버전: iOS 앱 버전과 일치시키세요
    • 빌드: iOS 앱 빌드 번호와 일치
  4. 다음으로 이동: Signing & Capabilities 탭:

    • 활성화 Signing 자동 관리
    • 선택하세요 팀
    • Xcode가 프로비저닝 프로필을 자동으로 생성합니다
  5. 설정 배포 정보:

    • 최소 배포 버전: watchOS 9.0 이상

4단계: Swift Package Manager로 CapgoWatchSDK 추가

“4단계: Swift Package Manager를 통해 CapgoWatchSDK 추가” 섹션

CapgoWatchSDK는 바로 사용할 수 있는 WatchConnector 클래스를 제공합니다.

  1. Xcode에서 다음으로 이동하세요: 파일 → 패키지 의존성 추가…

  2. 검색 필드에 다음을 입력하세요:

    https://github.com/Cap-go/capacitor-watch.git
  3. Enter 키를 누르고 Xcode가 패키지를 가져올 때까지 기다립니다

  4. 패키지 구성:

    • 의존성 규칙: “8.0.0”으로 “다음 메이저 버전까지”
    • 클릭 패키지 추가
  5. 추가할 제품을 선택하세요:

    • 중요: 다음만 선택하세요 CapgoWatchSDK
    • 다음에 추가되었는지 확인하세요 watch 대상 (예: “MyWatch”), iOS 앱이 아닙니다
    • 클릭 패키지 추가

이제 watch app code을(를) 만들어 보겠습니다. 자동 생성된 파일을 다음 내용으로 교체하세요:

편집 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()
}
}
}

편집 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 앱 설정

“단계 6: WatchConnectivity를 위한 iOS 앱 구성” 섹션

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

  1. 프로젝트 선택

  2. 선택하세요 iOS 앱 타깃 (워치 타깃이 아님)

  3. 다음으로 이동: Signing & Capabilities 탭

  4. 클릭 + Capability 추가

  5. 검색하여 추가 WatchConnectivity (사용 가능한 경우) 또는 자동으로 추가될 수 있습니다

  6. Capacitor 플러그인이 iOS 쪽을 자동으로 처리하지만, Info.plist에 다음 항목이 있는지 확인하세요:

    <key>WKCompanionAppBundleIdentifier</key>
    <string>app.capgo.myapp.watchkitapp</string>

7단계: 빌드 및 실행

“7단계: 빌드 및 실행” 섹션

시뮬레이터에서 실행

“시뮬레이터에서 실행” 섹션
  1. 스키마 선택기(Xcode 창 상단)에서 워치 스키마를 선택하세요

  2. 워치 시뮬레이터를 선택하세요:

    • 스키마 옆의 디바이스 선택기를 클릭하세요
    • Apple Watch 시뮬레이터를 선택하세요 (예: “Apple Watch Series 9 (45mm)”)
  3. Members 섹션에서 실행 버튼(▶️)을 클릭하거나 Cmd + R

  4. iOS 시뮬레이터가 iPhone과 Apple Watch 모두와 함께 실행됩니다

  1. USB로 iPhone 연결

  2. 해당 iPhone과 Apple Watch가 페어링되어 있는지 확인

  3. 워치 스킴 선택

  4. 기기 목록에서 물리적 Apple Watch 선택

  5. 클릭 실행

  6. 최초 사용 시: 두 기기 모두에서 컴퓨터를 신뢰하도록 설정해야 할 수 있습니다

iPhone (Capacitor)에서 Watch로

“iPhone (Capacitor)에서 Watch로” 섹션

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

Watch 앱은 다음을 사용합니다 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)")
}

iPhone에서 메시지 처리하기

“iPhone에서 메시지 처리하기” 섹션
// 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'] }
});
});

고급: 더 세밀한 제어를 위한 Custom Delegate

“고급: 더 많은 제어를 위한 Custom Delegate” 섹션

더 많은 제어가 필요하면 다음을 구현하세요 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()

Watch에 Watch App이 나타나지 않을 때

“Watch 앱이 Watch에 표시되지 않음” 섹션
  1. Bundle ID가 올바르게 연결되었는지 확인하세요 (watch app bundle ID는 iOS app bundle ID + .watchkitapp)
  2. 두 앱 모두 같은 팀으로 서명되었는지 확인하세요
  3. 실제 기기에서: iPhone에서 Watch 앱 열기 → My Watch → 앱을 찾을 때까지 스크롤 → ON으로 전환

메시지가 수신되지 않을 때

“메시지가 수신되지 않음” 섹션
  1. 양쪽 앱에서 WCSession이 활성화되어 있는지 확인하세요
  2. 체크 항목 isReachable 메시지를 보내기 전에
  3. 메시지 전달을 보장하려면 다음을 사용하세요 transferUserInfo 를 전달하고 sendMessage
  4. 상대 기기에서 메시지를 보내기 전에 리스너가 등록되어 있는지 확인하세요

“Session Not Activated” 에러

“Session Not Activated” 에러 섹션
  1. 호출하세요 WatchConnector.shared.activate() 앱 라이프사이클 초기에
  2. iOS에서는 플러그인이 자동으로 활성화되므로, 플러그인이 import되었는지 확인하세요
  3. iOS target에 WatchConnectivity capability가 추가되어 있는지 확인하세요

CapgoWatchSDK 빌드 에러

“CapgoWatchSDK 빌드 오류” 섹션
  1. 패키지가 다음 항목에 추가되었는지 확인하세요: watch 대상(iOS target이 아님)
  2. 빌드 폴더 정리: 제품 → Clean Build Folder (Cmd + Shift + K)
  3. 패키지 캐시 초기화: File → Packages → Reset Package Caches

Simulator 관련 이슈

“Simulator Issues” 섹션
  1. 시뮬레이터를 초기화하세요: Device → 모든 콘텐츠 및 설정 지우기
  2. iOS와 watchOS 시뮬레이터가 호환되는 쌍인지 확인하세요
  3. 통신이 작동하려면 두 시뮬레이터가 모두 실행 중이어야 합니다

사용 중이라면 watchOS 앱 만들기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-watch 사용하기 @capgo/capacitor-watch 사용하기에서 네이티브 기능을 위해, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.