Petnow시작하기
Petnow iOS SDK 설치 및 초기 설정 가이드.
개요
이 가이드는 Petnow iOS SDK를 프로젝트에 설치하고 초기 설정하는 방법을 단계별로 안내합니다.
사전 준비사항
시작하기 전에 다음을 준비해주세요:
- iOS 16.0 이상을 타겟으로 하는 Xcode 프로젝트
- Xcode 16.0 이상
- Petnow API 키 (발급 받지 않았다면 support@petnow.io로 문의)
1단계: SDK 설치
Petnow iOS SDK는 AWS CodeArtifact를 통해 배포됩니다.
AWS CLI 설치
다음 링크에서 AWS CLI를 설치하세요: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
Petify Console에서 자격 증명 발급
Petify Console에서 AWS 자격 증명을 발급하고, 제공된 값으로 환경 변수를 설정하세요:
export AWS_ACCESS_KEY_ID=<Petify Console에서 제공>
export AWS_SECRET_ACCESS_KEY=<Petify Console에서 제공>
export AWS_DEFAULT_REGION=<Petify Console에서 제공>
export PETNOW_CODEARTIFACT_DOMAIN=<Petify Console에서 제공>
export PETNOW_AWS_ACCOUNT_ID=<Petify Console에서 제공>
export PETNOW_IOS_SDK_REPOSITORY=<Petify Console에서 제공>Swift Package Manager (AWS CodeArtifact)
프로젝트 타입에 따라 하나를 선택하여 진행하세요:
옵션 A: Package.swift 프로젝트
Package.swift 파일이 있는 프로젝트에서는 다음 명령만 실행하면 됩니다:
- 프로젝트 루트 디렉토리로 이동:
cd /path/to/your-project # Package.swift가 있는 디렉토리- AWS CodeArtifact 로그인:
aws codeartifact login --tool swift \
--domain $PETNOW_CODEARTIFACT_DOMAIN \
--domain-owner $PETNOW_AWS_ACCOUNT_ID \
--repository $PETNOW_IOS_SDK_REPOSITORY- 성공 확인:
# 성공 시 출력:
Successfully configured credentials for codeartifact-DOMAIN-ACCOUNT_ID-REPOSITORY
# Registry 파일 확인:
cat ~/.swiftpm/configuration/registries.json참고: 인증 토큰은 12시간 유효합니다. 만료 시 로그인 명령을 다시 실행하세요.
옵션 B: Xcode Workspace
Xcode에서 패키지 추가
- Xcode에서 프로젝트를 엽니다
- File > Add Packages... 선택
- 구성된 CodeArtifact 저장소에서
petnow.ui패키지를 검색 - Add Package 클릭
중요: 패키지 이름을 입력 후 enter를 눌러야 합니다. 누르지 않으면 검색되지 않습니다.
설치 확인
패키지가 성공적으로 추가되면 프로젝트 네비게이터의 Package Dependencies 섹션에서 확인할 수 있습니다.
2단계: 프로젝트 설정
Info.plist 권한 추가
SDK가 카메라를 사용하려면 Info.plist에 권한 설명을 추가해야 합니다.
"Privacy - Camera Usage Description" 혹은 "NSCameraUsageDescription" 키를 추가하고, 카메라 사용 목적을 설명하는 문자열을 입력합니다.
필수 권한
<!-- 카메라 접근 권한 (필수) -->
<key>NSCameraUsageDescription</key>
<string>반려동물 탐지 및 식별을 위해 카메라 접근이 필요합니다.</string>중요: 권한 설명이 없으면 카메라 접근 시 앱이 크래시됩니다.
모듈 임포트
import PetnowUI3단계: 캡처 세션 생성
필수: 카메라 초기화 전에 반드시 서버에서 캡처 세션을 생성하고 captureSessionId를 받아와야 합니다.
// 서버에서 captureSessionId를 받아옵니다
// (서버는 Petnow Server API의 createCaptureSession을 호출)
let captureSessionId: UUID = await yourServerAPI.createCaptureSession(
species: "DOG",
purpose: "PET_PROFILE_REGISTRATION"
)Server API: captureSessionId는 서버에서 Petnow Server API를 통해 생성합니다. 클라이언트에서 직접 생성하지 않습니다.
자세한 세션 개념은 UI 모듈 개요를 참고하세요.
4단계: 카메라 초기화
PetnowUI의 CameraViewModel을 사용하여 카메라를 초기화합니다. API 키와 환경 설정은 LicenseInfo를 통해 전달됩니다.
import SwiftUI
import PetnowUI
struct PetCameraView: View {
@StateObject private var cameraViewModel: CameraViewModel
private let captureSessionId: UUID // 서버에서 받은 세션 ID
init(captureSessionId: UUID) {
self.captureSessionId = captureSessionId
_cameraViewModel = StateObject(wrappedValue: CameraViewModel(
species: .dog, // .dog 또는 .cat
cameraPurpose: .forRegisterFromProfile // 촬영 목적
))
}
var body: some View {
CameraView(viewModel: cameraViewModel)
.task {
await initializeCamera()
}
}
private func initializeCamera() async {
do {
try await cameraViewModel.initializeCamera(
licenseInfo: LicenseInfo(
apiKey: "YOUR_API_KEY",
isDebugMode: false
),
initialPosition: .back,
captureSessionId: captureSessionId
) { result in
// 촬영 결과 처리
print("촬영 완료: \(result)")
}
} catch {
print("카메라 초기화 실패: \(error)")
}
}
private func isDebugBuild() -> Bool {
#if DEBUG
return true
#else
return false
#endif
}
}LicenseInfo 파라미터
LicenseInfo는 API 키와 서버 환경을 설정합니다:
LicenseInfo(
apiKey: "YOUR_API_KEY", // Petnow API 키
isDebugMode: false // deprecated: 항상 false
)isDebugMode는 deprecated되었습니다. 항상 false를 전달하세요.
5단계: 설치 확인
SDK가 올바르게 설치되었는지 확인하려면 앱을 빌드하고 실행하세요.
카메라 초기화가 성공하면 카메라 프리뷰가 표시됩니다. 실패 시 에러 메시지를 확인하세요:
do {
try await cameraViewModel.initializeCamera(
licenseInfo: LicenseInfo(apiKey: "YOUR_API_KEY", isDebugMode: false),
initialPosition: .back,
captureSessionId: captureSessionId
) { result in
print("촬영 완료")
}
print("카메라 초기화 성공")
} catch {
print("초기화 실패: \(error.localizedDescription)")
}문제 해결
패키지를 찾을 수 없음 (Package Resolution Failed)
증상: Xcode에서 "package 'PetnowUI' not found" 또는 유사한 오류
해결 방법:
-
Registry 설정 확인
# Xcode Workspace 프로젝트 cat YourApp.xcworkspace/xcshareddata/swiftpm/configuration/registries.json # Package.swift 프로젝트 cat ~/.swiftpm/configuration/registries.json파일이 없거나 비어있다면 프로젝트 루트에서 다시 로그인:
cd /path/to/YourApp # .xcworkspace 파일이 있는 디렉토리 aws codeartifact login --tool swift \ --domain $PETNOW_CODEARTIFACT_DOMAIN \ --domain-owner $PETNOW_AWS_ACCOUNT_ID \ --repository $PETNOW_IOS_SDK_REPOSITORY -
토큰 만료 확인
- 토큰은 12시간 후 만료됩니다
aws codeartifact login명령을 다시 실행하세요
-
Xcode 캐시 삭제
# SPM 캐시 삭제 rm -rf ~/Library/Caches/org.swift.swiftpm rm -rf ~/Library/Developer/Xcode/DerivedData # Xcode 재시작 후 File > Packages > Reset Package Caches
Registry 설정 누락 (Xcode Workspace)
증상: 로그인했는데도 Xcode에서 패키지를 찾지 못함
원인: aws codeartifact login --tool swift는 ~/.swiftpm/에만 설정을 저장하므로, Xcode Workspace는 이를 인식하지 못함
해결: 옵션 B의 Registry 설정 복사 과정을 수행하세요
# Xcode Workspace로 복사
mkdir -p YourApp.xcworkspace/xcshareddata/swiftpm/configuration
cp ~/.swiftpm/configuration/registries.json YourApp.xcworkspace/xcshareddata/swiftpm/configuration/카메라 권한 오류
증상: 앱이 크래시하거나 권한 요청이 표시되지 않음
해결: Info.plist에 NSCameraUsageDescription 추가 확인
API 키 오류
증상: 카메라 초기화 시 인증 오류
해결: API 키가 올바른지 확인하고 Petnow 팀에 문의
다음 단계
설치와 설정이 완료되었습니다! 이제 SDK를 사용할 준비가 되었습니다.
지원
설치 중 문제가 발생하면 support@petnow.io로 문의해주세요.