Getting Started

Overview

This guide provides step-by-step instructions for installing the Petnow iOS SDK in your project and completing initial setup.

Prerequisites

Before you begin, please prepare the following:

• Xcode project targeting iOS 16.0 or later
• Xcode 16.0 or later
• Petnow API key (Contact support@petnow.io if you haven't received one)
• For AWS CodeArtifact: AWS CLI installation and configuration

Step 1: SDK Installation

The Petnow iOS SDK is distributed through AWS CodeArtifact.

AWS CLI Installation and Configuration

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

Swift Package Manager (AWS CodeArtifact)

Choose one based on your project type:

Option A: Package.swift Project

For projects with a Package.swift file, simply run this command:

1. Navigate to project root directory:

cd /path/to/your-project  # Directory containing Package.swift

2. Login to AWS CodeArtifact:

aws codeartifact login --tool swift \
  --domain PETNOW_CODEARTIFACT_DOMAIN \
  --domain-owner PETNOW_AWS_ACCOUNT_ID \
  --repository PETNOW_IOS_SDK_REPOSITORY

3. Verify success:

# On success, outputs:
Successfully configured credentials for codeartifact-DOMAIN-ACCOUNT_ID-REPOSITORY

# Check Registry file:
cat ~/.swiftpm/configuration/registries.json

Placeholder values explained:

• PETNOW_CODEARTIFACT_DOMAIN: CodeArtifact domain provided by Petnow
• PETNOW_AWS_ACCOUNT_ID: AWS account ID
• PETNOW_IOS_SDK_REPOSITORY: Repository name

Note: Authentication tokens are valid for 12 hours. Re-run the command above when expired.

Option B: Xcode Workspace

Add Package in Xcode

1. Open your project in Xcode
2. Select File > Add Packages...
3. Search for the petnow.ui package from the configured CodeArtifact repository
4. Click Add Package

Important: You must press enter after typing the package name. Otherwise, it won't be found.

Verify Installation

Once the package is successfully added, you can verify it in the Package Dependencies section of the project navigator.

Step 2: Project Configuration

Add Info.plist Permissions

For the SDK to use the camera, you must add permission descriptions to Info.plist.

Add the "Privacy - Camera Usage Description" or "NSCameraUsageDescription" key and enter a string explaining the camera usage purpose.

Required Permission

<!-- Camera access permission (required) -->
<key>NSCameraUsageDescription</key>
<string>Camera access is required for pet detection and identification.</string>

Important: Without permission description, the app will crash when accessing the camera.

Import Module

import PetnowUI

Step 3: Create Capture Session

// Get captureSessionId from your server
// (Server calls Petnow Server API's createCaptureSession)
let captureSessionId: UUID = await yourServerAPI.createCaptureSession(
    species: "DOG",
    purpose: "PET_PROFILE_REGISTRATION"
)

For detailed session concept, refer to UI Module Overview.

Step 4: Camera Initialization

Initialize the camera using PetnowUI's CameraViewModel. API key and environment settings are passed through LicenseInfo.

import SwiftUI
import PetnowUI

struct PetCameraView: View {
    @StateObject private var cameraViewModel: CameraViewModel
    private let captureSessionId: UUID  // Session ID from server
    
    init(captureSessionId: UUID) {
        self.captureSessionId = captureSessionId
        _cameraViewModel = StateObject(wrappedValue: CameraViewModel(
            species: .dog,                      // .dog or .cat
            cameraPurpose: .forRegisterFromProfile  // Capture purpose
        ))
    }
    
    var body: some View {
        CameraView(viewModel: cameraViewModel)
            .task {
                await initializeCamera()
            }
    }
    
    private func initializeCamera() async {
        do {
            try await cameraViewModel.initializeCamera(
                licenseInfo: LicenseInfo(
                    apiKey: "YOUR_API_KEY",
                    isDebugMode: isDebugBuild()
                ),
                initialPosition: .back,
                captureSessionId: captureSessionId
            ) { result in
                // Process capture result
                print("Capture complete: \(result)")
            }
        } catch {
            print("Camera initialization failed: \(error)")
        }
    }
    
    private func isDebugBuild() -> Bool {
        #if DEBUG
        return true
        #else
        return false
        #endif
    }
}

LicenseInfo Parameters

LicenseInfo configures API key and server environment:

LicenseInfo(
    apiKey: "YOUR_API_KEY",  // Petnow API key
    isDebugMode: true         // true: Stage, false: Production
)

Recommendation: Use Swift's #if DEBUG conditional compilation to automatically switch environments.

Step 5: Verify Installation

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

If camera initialization succeeds, the camera preview will be displayed. If it fails, check the error message:

do {
    try await cameraViewModel.initializeCamera(
        licenseInfo: LicenseInfo(apiKey: "YOUR_API_KEY", isDebugMode: true),
        initialPosition: .back,
        captureSessionId: captureSessionId
    ) { result in
        print("Capture complete")
    }
    print("Camera initialization successful")
} catch {
    print("Initialization failed: \(error.localizedDescription)")
}

Troubleshooting

Package Not Found (Package Resolution Failed)

Symptom: "package 'PetnowUI' not found" or similar error in Xcode

Solution:

1. Check Registry Configuration

   # Xcode Workspace project
   cat YourApp.xcworkspace/xcshareddata/swiftpm/configuration/registries.json
   
   # Package.swift project
   cat ~/.swiftpm/configuration/registries.json

   If the file is missing or empty, login again from project root:

   cd /path/to/YourApp  # Directory containing .xcworkspace file
   aws codeartifact login --tool swift \
     --domain PETNOW_CODEARTIFACT_DOMAIN \
     --domain-owner PETNOW_AWS_ACCOUNT_ID \
     --repository PETNOW_IOS_SDK_REPOSITORY

2. Check Token Expiration

   • Tokens expire after 12 hours
   • Re-run the aws codeartifact login command

3. Clear Xcode Cache

   # Delete SPM cache
   rm -rf ~/Library/Caches/org.swift.swiftpm
   rm -rf ~/Library/Developer/Xcode/DerivedData
   
   # Restart Xcode then File > Packages > Reset Package Caches

Missing Registry Configuration (Xcode Workspace)

Symptom: Xcode can't find package even after login

Cause: aws codeartifact login --tool swift only saves configuration to ~/.swiftpm/, which Xcode Workspace doesn't recognize

Solution: Follow the Registry configuration copy process in Option B

# Copy to Xcode Workspace
mkdir -p YourApp.xcworkspace/xcshareddata/swiftpm/configuration
cp ~/.swiftpm/configuration/registries.json YourApp.xcworkspace/xcshareddata/swiftpm/configuration/

Camera Permission Error

Symptom: App crashes or permission request doesn't appear
Solution: Verify NSCameraUsageDescription is added to Info.plist

API Key Error

Symptom: Authentication error during camera initialization
Solution: Verify API key is correct and contact Petnow team

Next Steps

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

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

Support

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