시작하기

개요

이 가이드는 Petnow iOS SDK를 프로젝트에 설치하고 초기 설정하는 방법을 단계별로 안내합니다.

사전 준비사항

시작하기 전에 다음을 준비해주세요:

• iOS 16.4 이상을 타겟으로 하는 Xcode 프로젝트
• Xcode 16.0 이상
• Petnow API 키 — Petify Console에서 발급 (또는 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의 My Page에서 AWS CodeArtifact 자격 증명을 발급하고, 제공된 값으로 환경 변수를 설정하세요. (콘솔 가입·결제수단 등록·키 발급 절차는 Petify Console 문서를 참고하세요.)

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 파일이 있는 프로젝트에서는 다음 명령만 실행하면 됩니다:

1. 프로젝트 루트 디렉토리로 이동:

cd /path/to/your-project  # Package.swift가 있는 디렉토리

2. AWS CodeArtifact 로그인 (Package.swift가 있는 디렉터리에서 실행 — 내부적으로 swift package-registry set을 호출합니다):

aws codeartifact login --tool swift \
  --domain $PETNOW_CODEARTIFACT_DOMAIN \
  --domain-owner $PETNOW_AWS_ACCOUNT_ID \
  --repository $PETNOW_IOS_SDK_REPOSITORY \
  --namespace petnow

--namespace petnow는 SDK 패키지 스코프(petnow.ui 등)에 맞춘 스코프 레지스트리로 설정합니다(생략하면 모든 패키지가 이 레지스트리로 라우팅됩니다). 스코프 레지스트리 매핑은 프로젝트의 .swiftpm/configuration/registries.json에 기록됩니다.

3. 성공 확인:

# 성공 시 출력:
Successfully configured swift to use AWS CodeArtifact repository ...
Login expires in 12 hours ...

# 프로젝트 레지스트리 설정 확인:
cat .swiftpm/configuration/registries.json

옵션 B: Xcode Workspace

CI/CD 환경에서 설치 (키체인 없이)

CI 러너에는 macOS 키체인을 쓰기 어렵습니다. aws codeartifact login(키체인) 대신 토큰을 ~/.netrc로 주입하면 헤드리스에서도 동작합니다. AWS 자격 증명은 CI 시크릿으로 넣고, 토큰은 12시간마다 만료되므로 빌드 단계에서 매번 발급하세요.

# .github/workflows/ios.yml (예시)
jobs:
  build:
    runs-on: macos-15
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.PETNOW_AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.PETNOW_AWS_SECRET_ACCESS_KEY }}
      AWS_DEFAULT_REGION: ${{ secrets.PETNOW_AWS_REGION }}
      PETNOW_CODEARTIFACT_DOMAIN: ${{ secrets.PETNOW_CODEARTIFACT_DOMAIN }}
      PETNOW_AWS_ACCOUNT_ID: ${{ secrets.PETNOW_AWS_ACCOUNT_ID }}
      PETNOW_IOS_SDK_REPOSITORY: ${{ secrets.PETNOW_IOS_SDK_REPOSITORY }}
    steps:
      - uses: actions/checkout@v4
      - name: Configure CodeArtifact SwiftPM registry (netrc)
        run: |
          ENDPOINT=$(aws codeartifact get-repository-endpoint \
            --domain "$PETNOW_CODEARTIFACT_DOMAIN" --domain-owner "$PETNOW_AWS_ACCOUNT_ID" \
            --repository "$PETNOW_IOS_SDK_REPOSITORY" --format swift \
            --query repositoryEndpoint --output text)
          HOST=$(printf '%s' "$ENDPOINT" | sed -E 's#https?://([^/]+)/.*#\1#')
          TOKEN=$(aws codeartifact get-authorization-token \
            --domain "$PETNOW_CODEARTIFACT_DOMAIN" --domain-owner "$PETNOW_AWS_ACCOUNT_ID" \
            --query authorizationToken --output text)
          # 토큰은 netrc로 (키체인 미사용). 12시간 유효.
          printf 'machine %s login aws password %s\n' "$HOST" "$TOKEN" > ~/.netrc
          chmod 600 ~/.netrc
          # 스코프 레지스트리 등록 (Package.swift가 있는 디렉터리에서)
          swift package-registry set "$ENDPOINT" --scope petnow
      - name: Resolve & build
        run: swift package resolve --netrc && swift build --netrc

Xcode에서 패키지 추가

1. Xcode에서 프로젝트를 엽니다
2. File > Add Packages... 선택
3. 구성된 CodeArtifact 저장소에서 petnow.ui 패키지를 검색
4. Add Package 클릭

중요: 패키지 이름을 입력 후 enter를 눌러야 합니다. 누르지 않으면 검색되지 않습니다.

설치 확인

패키지가 성공적으로 추가되면 프로젝트 네비게이터의 Package Dependencies 섹션에서 확인할 수 있습니다.

2단계: 프로젝트 설정

Info.plist 권한 추가

SDK가 카메라를 사용하려면 Info.plist에 권한 설명을 추가해야 합니다.

"Privacy - Camera Usage Description" 혹은 "NSCameraUsageDescription" 키를 추가하고, 카메라 사용 목적을 설명하는 문자열을 입력합니다.

필수 권한

<!-- 카메라 접근 권한 (필수) -->
<key>NSCameraUsageDescription</key>
<string>반려동물 탐지 및 식별을 위해 카메라 접근이 필요합니다.</string>

중요: 권한 설명이 없으면 카메라 접근 시 앱이 크래시됩니다.

모듈 임포트

import PetnowUI

3단계: 캡처 세션 생성

// 서버에서 captureSessionId를 받아옵니다
// (서버는 Petnow Server API의 createCaptureSession을 호출)
let captureSessionId: UUID = await yourServerAPI.createCaptureSession(
    species: "DOG",
    purpose: "PET_PROFILE_REGISTRATION"
)

캡처 세션 생성은 앱 서버의 책임입니다(클라이언트는 발급받은 captureSessionId만 사용). 목적(purpose)에 따라 petId 요건이 다릅니다(등록·검증은 필수, 식별은 불필요). 생성 파라미터·petId 요건·결과 이미지 업로드까지의 전체 서버 흐름은 서버 API – 생체 데이터를 참고하세요.

자세한 세션 개념은 UI 모듈 개요를 참고하세요.

4단계: 카메라 초기화

PetnowUI의 CameraController로 카메라를 초기화합니다. 촬영 설정(DetectionConfiguration)과 API 키(LicenseInfo)는 컨트롤러 생성자에 전달하고, 이후 initializeCamera를 호출합니다.

import SwiftUI
import PetnowUI

struct PetCameraView: View {
    @StateObject private var controller: CameraController
    private let captureSessionId: UUID  // 서버에서 받은 세션 ID

    init(captureSessionId: UUID) {
        self.captureSessionId = captureSessionId
        _controller = StateObject(wrappedValue: CameraController(
            configuration: DetectionConfiguration(
                species: .dog,                    // .dog 또는 .cat
                purpose: .petProfileRegistration  // .petProfileRegistration / .petVerification / .petIdentification
            ),
            licenseInfo: LicenseInfo(apiKey: "YOUR_API_KEY")
        ))
    }

    var body: some View {
        CameraView(controller: controller)
            .task { await initializeCamera() }
    }

    private func initializeCamera() async {
        do {
            try await controller.initializeCamera(
                initialPosition: .back,
                captureSessionId: captureSessionId
            ) { result in
                switch result {
                case let .success(fingerprintImages, appearanceImages):
                    // 로컬 file:// URL 배열 — 앱 서버로 업로드
                    print("촬영 완료: 지문 \(fingerprintImages.count), 외형 \(appearanceImages.count)")
                case .fail:
                    print("촬영 실패")
                }
            }
            controller.startDetection() 
        } catch {
            print("카메라 초기화 실패: \(error)")
        }
    }
}

DetectionConfiguration / LicenseInfo

• DetectionConfiguration(species:purpose:enableFakeDetection:difficultyMode:) — 촬영 설정. purpose는 DetectionPurpose(.petProfileRegistration / .petVerification / .petIdentification).
• LicenseInfo(apiKey:) — API 키. 라이선스 검증은 initializeCamera 시점에 서버에서 (키별 1회) 수행됩니다.

라이선스를 initializeCamera(licenseInfo:…)로 전달하던 이전 방식은 deprecated입니다. 위처럼 생성자에 licenseInfo를 주입하고, initializeCamera는 license 인자 없이 호출하세요.

5단계: 설치 확인

SDK가 올바르게 설치되었는지 확인하려면 앱을 빌드하고 실행하세요.

카메라 초기화가 성공하면 카메라 프리뷰가 표시됩니다. 실패 시 에러 메시지를 확인하세요:

do {
    // licenseInfo는 위에서 CameraController(configuration:licenseInfo:) 생성자에 이미 전달됨
    try await controller.initializeCamera(
        initialPosition: .back,
        captureSessionId: captureSessionId
    ) { _ in
        print("촬영 완료")
    }
    print("카메라 초기화 성공")
} catch {
    print("초기화 실패: \(error.localizedDescription)")
}

문제 해결

패키지를 찾을 수 없음 (Package Resolution Failed)

증상: Xcode에서 "package 'PetnowUI' not found" 또는 유사한 오류

해결 방법:

1. Registry 설정 확인

   # Xcode Workspace 프로젝트
   cat YourApp.xcworkspace/xcshareddata/swiftpm/configuration/registries.json
   
   # Package.swift 프로젝트 (프로젝트 루트의 .swiftpm)
   cat .swiftpm/configuration/registries.json

   파일이 없거나 비어있다면 Package.swift가 있는 디렉터리(Package.swift 프로젝트 루트, 또는 Option B의 dummy 프로젝트)에서 다시 로그인:

   cd /path/to/package-dir  # Package.swift가 있는 디렉터리
   aws codeartifact login --tool swift \
     --domain $PETNOW_CODEARTIFACT_DOMAIN \
     --domain-owner $PETNOW_AWS_ACCOUNT_ID \
     --repository $PETNOW_IOS_SDK_REPOSITORY \
     --namespace petnow

2. 토큰 만료 확인

   • 토큰은 12시간 후 만료됩니다
   • aws codeartifact login 명령을 다시 실행하세요

3. 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에서 패키지를 찾지 못함

원인: 스코프 레지스트리 매핑은 로그인을 실행한 프로젝트(또는 dummy 프로젝트)의 .swiftpm/configuration/registries.json 에 생성됩니다. Xcode Workspace는 자신의 xcshareddata/swiftpm/configuration/registries.json을 사용하므로, 그 위치로 복사해야 인식합니다.

해결: 옵션 B의 Registry 설정 복사 과정을 수행하세요 (dummy 프로젝트 디렉터리에서 실행)

# 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를 사용할 준비가 되었습니다.

• UI 모듈 개요 - UI 모듈 구조 이해하기
• 기본 사용법 - 카메라 UI 통합하기

지원

설치 중 문제가 발생하면 support@petnow.io로 문의해주세요.