Getting Started

Overview

This guide provides step-by-step instructions for installing and initially configuring the Petnow Android SDK in your project.

Prerequisites

Before you begin, ensure you have the following:

• A project targeting Android API 28 (Android 9.0) or higher
• compileSdk 34 or higher
• Java 17 or higher
• Kotlin 1.9 or higher
• Petnow API key (contact support@petnow.io if you haven't received one)
• AWS CLI installed and configured

Step 1: SDK Installation

The Petnow Android SDK is distributed through AWS CodeArtifact.

Install and Configure AWS CLI

1. Install AWS CLI

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

2. Configure AWS CLI

   Configure the CLI with your AWS credentials:

   aws configure

Add Petnow Maven Repository

Add the Petnow Maven repository to your project's settings.gradle.kts or root build.gradle.kts file:

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

Add Dependencies

Add the following dependencies to your app's build.gradle.kts file:

dependencies {
    // Petnow SDK
    implementation("io.petnow:ui:1.3.0")
    implementation("io.petnow:api-client:1.3.0")
}

Step 2: Project Configuration

Configure AndroidManifest.xml

Add the following permissions and settings to your app's AndroidManifest.xml file:

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

    <!-- Internet permission (required) -->
    <uses-permission android:name="android.permission.INTERNET"/>

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

</manifest>

Note: Camera permissions are automatically requested by the SDK.

Import Modules

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

Step 3: SDK Initialization

Initialize API Client

Initialize the Petnow API client in your application's onCreate() method:

import android.app.Application
import android.util.Log
import io.petnow.api.client.PetnowApiClient

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

        PetnowApiClient.init(
            key = "YOUR_API_KEY",
            isDebugMode = BuildConfig.DEBUG,
            onSuccess = { result ->
                Log.d("PetnowSDK", "API client initialized successfully")
            },
            onError = { exception ->
                Log.e("PetnowSDK", "Failed to initialize API client", exception)
            }
        )
    }
}

isDebugMode parameter:

• true: Connects to Stage (development) environment
• false: Connects to Production environment

Recommended: Use BuildConfig.DEBUG to automatically switch environments.

Configure Detection Mode

// For dog profile registration
PetnowApiClient.configureDetectionMode(
    purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
    species = PetSpecies.DOG,
    enableFakeDetection = true
)

// Or for cat verification
PetnowApiClient.configureDetectionMode(
    purpose = DetectionPurpose.PET_VERIFICATION,
    species = PetSpecies.CAT,
    enableFakeDetection = false
)

Parameter Descriptions

purpose options:

• DetectionPurpose.PET_PROFILE_REGISTRATION - Profile registration
• DetectionPurpose.PET_IDENTIFICATION - Identification
• DetectionPurpose.PET_VERIFICATION - Verification

species options:

• PetSpecies.DOG - Dog (nose detection)
• PetSpecies.CAT - Cat (face detection)

Create Capture Session

import java.util.UUID

lifecycleScope.launch {
    // Obtain captureSessionId from your server
    // (Server calls Petnow Server API's createCaptureSession)
    val captureSessionId: UUID = yourServerApi.createCaptureSession(
        species = "DOG",
        purpose = "PET_PROFILE_REGISTRATION"
    )
    
    // Pass captureSessionId when navigating to camera fragment
    navigateToCameraFragment(captureSessionId)
}

For detailed information on passing captureSessionId, refer to UI Module Overview.

Step 4: Verify Installation

To verify that the SDK is installed correctly, build and run your app.

import io.petnow.api.client.PetnowApiClient

// Check initialization status
if (PetnowApiClient.isSuccessInitialize) {
    Log.d("PetnowSDK", "SDK initialization successful")
} else {
    Log.e("PetnowSDK", "SDK initialization failed")
}

Troubleshooting

Package Not Found

Symptom: Gradle sync fails, dependencies cannot be found

Solution:

1. Verify CodeArtifact Authentication

   # Check environment variables
   echo $CODEARTIFACT_URL
   echo $CODEARTIFACT_AUTH_TOKEN

2. Refresh Token

   • CodeArtifact tokens expire after 12 hours
   • Get a new token with aws codeartifact get-authorization-token

3. Clear Gradle Cache

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

API Key Error

Symptom: Authentication error during initialization

Solution:

• Verify your API key is correct
• Check Debug/Production environment setting
• Contact support@petnow.io

Camera Permission Error

Symptom: Camera doesn't display or permission request fails

Solution:

• The SDK automatically requests camera permissions
• If the user denies permission, guide them to manually grant it in settings

OutOfMemoryError

Symptom: Out of memory error during image processing

Solution:

• Verify that android:largeHeap="true" is added in AndroidManifest.xml
• Clear unnecessary image caches

Next Steps

Installation and setup are complete! You're now ready to use the SDK.

• UI Module Overview - Understand the UI module structure
• Basic Usage - Integrate camera UI

Support

If you encounter any issues during installation, please contact support@petnow.io.