Petnow LogoPetnow
Android SDK

시작하기

Petnow Android SDK 설치 및 초기 설정 가이드.

개요

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

사전 준비사항

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

  • Android API 28 (Android 9.0) 이상을 타겟으로 하는 프로젝트
  • compileSdk 34 이상
  • Java 17 이상
  • Kotlin 1.9 이상
  • Petnow API 키 — Petify Console에서 발급 (또는 support@petnow.io 문의)

1단계: SDK 설치

Petnow Android 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 문서를 참고하세요.)

Petify Console – AWS CodeArtifact 자격 증명 화면

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

Petnow Maven 저장소 추가

자격 증명으로부터 저장소 URL과 인증 토큰을 도출하세요:

export CODEARTIFACT_URL=$(aws codeartifact get-repository-endpoint \
  --domain $PETNOW_CODEARTIFACT_DOMAIN \
  --domain-owner $PETNOW_AWS_ACCOUNT_ID \
  --repository $PETNOW_ANDROID_SDK_REPOSITORY \
  --region $AWS_DEFAULT_REGION \
  --format maven \
  --query repositoryEndpoint \
  --output text)

export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
  --domain $PETNOW_CODEARTIFACT_DOMAIN \
  --domain-owner $PETNOW_AWS_ACCOUNT_ID \
  --region $AWS_DEFAULT_REGION \
  --query authorizationToken \
  --output text)

토큰 만료: 12시간마다, 또는 Gradle sync가 인증 오류로 실패할 때 두 명령을 모두 다시 실행하세요. CI 등 자동화 환경에서는 자격 증명을 시크릿으로 주입하고 빌드 단계에서 토큰을 갱신하세요 — AWS CodeArtifact 인증 토큰 문서 참고.

프로젝트의 settings.gradle.kts 또는 루트 build.gradle.kts 파일에 Petnow Maven 저장소를 추가하세요:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            name = "CodeArtifact"
            url = uri(System.getenv("CODEARTIFACT_URL") ?: "YOUR_REPOSITORY_URL")
            credentials {
                username = "aws"
                password = System.getenv("CODEARTIFACT_AUTH_TOKEN") ?: "YOUR_AUTH_TOKEN"
            }
        }
    }
}

의존성 추가

앱의 build.gradle.kts 파일에 다음 의존성을 추가하세요:

dependencies {
    // Petnow SDK
    implementation("io.petnow:ui:1.4.5")
}

UI 모듈 사용에는 별도의 api-client 의존이 필요하지 않습니다. 서버 API 호출이 필요한 경우에는 앱 서버에서 직접 처리하세요.

2단계: 프로젝트 설정

AndroidManifest.xml 구성

앱의 AndroidManifest.xml 파일에 다음 권한과 설정을 추가하세요:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- 인터넷 권한 (필수) -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- 카메라 권한 (필수) -->
    <uses-permission android:name="android.permission.CAMERA"/>

    <application
        android:largeHeap="true"
        ... >
        ...
    </application>

</manifest>
설정설명
INTERNETAPI 통신 및 라이선스 검증에 필요
CAMERA카메라 프리뷰·탐지에 필요
largeHeap="true"이미지 처리와 탐지 작업 시 최적의 성능을 위해 권장

카메라 권한은 호스트가 요청합니다

권장 경로인 CameraView + CameraController는 카메라 권한을 자동으로 요청하지 않습니다. 위 CAMERA 권한을 선언하고, 세션을 시작하기 전에 런타임 권한을 직접 요청하세요. (레거시 PetnowCameraFragment만 권한을 자동 요청합니다.)

모듈 임포트

import io.petnow.ui.CameraController
import io.petnow.ui.CameraView
import io.petnow.ui.config.LicenseInfo
import io.petnow.callback.PetnowCameraDetectionListenerV2

3단계: 라이선스와 탐지 설정 이해하기

1.4.0부터 전역 초기화(v1.3.x의 PetnowApiClient.init())는 없습니다. 라이선스와 탐지 설정은 카메라 세션 단위로 전달합니다.

  • 라이선스: LicenseInfo(apiKey)를 만들어 CameraController 생성자에 전달합니다. (별도의 전역 초기화 호출이 없습니다.)
  • 탐지 설정: DetectionConfiguration을 만들어 세션을 시작할 때 initializeCamera()에 전달합니다.
import io.petnow.ui.CameraController
import io.petnow.ui.config.LicenseInfo

// 라이선스는 CameraController를 만들 때 전달합니다.
val license = LicenseInfo(apiKey = "YOUR_API_KEY")
val controller = CameraController(
    context,                     // Application/Activity Context
    license,
    coroutineScope,              // 세션 동안 유효한 CoroutineScope
)

apiKey는 모니터링/메트릭 용도입니다. Android에서는 클라이언트 측 라이선스 검증을 수행하지 않습니다(키가 없거나 틀려도 카메라는 동작하지만, 메트릭이 집계되지 않습니다). 키 발급은 support@petnow.io로 문의하세요.

탐지 설정 (DetectionConfiguration)

import io.petnow.ui.config.DetectionConfiguration
import io.petnow.ui.config.DetectionPurpose
import io.petnow.ui.config.PetSpecies

// 강아지 프로필 등록용
val configuration = DetectionConfiguration(
    species = PetSpecies.DOG,
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    enableFakeDetection = true,
)

이 설정은 세션을 시작할 때 controller.initializeCamera(configuration, captureSessionId)에 전달합니다. 자세한 흐름은 기본 사용법에서 다룹니다.

파라미터 설명

파라미터설명
species반려동물 종류. 탐지 파이프라인이 결정됩니다.
purpose촬영 목적. 목적에 따라 필요한 이미지 수가 결정됩니다.
enableFakeDetection가짜 이미지(사진·영상 등) 탐지 활성화 여부
difficultyMode(선택) 난이도. 지정하지 않으면 서버/기본값(NORMAL)이 적용됩니다.

purpose 옵션:

  • DetectionPurpose.PET_PROFILE_REGISTRATION - 프로필 등록
  • DetectionPurpose.PET_IDENTIFICATION - 식별
  • DetectionPurpose.PET_VERIFICATION - 인증

species 옵션:

  • PetSpecies.DOG - 강아지 (코 탐지)
  • PetSpecies.CAT - 고양이 (얼굴 탐지)

캡처 세션 생성

필수: 카메라 세션을 시작하기 전에 반드시 서버에서 캡처 세션을 생성하고 captureSessionId를 받아와야 합니다.

import java.util.UUID

lifecycleScope.launch {
    // 서버에서 captureSessionId를 받아옵니다
    // (서버는 Petnow Server API의 createCaptureSession을 호출)
    val captureSessionId: UUID = yourServerApi.createCaptureSession(
        species = "DOG",
        purpose = "PET_PROFILE_REGISTRATION"
    )
    
    // 카메라 화면으로 이동 시 captureSessionId 전달
    navigateToCameraScreen(captureSessionId)
}

Server API: captureSessionId는 서버에서 Petnow Server API를 통해 생성합니다. 클라이언트에서 직접 생성하지 않습니다.

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

자세한 captureSessionId 전달 방법은 UI 모듈 개요를 참고하세요.

4단계: 설치 확인

SDK가 올바르게 설치되었는지 확인하려면 앱을 빌드하고 실행하세요. 의존성이 정상적으로 받아졌다면 다음 코드가 컴파일되고, 기기의 카메라 지원 여부를 확인할 수 있습니다.

import io.petnow.ui.camera.cameraInfo

// 기기 카메라 지원 여부 확인 (전역 초기화 호출은 없습니다)
val cameraInfo = context.cameraInfo
Log.d("PetnowSDK", "supported=${cameraInfo.isSupportedDevice}, front=${cameraInfo.isFrontCameraSupported}")

문제 해결

패키지를 찾을 수 없음

증상: Gradle sync 실패, 의존성을 찾을 수 없음

해결 방법:

  1. CodeArtifact 인증 확인

    # 환경 변수 확인
echo $CODEARTIFACT_URL
echo $CODEARTIFACT_AUTH_TOKEN

  2. 토큰 갱신

    • CodeArtifact 토큰은 12시간 후 만료됩니다
    • 다음 명령으로 토큰을 재발급하세요:
    export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
  --domain $PETNOW_CODEARTIFACT_DOMAIN \
  --domain-owner $PETNOW_AWS_ACCOUNT_ID \
  --region $AWS_DEFAULT_REGION \
  --query authorizationToken \
  --output text)

  3. Gradle 캐시 삭제

    ./gradlew clean
./gradlew --refresh-dependencies

API 키 / 메트릭 관련

증상: 촬영은 되지만 Petify Console에 메트릭이 집계되지 않음

해결 방법:

  • Android는 클라이언트 측 라이선스 검증을 하지 않으므로, 키 문제는 카메라 동작이 아니라 메트릭 집계에서 드러납니다.
  • LicenseInfo(apiKey = ...)에 전달한 키가 올바른지 확인
  • support@petnow.io로 문의

카메라 권한 오류

증상: 카메라가 표시되지 않거나 권한 요청이 실패

해결 방법:

  • AndroidManifest.xml에 CAMERA 권한을 선언했는지 확인하세요
  • CameraView + CameraController 경로에서는 호스트가 세션 시작 전에 런타임 카메라 권한을 직접 요청해야 합니다 (레거시 PetnowCameraFragment만 자동 요청)
  • 사용자가 권한을 거부한 경우, 설정에서 수동으로 권한을 부여하도록 안내하세요

OutOfMemoryError

증상: 이미지 처리 중 메모리 부족 오류

해결 방법:

  • AndroidManifest.xml에 android:largeHeap="true" 추가 확인
  • 불필요한 이미지 캐시 정리

다음 단계

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

지원

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

Android SDK 소개

Petnow Android SDK의 기술 요구사항과 특징을 소개합니다.

UI 모듈 개요

Petnow Android UI 모듈의 구조와 핵심 컴포넌트 설명.

On this page

개요사전 준비사항1단계: SDK 설치AWS CLI 설치Petify Console에서 자격 증명 발급Petnow Maven 저장소 추가의존성 추가2단계: 프로젝트 설정AndroidManifest.xml 구성모듈 임포트3단계: 라이선스와 탐지 설정 이해하기탐지 설정 (DetectionConfiguration)파라미터 설명캡처 세션 생성4단계: 설치 확인문제 해결패키지를 찾을 수 없음API 키 / 메트릭 관련카메라 권한 오류OutOfMemoryError다음 단계지원