Skip to content

README.md

Latest commit

 

History

History
146 lines (111 loc) · 4.47 KB

README.md

File metadata and controls

146 lines (111 loc) · 4.47 KB

OOTO Face API — iOS Demo (UIKit + Storyboard)

A minimal demonstration app showing how to integrate iOS with OOTO Face API services.
This project is for evaluation and learning only (not production).

What this demo does

  • Take photo — opens the camera and shows a preview.
  • Enroll — sends the captured photo to create a face template.
  • Search — performs 1:N face identification against existing templates.
  • Delete — deletes a template by templateId (appears after you get one from Enroll or Search).

API endpoints used

All requests include APP-ID and APP-KEY HTTP headers.

  • Enroll — POST /add
    • Query (optional): check_liveness=true|false, check_deepfake=true|false
    • Body: multipart/form-data with:
      • photo: JPEG/PNG file
      • templateId (optional): string
  • Search (Identify) — POST /identify
    • Query (optional): check_liveness=true|false, check_deepfake=true|false
    • Body: multipart/form-data with:
      • photo: JPEG/PNG file
  • Delete — POST /delete
    • Body: JSON 
      { "templateId": "<ID>" }

Notes

  • On successful Search, the app displays templateId and similarity.
  • If the backend indicates no detectable face, the app shows No faces found.
  • Delete is manual via button (not automatic).

Requirements

  • Xcode 14+
  • iOS 13+ (uses SceneDelegate)
  • Real device for camera testing (the iOS Simulator camera isn’t supported)
  • OOTO credentials: APP-ID, APP-KEY

Project structure

OotoFaceApiExample/
├─ OotoFaceApiExample.xcodeproj
├─ OotoFaceApiExample/
│  ├─ AppDelegate.swift
│  ├─ SceneDelegate.swift
│  ├─ APIConstants.swift        // Base URL, endpoints, APP-ID/APP-KEY
│  ├─ APIClient.swift           // Enroll / Identify / Delete requests
│  ├─ Models/
│  │  ├─ IdentifyResponse.swift // Identify + generic API error models
│  │  └─ DeleteResponse.swift   // DeleteRequest / DeleteSuccessResponse
│  ├─ ViewController.swift      // Camera + buttons + result handling
│  ├─ Base.lproj/Main.storyboard
│  ├─ Assets.xcassets/
│  └─ Info.plist
└─ README.md

Setup

  1. Clone

    git clone https://github.com/OOTO-AI/SwiftOotoFaceApiExample.git
cd SwiftOotoFaceApiExample

  2. Open in Xcode
    Open OotoFaceApiExample.xcodeproj.

  3. Configure credentials
    Edit APIConstants.swift:

    struct APIConstants {
    static let baseURL = URL(string: "https://cloud.ooto-ai.com/api/v1.0")!
    static let identifyEndpoint = "/identify"
    static let addTemplateEndpoint = "/add"
    static let deleteEndpoint = "/delete"

    static let appId  = "<YOUR_APP_ID>"
    static let appKey = "<YOUR_APP_KEY>"
}

  4. Camera permission
    Ensure Info.plist contains:

    <key>NSCameraUsageDescription</key>
<string>Camera access is required to take a face photo.</string>

  5. Run on device
    Select a physical iPhone target and press ⌘R.

Usage (UI flow)

  • Launch screen shows: Take photo, Enroll (disabled), Search (disabled).
  • Tap Take photo → capture → preview appears → Enroll and Search become enabled.
  • Tap Enroll → calls /add → shows returned templateId → Delete appears.
  • Tap Search → calls /identify → shows templateId + similarity if matched → Delete appears.
  • Tap Delete → calls /delete with the last templateId → shows result.

Implementation details

  • Networking: URLSession.
    • Enroll & Search: manual multipart/form-data body with photo.
    • Delete: application/json body ({"templateId":"..."}).
  • UI: UIKit + Storyboard (single UIViewController).
    • Take photo: full-width row.
    • Enroll & Search: one row, equal widths.
    • Delete: separate row, hidden until a templateId exists.
    • Results UILabel is multiline with wrapping for long IDs.
  • Concurrency: main-thread UI updates, simple activity indicator, buttons disabled during in-flight requests.

Error handling

  • Network issues → Network error: <message>.
  • API errors → server info message is shown.
  • “No faces found” when the backend signals no detectable face.
  • Defensive UI guards to avoid crashes if an IBOutlet is accidentally disconnected during storyboard edits.

License

MIT