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

v1.5.0은 강아지 비문 품질 판정을 기기로 옮기고, 1.4.2에서 도입된 실시간 서버 품질 판정 경로를 제거하며, difficulty 레벨을 폐기하고, Android AAR에 x86_64를 추가하고, LicenseInfo에 환경 선택을 추가합니다.

배포 전에 반드시 확인할 것이 세 가지입니다. Android 앱은 재빌드해야 하고, 서버 품질 판정 API는 완전히 제거되었고, enableFakeDetection 기본값이 true로 바뀌었습니다. 그 외에는 소스 호환입니다.

버전 변경

온디바이스 품질 모델이 SDK에 포함되어 패키지가 커집니다. Android AAR은 두 ABI 포함 약 74MB(12MB 모델은 1회만 포함, App Bundle도 1회만 포함), iOS 프레임워크는 약 12MB 증가합니다.

Breaking: 실시간 서버 품질 판정 API 제거

1.4.2–1.4.5 실시간 서버 품질 판정 파일럿에 참여했다면, 이것은 나중에 정리해도 되는 항목이 아니라 컴파일 에러입니다. deprecated no-op을 남겨 두지 않았습니다.

prop과 타입을 삭제하세요. 대체 API는 없습니다. 이 콜백은 더 이상 일어나지 않는 서버 판정을 보고하던 것이고, 강아지 품질 점수는 공개 API가 아닙니다. 파일럿을 켠 적이 없는 통합은 할 일이 없습니다.

촬영이 더 이상 서버 호출을 기다리지 않습니다. 라이선스 검증은 initializeCamera()에서 프로세스당 API 키별 1회 수행되며, 이 시점에 서버에 도달할 수 없으면 InvalidLicense로 실패합니다. 그 뒤로 검출과 결과 파일은 로컬에서 처리되고, SDK가 백그라운드로 보내는 사용량 지표는 촬영을 막거나 실패시키지 않습니다. "세션이 detected에서 멈춤"이나 서버 품질 판정 타임아웃을 별도로 처리하던 코드가 있다면 제거해도 됩니다. → 촬영 품질은 어떻게 판정되나요

기본값 변경: enableFakeDetection이 true

DetectionConfiguration.enableFakeDetection의 기본값이 모든 플랫폼(iOS, Android, React Native)에서 **true**가 되었습니다. 1.4.5에서는 이 값을 지정하지 않으면 위조 감지가 꺼진 상태였지만, 1.5에서는 같은 코드가 위조 감지를 켭니다. 업그레이드 전에 호출 지점을 확인하세요. 사진으로 테스트해 온 플로우는 이제 실패하기 시작합니다.

false를 넘기면 해당 세션에서 위조 감지가 비활성화됩니다. 실제 동물 대신 사진으로 SDK를 평가할 때 쓰는 방법입니다.

// 1.4.5 — 지정하지 않으면 꺼짐
DetectionConfiguration(species = PetSpecies.DOG, purpose = DetectionPurpose.PET_PROFILE_REGISTRATION)

// 1.5.0 — 같은 호출에서 위조 감지가 켜짐

// 1.5.0 — 사진으로 테스트할 때
DetectionConfiguration(
    species = PetSpecies.DOG,
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    enableFakeDetection = false, 
)

신규: LicenseInfo.environment

staging 콘솔에서 발급한 API 키는 staging 백엔드에서만 유효하고, 그 반대도 마찬가지입니다. v1.5는 키가 어느 백엔드용인지 호스트가 지정할 수 있게 했습니다. v1.3.x의 isDebugMode가 하던 일이고, v1.4에서 사라졌던 기능입니다.

// Android
LicenseInfo(apiKey = "YOUR_API_KEY", environment = PetnowEnvironment.STAGING)

// iOS
LicenseInfo(apiKey: "YOUR_API_KEY", environment: .staging)

// React Native
const camera = usePetnowCamera({ apiKey, environment: 'staging' });

지정하지 않으면 SDK가 빌드된 환경을 그대로 씁니다. 배포되는 모든 빌드는 production이므로, 이 값을 설정하지 않는 앱은 달라지는 것이 없습니다. boolean이 아니라 이름 있는 환경으로 만든 이유가 있습니다. 호스트 앱의 DEBUG / __DEV__ 플래그에 연결하지 마세요. 릴리즈 빌드가 실수로 staging을 선택하면, 펫이 등록되어 있지 않은 백엔드로 실제 촬영이 전송됩니다.

신규: 프로세스당 API 키 하나

같은 프로세스에서 다른 API 키를 두 번째로 넘기면, 이제 조용히 교체되는 대신 거부됩니다. 콘솔에서 키를 여러 개 발급할 수 있지만, 한 프로세스는 그중 하나를 골라 계속 써야 합니다.

먼저 사용한 키는 계속 동작합니다. 같은 키로 다시 초기화하는 것은 영향이 없습니다.

Deprecated: difficultyMode

계속 받기만 하고 무시되며, 1.5까지는 그대로 유지됩니다. 다음 메이저 릴리즈에서 제거됩니다. deprecation 경고를 없애려면 편한 시점에 인자를 지우세요.

// v1.4.x
DetectionConfiguration(
    species = PetSpecies.DOG,
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    enableFakeDetection = true,
    difficultyMode = DifficultyMode.NORMAL,   // 1.5.0에서 deprecated — 무시됨
)

// v1.5.0
DetectionConfiguration(
    species = PetSpecies.DOG,
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    enableFakeDetection = true,
)

iOS DetectionConfiguration(difficultyMode:)와 React Native <CameraView difficultyMode> prop도 동일합니다.

이유: 강아지 비문 촬영 품질은 온디바이스 모델이 판정하며, difficulty 레벨은 이 판정에 관여하지 않습니다. → 촬영 품질은 어떻게 판정되나요

Android

1. 의존성 — 단일 self-contained AAR

dependencies {
    implementation("io.petnow:ui:1.5.0")
    // 남아 있다면 제거:
    // implementation("io.petnow:api-client:...")
    // implementation(files("AndroidCameraFramework-release.aar"))
}

io.petnow:ui에 필요한 것이 모두 들어 있습니다. api-client 모듈과 AndroidCameraFramework 아티팩트는 1.4/1.5에서 배포되지 않으므로 선언하면 안 됩니다. 서버 호출은 앱 서버에서 하세요 → Server API.

2. ABI — x86_64 추가, armeabi-v7a 미포함

AAR에는 arm64-v8a와 x86_64가 들어 있습니다. 에뮬레이터 기반 테스트에서 SDK가 실행됩니다(에뮬레이터의 GPU 가속은 GL/OpenCL 지원에 따라 다르며 CPU로 폴백합니다). 앱에 abiFilters가 있다면 armeabi-v7a 전용 빌드에 SDK가 포함되기를 기대하지 않도록 확인하세요.

3. 선택: inferenceTier와 performanceStats

• DetectionConfiguration.inferenceTier(AUTO 기본 / CPU / GPU)는 검출기 실행 경로를 선택합니다. AUTO는 기기에 맞는 경로를 고르고, 그 경로를 쓸 수 없으면 다른 경로로 폴백합니다. 이 값은 프로세스가 첫 검출기 엔진을 만들 때 한 번만 읽히고 이후 고정됩니다. 프로세스의 첫 initializeCamera()에서 지정하거나, 바꾸려면 앱을 재시작하세요. 지원팀이 요청할 때만 티어를 강제하세요.
• CameraController.performanceStats(StateFlow<CameraPerformanceStats>)와 PetnowCameraFragment.performanceStats()는 카메라 초기화 시간, 첫 프레임 시간, fps, 검출기 ms, 선택된 티어를 알려 줍니다. 진단 화면이나 지원 요청에 유용합니다. → 기본 사용법

4. 레거시 Fragment 경로 — 종별 결과 목록

PetnowCameraFragment와 V1 DetectionCaptureResult를 계속 쓴다면: 강아지는 noseImageFiles(생체 세트 → fingerprint로 업로드)와 faceImageFiles(외형 세트)가 모두 채워지고, 고양이는 faceImageFiles만 채워지며 이것이 생체 세트입니다. 1.4와 동일하지만 그동안 문서화되지 않았던 내용입니다.

iOS

• CameraController.performanceStats(@Published CameraPerformanceStats)가 추가되었습니다. 변경할 것은 없습니다.
• CameraOpticsPolicy와 적응형 후면 카메라 모드가 제거되었습니다. 서버 품질 판정 경로만 쓰던 기능이며, 후면 렌즈 선택은 1.4.3과 동일하게 동작합니다.
• setRealtimeServerIqaDiagnosticHandler와 RealtimeServerIqa* 타입이 제거되었습니다(위 Breaking 참고).

React Native

• onRealtimeServerIqaDiagnostic과 RealtimeServerIqa* 타입이 제거되었고(위 Breaking 참고), difficultyMode는 deprecated이며 네이티브로 전달되지 않습니다. usePetnowCamera / <CameraView>의 나머지는 그대로입니다.
• 지원 범위는 동일합니다: React Native 0.75 이상(0.86.x까지 검증) + New Architecture 활성화.
• 1.5.0용 새 예제 앱이 있습니다. support@petnow.io로 문의하세요.

마이그레이션 체크리스트

• 패키지 버전 올리기(io.petnow:ui:1.5.0 / petnow.ui 1.5.0 / @petify/react-native-camera-ui@1.5.0)
• Android: 앱 재빌드. 1.4.5로 컴파일한 바이너리에 1.5 AAR만 넣어 배포하지 마세요
• 파일럿 통합만: onRealtimeServerIqaDiagnostic, RealtimeServerIqa* 타입, PETNOW_SERVER_IQA_* / Info.plist / .env 설정 삭제
• 모든 DetectionConfiguration 호출 지점에서 바뀐 enableFakeDetection 기본값 확인
• 프로세스당 API 키 하나인지 확인. staging 키라면 environment를 staging으로 지정
• difficultyMode 인자 제거(선택, deprecation 경고 제거)
• Android: api-client / AndroidCameraFramework 선언이 있으면 제거
• 기기에서 촬영 플로우 재확인. 콜백과 결과 파일은 바뀌지 않았습니다