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)

Step 1: SDK Installation

The Petnow Android SDK is distributed through AWS CodeArtifact.

Install AWS CLI

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

Obtain Credentials from Petify Console

Issue AWS Credentials from Petify Console and set all provided values as environment variables:

Petify Console – AWS CodeArtifact credentials screen

export AWS_ACCESS_KEY_ID=<from Petify Console>
export AWS_SECRET_ACCESS_KEY=<from Petify Console>
export AWS_DEFAULT_REGION=<from Petify Console>
export PETNOW_CODEARTIFACT_DOMAIN=<from Petify Console>
export PETNOW_AWS_ACCOUNT_ID=<from Petify Console>
export PETNOW_ANDROID_SDK_REPOSITORY=<from Petify Console>

Add Petnow Maven Repository

Derive the repository URL and auth token from your credentials:

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)

Token expiry: Re-run both commands every 12 hours, or whenever a Gradle sync fails with an authentication error.

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

Using the UI module does not require a separate api-client dependency. If you need server API calls, handle them from your own backend.

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>

Setting	Description
`INTERNET`	Required for API communication and license verification
`largeHeap="true"`	Recommended for optimal performance during image processing and detection tasks

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 UI Client

Required: You must call PetnowUiClient.initialize() before using PetnowCameraFragment. The fragment will automatically close if not initialized.

Initialize the UI module client in your application's onCreate() method:

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

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

        PetnowUiClient.init(
            key = "YOUR_API_KEY",
            isDebugMode = false
        )

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

isDebugMode is deprecated. Always pass false.

Configure Detection Mode

Important: You must configure detection before navigating to the fragment that inherits from 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

// For dog profile registration
PetnowUiClient.configureDetection(
    DetectionConfiguration(
        purpose = DetectionPurpose.PET_PROFILE_REGISTRATION,
        species = PetSpecies.DOG,
        enableFakeDetection = true
    )
)

// Or for cat verification
PetnowUiClient.configureDetection(
    DetectionConfiguration(
        purpose = DetectionPurpose.PET_VERIFICATION,
        species = PetSpecies.CAT,
        enableFakeDetection = false
    )
)

Parameter Descriptions

Parameter	Description
`purpose`	Capture purpose. Determines the number of images required.
`species`	Pet species. Determines the detection pipeline.
`enableFakeDetection`	Whether to enable fake image detection

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

Required: Before navigating to PetnowCameraFragment, you must create a capture session on your server and obtain the captureSessionId.

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

Server API: The captureSessionId is generated on your server through the Petnow Server API. Do not generate it on the client.

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.ui.config.PetnowUiClient

// Check initialization status
if (PetnowUiClient.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:

Verify CodeArtifact Authentication

# Check environment variables
echo $CODEARTIFACT_URL
echo $CODEARTIFACT_AUTH_TOKEN

Refresh Token

CodeArtifact tokens expire after 12 hours
Re-run the token generation command:

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)

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.

Getting Started

Store credentials permanently with aws configure (Optional)

On this page