Getting Started

Overview

This guide walks you through installing and configuring @petnow/react-native-camera-ui in a React Native app, step by step.

Prerequisites

• React Native 0.75 or higher, with New Architecture (Fabric/TurboModules) enabled
• Android minSdk 28 or higher / iOS 16.0 or higher
• AWS CLI (required for CodeArtifact authentication — install below)
• Petnow API key — issued from the Petify Console (or contact support@petnow.io)

Step 1: Installation

This package is distributed via AWS CodeArtifact (npm registry). It uses the same credential scheme as the Android SDK's CodeArtifact setup.

Install the AWS CLI

CodeArtifact authentication requires the AWS CLI. Install it from the following link: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

CodeArtifact Authentication and Installation

Set the environment variables with the values issued from the Petify Console, then log npm into CodeArtifact (configures ~/.npmrc):

export AWS_ACCESS_KEY_ID=<provided by Petify Console>
export AWS_SECRET_ACCESS_KEY=<provided by Petify Console>
export AWS_DEFAULT_REGION=<provided by Petify Console>
export PETNOW_CODEARTIFACT_DOMAIN=<provided by Petify Console>
export PETNOW_AWS_ACCOUNT_ID=<provided by Petify Console>
export PETNOW_NPM_REPOSITORY=<provided by 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"

Token expiration: CodeArtifact authentication tokens expire every 12 hours. If npm install fails with an authentication error, run aws codeartifact login again.

Then install the package:

npm install @petnow/react-native-camera-ui
# or
yarn add @petnow/react-native-camera-ui

The package includes the native binaries (iOS PetnowUI.xcframework, Android AAR), so no separate native SDK installation is required.

iOS

cd ios && pod install

New Architecture

New Architecture must be enabled in gradle.properties (Android) and the environment (iOS). The default RN 0.76+ template has it enabled.

Step 2: Permission Setup

Android

Declare the permissions in AndroidManifest.xml. The runtime permission request is performed automatically by the package when the camera mounts.

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

iOS

Add a camera usage description to Info.plist.

<key>NSCameraUsageDescription</key>
<string>The camera is used to photograph pets.</string>

Step 3: License Initialization

There is no global initialization function. The usePetnowCamera({ apiKey }) hook ties the controller's lifetime to a React component and holds the license.

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

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

  // Do not mount CameraView before it is ready.
  if (camera.state.status !== 'ready') {
    return <Loading state={camera.state} />;
  }

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

Step 4: Create a Capture Session

captureSessionId is a UUID issued on the server via the Petnow Server API. The client does not create it.

// Create a capture session on the server (or via your app server) → receive 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 }}
/>

Creating the capture session is the responsibility of the app server (the client only uses the issued captureSessionId). The petId requirement differs by purpose (required for registration and verification, not needed for identification). For the full server flow — from creation parameters and petId requirements to uploading the result images — see Server API – Biometric Data.

Troubleshooting

New Architecture Not Enabled

Symptom: The PetnowCamera native module/view cannot be found, or codegen-related build errors.

Solution: This package is New Architecture (Fabric/TurboModules) only. The default RN 0.76+ template has it enabled. On older versions, verify newArchEnabled=true (Android gradle.properties) and iOS RCT_NEW_ARCH_ENABLED=1, then run pod install.

npm install Fails with an Authentication Error (401/403)

Solution: CodeArtifact tokens expire every 12 hours. Run aws codeartifact login --tool npm ... again, then reinstall. Verify that the domain, account, and repository values, and your AWS credentials, match the values issued by the Petify Console.

Build/Link Failure on iOS

Solution: Make sure you ran cd ios && pod install. The package includes PetnowUI.xcframework as a vendored framework.

Camera Shows a Black Screen or Permission Is Denied

Solution: Verify that the camera permission is declared in the manifest/Info.plist. The package requests the runtime permission, and if the user denies it, failed is delivered via onDetectionStatus. Guide the user to grant the permission in Settings, then re-mount <CameraView>.

Camera Doesn't Appear Even Though ready

Solution: Verify that you did not mount <CameraView> before camera.state.status === 'ready' (an initialize() must complete... warning appears in the logs). Just respect the ready gating.

Next Steps

• Basic Usage — usePetnowCamera + CameraView, events, commands, and lifecycle
• Customization — Layering UI on top of <CameraView>