SDK v1.2 → v1.4 마이그레이션

의존성은 곧바로 v1.4로 올리세요 — 중간에 v1.3을 설치할 이유가 없습니다. 이 가이드는 v1.2.x와 v1.4 사이의 모든 코드 변경을 한 곳에 모아 v1.4 API 기준으로만 서술합니다. v1.4가 다시 갈아엎는 v1.3 시절 코드를 잠깐 쓰는 일이 없도록 하기 위해서입니다.

iOS

1. CameraViewModel → CameraController · 라이선스는 생성자로 · captureSessionId 필수

v1.2 시절 패턴 세 가지가 한 번에 바뀝니다: 타입 이름이 바뀌고, 라이선스가 생성자로 이동하며, initializeCamera에 서버가 발급한 captureSessionId (POST /api/capture-sessions)가 필수입니다.

// ❌ v1.2.x
@StateObject private var viewModel: CameraViewModel
try await viewModel.initializeCamera(
    licenseInfo: LicenseInfo(apiKey: "YOUR_API_KEY"),
    initialPosition: .back
) { result in /* ... */ }
CameraView(viewModel: viewModel)

// ✅ v1.4
@StateObject private var controller = CameraController( 
    configuration: DetectionConfiguration(species: .dog, purpose: .petProfileRegistration), 
    licenseInfo: LicenseInfo(apiKey: "YOUR_API_KEY") 
)
let sessionId = try await createCaptureSessionFromServer() // POST /api/capture-sessions
try await controller.initializeCamera(initialPosition: .back, captureSessionId: sessionId) 
CameraView(controller: controller) 

왜: 컨트롤러가 수명 동안 라이선스를 보유하고(검증 1회), initializeCamera는 카메라 연결에만 집중하며, 타입 이름이 Android의 CameraController와 일치합니다. → 시작하기

2. previewLayer 제거 — 프리뷰는 CameraView가 담당

CameraViewModel.previewLayer(v1.2)는 제거됐고, v1.4에서 캡처 세션은 공개 getter가 없지만 — 이니셜라이저로 자체 AVCaptureSession을 주입하면 완전 커스텀 프리뷰는 여전히 가능합니다(커스터마이징 참고). 기본 경로에서는 CameraView가 프리뷰를 담당하며, 준비 상태 확인은 published 프로퍼티 isInitialized를 쓰세요.

// ❌ v1.2.x
if viewModel.previewLayer != nil { showCameraView() }
view.layer.addSublayer(viewModel.previewLayer)

// ✅ v1.4 — 프리뷰는 CameraView가 그리고, 준비 상태는 명시적으로 확인
if controller.isInitialized { showCameraView() } 
CameraView(controller: controller)               

프리뷰 위에 커스텀 UI를 올리려면 CameraView 위에 뷰를 얹으세요 — 커스터마이징 참고.

3. 탐지가 저절로 시작되지 않습니다 — startDetection() 호출

initializeCamera()는 카메라만 연결하고 탐지를 시작하지 않습니다. 반환된 뒤 명시적으로 시작하세요(재촬영도 같은 호출):

try await controller.initializeCamera(initialPosition: .back, captureSessionId: sessionId)
controller.startDetection() 

4. 종료: stopDetection() → finalizeCamera()

// ❌ v1.2.x
controller.stopDetection()

// ✅ v1.4
controller.finalizeCamera() 

일시정지/재개는 별도 동사(pauseDetection())를 가져 완전 종료가 항상 명시적입니다.

iOS 변경 요약

Android

1. 전역 PetnowApiClient 소멸 — 라이선스·설정은 세션 단위로 전달

// ❌ v1.2.x (apiClient 모듈이 더 이상 배포되지 않음 — 컴파일 에러)
PetnowApiClient.init(key = "YOUR_API_KEY", isDebugMode = false)
PetnowApiClient.configureDetectionMode(
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    species = PetSpecies.DOG,
    enableFakeDetection = true
)

• 권장 (CameraView + CameraController): LicenseInfo를 CameraController(context, license, scope) 생성자에, DetectionConfiguration을 initializeCamera(config, captureSessionId)에 전달합니다. → 기본 사용법
• 기존 PetnowCameraFragment 유지: 라이선스는 Fragment args(ARG_API_KEY)나 provideLicense()로, 설정은 ARG_DETECTION_CONFIGURATION으로 전달합니다. → Fragment (레거시)

PetnowApiClient.isSuccessInitialize의 대체물은 없습니다 — 초기화 실패는 PetnowUIError로 드러납니다(4번). 설정 타입 패키지가 이동하고(io.petnow.api.client.* → io.petnow.ui.config.*, 형태 동일), Android의 isDebugMode는 사라졌습니다.

2. captureSessionId 필수

어느 경로든 서버 발급 captureSessionId(POST /api/capture-sessions)가 필수입니다.

// ✅ v1.4 — CameraController 경로
val sessionId = createCaptureSessionFromServer()
controller.initializeCamera(configuration, captureSessionId = sessionId) 

// ✅ v1.4 — Fragment 경로
val fragment = MyCameraFragment().apply {
    arguments = Bundle().apply {
        putString(ARG_CAPTURE_SESSION_ID, sessionId.toString()) 
    }
}

3. 리스너 import 패키지 변경 — 그리고 V2로

// ❌ v1.2.x
import io.petnow.ui.PetnowCameraDetectionListener

// ✅ v1.4
import io.petnow.callback.PetnowCameraDetectionListenerV2 

CameraController 경로에서는 setDetectionListenerV2를 쓰세요. V2는 iOS와 동일한 결과 모델 — sealed DetectionStatus (NoObject/Processing/Detected/Finished/Failed(reason))와 CameraResult(Success(fingerprintImageFiles, appearanceImageFiles)/Fail) — 를 전달합니다.

4. 초기화 실패는 구조화된 PetnowUIError

initializeCamera()가 더 이상 플랫폼 예외를 그대로 던지지 않으며, API 키를 서버에 검증합니다(프로세스당 키별 1회).

// ✅ v1.4 — catch 하나 + sealed when
try {
    controller.initializeCamera(configuration, captureSessionId)
} catch (e: PetnowUIError) {                                
    when (e) {
        is PetnowUIError.InvalidLicense -> { /* API 키 거절 */ }
        is PetnowUIError.PermissionDenied -> { /* 권한 없음 */ }
        is PetnowUIError.CameraOpenFailed -> { /* 카메라 오류 — e.cause 참조 */ }
    }
}

CancellationException은 여전히 그대로 전파됩니다(정상 수명주기 — 다시 던지세요).

Android 변경 요약

마이그레이션 체크리스트

공통

• 서버에서 POST /api/capture-sessions로 captureSessionId 발급

iOS

• CameraViewModel → CameraController; 라이선스를 생성자로
• 서버 세션 ID로 initializeCamera(initialPosition:captureSessionId:)
• previewLayer 사용 코드를 CameraView로 교체 (준비 상태는 isInitialized)
• initializeCamera 후 startDetection() 호출 · stopDetection() → finalizeCamera()

Android

• PetnowApiClient 호출 제거; 라이선스/설정을 세션 단위로 전달; 서버 API 호출은 앱 서버로 이관
• captureSessionId 전달 (컨트롤러 인자 또는 ARG_CAPTURE_SESSION_ID)
• 리스너 import를 io.petnow.callback으로, V2로 이전
• initializeCamera() 주변을 PetnowUIError catch로 교체