시작하기

개요

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

사전 준비사항

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

Android API 28 (Android 9.0) 이상을 타겟으로 하는 프로젝트
compileSdk 34 이상
Java 17 이상
Kotlin 1.9 이상
Petnow API 키 (발급 받지 않았다면 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에서 AWS 자격 증명을 발급하고, 제공된 값으로 환경 변수를 설정하세요:

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가 인증 오류로 실패할 때 두 명령을 모두 다시 실행하세요.

프로젝트의 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.3.3")
}

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"/>

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

</manifest>

설정	설명
`INTERNET`	API 통신 및 라이선스 검증에 필요
`largeHeap="true"`	이미지 처리와 탐지 작업 시 최적의 성능을 위해 권장

참고: 카메라 권한은 SDK에서 자동으로 요청합니다.

모듈 임포트

import io.petnow.ui.PetnowCameraFragment
import io.petnow.callback.PetnowCameraDetectionListener

3단계: SDK 초기화

UI 클라이언트 초기화

필수: PetnowCameraFragment를 사용하기 전에 반드시 PetnowUiClient.initialize()를 호출해야 합니다. 초기화하지 않으면 프래그먼트가 자동으로 종료됩니다.

애플리케이션의 onCreate() 메서드에서 UI 모듈 클라이언트를 초기화합니다:

import android.app.Application
import android.util.Log
import io.petnow.ui.config.PetnowUiClient

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        PetnowUiClient.initialize(
            apiKey = "YOUR_API_KEY",
            isDebugMode = false
        )

        Log.d("PetnowSDK", "UI client initialized successfully")
    }
}

isDebugMode는 deprecated되었습니다. 항상 false를 전달하세요.

탐지 모드 설정

중요: PetnowCameraFragment를 상속하는 프래그먼트로 이동하기 전에 반드시 탐지 설정을 구성해야 합니다.

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

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

// 또는 고양이 인증용
PetnowUiClient.configureDetection(
    DetectionConfiguration(
        purpose = DetectionPurpose.PET_VERIFICATION,
        species = PetSpecies.CAT,
        enableFakeDetection = false
    )
)

파라미터 설명

파라미터	설명
`purpose`	촬영 목적. 목적에 따라 필요한 이미지 수가 결정됩니다.
`species`	반려동물 종류. 탐지 파이프라인이 결정됩니다.
`enableFakeDetection`	가짜 이미지 탐지 활성화 여부

purpose 옵션:

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

species 옵션:

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

캡처 세션 생성

필수: PetnowCameraFragment로 이동하기 전에 반드시 서버에서 캡처 세션을 생성하고 captureSessionId를 받아와야 합니다.

import java.util.UUID

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

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

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

4단계: 설치 확인

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

import io.petnow.ui.config.PetnowUiClient

// 초기화 상태 확인
if (PetnowUiClient.isSuccessInitialize) {
    Log.d("PetnowSDK", "SDK 초기화 성공")
} else {
    Log.e("PetnowSDK", "SDK 초기화 실패")
}

문제 해결

패키지를 찾을 수 없음

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

해결 방법:

CodeArtifact 인증 확인

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

토큰 갱신

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)

Gradle 캐시 삭제

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

API 키 오류

증상: 초기화 시 인증 오류 발생

해결 방법:

API 키가 올바른지 확인
Debug/Production 환경 설정 확인
support@petnow.io로 문의

카메라 권한 오류

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

해결 방법:

SDK가 자동으로 카메라 권한을 요청합니다
사용자가 권한을 거부한 경우, 설정에서 수동으로 권한을 부여하도록 안내하세요

OutOfMemoryError

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

해결 방법:

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

다음 단계

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

UI 모듈 개요 - UI 모듈 구조 이해하기
기본 사용법 - 카메라 UI 통합하기

지원

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

aws configure로 자격 증명 영구 저장 (선택사항)

On this page