시작하기

개요

이 가이드는 @petify/react-native-camera-ui를 React Native 앱에 설치하고 초기 설정하는 방법을 단계별로 안내합니다.

사전 준비사항

• React Native 0.75 – 0.86.x, New Architecture(Fabric/TurboModules) 활성화
• Android minSdk 28 이상 / iOS 16.4 이상
• AWS CLI (CodeArtifact 인증에 필요 — 아래 설치)
• Petnow API 키 — Petify Console에서 발급 (또는 support@petnow.io 문의)

1단계: 설치

이 패키지는 AWS CodeArtifact(npm 레지스트리) 를 통해 배포됩니다. Android SDK의 CodeArtifact 설정과 동일한 자격 증명 체계를 사용합니다.

AWS CLI 설치

CodeArtifact 인증에는 AWS CLI가 필요합니다. 다음 링크에서 설치하세요: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

CodeArtifact 인증 및 설치

Petify Console에서 발급한 값으로 환경 변수를 설정한 뒤, npm을 CodeArtifact에 로그인합니다(~/.npmrc 구성):

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_NPM_REPOSITORY=<Petify Console에서 제공>

aws codeartifact login --tool npm \
  --domain "$PETNOW_CODEARTIFACT_DOMAIN" \
  --domain-owner "$PETNOW_AWS_ACCOUNT_ID" \
  --repository "$PETNOW_NPM_REPOSITORY" \
  --region "$AWS_DEFAULT_REGION"

토큰 만료: CodeArtifact 인증 토큰은 12시간마다 만료됩니다. npm install이 인증 오류로 실패하면 aws codeartifact login을 다시 실행하세요.

그런 다음 패키지를 설치합니다:

npm install @petify/react-native-camera-ui
# 또는
yarn add @petify/react-native-camera-ui

패키지는 네이티브 바이너리(iOS PetnowUI.xcframework, Android AAR)를 포함하므로 별도의 네이티브 SDK 설치는 필요 없습니다.

iOS

cd ios && pod install

New Architecture

gradle.properties(Android)와 환경(iOS)에서 New Architecture가 켜져 있어야 합니다. RN 0.76+ 기본 템플릿은 활성화되어 있습니다.

2단계: 권한 설정

Android

AndroidManifest.xml에 권한을 선언하세요. 런타임 권한 요청은 패키지가 카메라 마운트 시 자동으로 수행합니다.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>

iOS

Info.plist에 카메라 사용 설명을 추가하세요.

<key>NSCameraUsageDescription</key>
<string>반려동물 촬영을 위해 카메라를 사용합니다.</string>

3단계: 라이선스 초기화

전역 초기화 함수는 없습니다. usePetnowCamera({ apiKey }) hook이 컨트롤러 수명을 React 컴포넌트에 묶고, 라이선스를 보유합니다.

import { usePetnowCamera, CameraView } from '@petify/react-native-camera-ui';

function Scan() {
  const camera = usePetnowCamera({ apiKey: 'YOUR_API_KEY' });

  // 준비되기 전에는 CameraView를 마운트하지 마세요.
  if (camera.state.status !== 'ready') {
    return <Loading state={camera.state} />;
  }

  return <CameraView camera={camera} /* ...props */ />;
}

4단계: 캡처 세션 생성

captureSessionId는 서버에서 Petnow Server API로 발급받은 UUID입니다. 클라이언트가 생성하지 않습니다.

// 서버(또는 앱 서버 경유)에서 capture session 생성 → captureSessionId(UUID) 수신
const captureSessionId = await yourServerApi.createCaptureSession({
  species: 'DOG',
  purpose: 'PET_PROFILE_REGISTRATION',
});

<CameraView
  camera={camera}
  species="DOG"
  purpose="PET_PROFILE_REGISTRATION"
  captureSessionId={captureSessionId}
  style={{ flex: 1 }}
/>

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

5단계: 설치 확인

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

camera.state.status가 'ready'가 되면 <CameraView>가 마운트되고, 카메라 프리뷰와 탐지 오버레이(코/얼굴 마커) 가 표시됩니다. 상태와 이벤트가 들어오는지 로그로 확인할 수 있습니다:

const camera = usePetnowCamera({ apiKey });
console.log('state:', camera.state.status); // idle → initializing → ready

return (
  <CameraView
    camera={camera}
    species="DOG"
    purpose="PET_PROFILE_REGISTRATION"
    captureSessionId={captureSessionId}
    style={{ flex: 1 }}
    onDetectionStatus={(s) => console.log('detection:', s.type)} // noObject / processing / ...
  />
);

프리뷰가 표시되고 state가 ready가 되며 onDetectionStatus가 호출되면 정상입니다. 화면이 검은색이거나 이벤트가 오지 않으면 아래 문제 해결을 확인하세요.

문제 해결

New Architecture 미활성

증상: PetnowCamera 네이티브 모듈/뷰를 찾을 수 없음, codegen 관련 빌드 오류.

해결: 이 패키지는 New Architecture(Fabric/TurboModules) 전용입니다. RN 0.76+ 기본 템플릿은 활성화돼 있습니다. 구버전이면 newArchEnabled=true(Android gradle.properties)와 iOS RCT_NEW_ARCH_ENABLED=1 후 pod install을 확인하세요.

npm install이 인증 오류(401/403)로 실패

해결: CodeArtifact 토큰은 12시간마다 만료됩니다. aws codeartifact login --tool npm ...을 다시 실행한 뒤 재설치하세요. 도메인·계정·저장소 값과 AWS 자격 증명이 Petify Console 발급값과 일치하는지 확인하세요.

iOS에서 빌드/링크 실패

해결: cd ios && pod install을 실행했는지 확인하세요. 패키지는 PetnowUI.xcframework를 vendored framework로 포함합니다.

카메라가 검은 화면이거나 권한 거부

해결: 매니페스트/Info.plist에 카메라 권한을 선언했는지 확인하세요. 런타임 권한은 패키지가 요청하며, 사용자가 거부하면 onDetectionStatus로 failed가 전달됩니다. 설정에서 권한을 허용하도록 안내한 뒤 <CameraView>를 다시 마운트하세요.

ready인데 카메라가 안 뜸

해결: <CameraView>를 camera.state.status === 'ready' 이전에 마운트하지 않았는지 확인하세요(로그에 initialize() must complete... 경고가 남습니다). ready 게이팅을 지키면 됩니다.

다음 단계

설치와 설정이 완료되었습니다! 이제 SDK를 사용할 준비가 되었습니다.

• 기본 사용법 — usePetnowCamera + CameraView, 이벤트·커맨드·수명주기
• 커스터마이징 — <CameraView> 위에 UI 올리기

지원

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