Skip to main content

iOS App

This guide is for developers building or customizing the LeadHub iOS companion app. The app source code is written in Swift and targets iPhone and iPad.

Requirementsโ€‹

  • Xcode 15 or later (macOS only)
  • Swift 5.9 or later
  • iOS deployment target: iOS 15.0 minimum
  • An Apple Developer account (required for TestFlight and App Store distribution)
  • A LeadHub instance with a valid HTTPS URL and an active API key

Project Setupโ€‹

  1. Open the ios/ folder from your LeadHub purchase in Xcode.
  2. Open the .xcworkspace file (not the .xcodeproj) if CocoaPods or Swift Package Manager dependencies are present.
  3. Select your development team in the project's Signing & Capabilities settings.
  4. Build and run on a simulator or device.

Architectureโ€‹

The app uses a standard iOS architecture:

  • URLSession with a custom API client for HTTP calls to the LeadHub REST API
  • Combine or async/await for asynchronous operations
  • SwiftUI for the user interface
  • CoreData for local caching of leads between sessions
  • Apple Push Notification Service (APNs) for push notifications

API keys are stored in the iOS Keychain using the Security framework.

Authentication Flowโ€‹

  1. The user enters their LeadHub instance URL and API key on the onboarding screen.
  2. The app makes a GET /api/v1/health request to verify the instance is reachable over HTTPS.
  3. It verifies the API key is valid by making a test authenticated request.
  4. The URL and API key are stored in the Keychain.

Push Notificationsโ€‹

Push notifications use Apple Push Notification Service (APNs).

  1. In your Apple Developer account, create an APNs key (.p8 file) under Certificates, Identifiers & Profiles โ†’ Keys.
  2. Note the Key ID and your Team ID.
  3. In your LeadHub backend configuration, set APNS_KEY, APNS_KEY_ID, APNS_TEAM_ID, and APNS_BUNDLE_ID.
  4. In Xcode, enable the Push Notifications capability under Signing & Capabilities.

The app registers for push notifications on first launch and sends the device token to the LeadHub backend via the API.

Building for Distributionโ€‹

  1. Archive the app via Product โ†’ Archive in Xcode.
  2. In the Organizer window, click Distribute App.
  3. Choose App Store Connect for App Store distribution, or TestFlight for beta testing.
  4. Follow the Xcode prompts to upload.

API Endpoints Usedโ€‹

EndpointPurpose
GET /api/v1/healthVerify instance connectivity
GET /api/v1/leadsLoad leads list
GET /api/v1/leads/{id}Load lead detail
PATCH /api/v1/leads/{id}Update lead status or stage
POST /api/v1/leads/{id}/tagsAdd tag to lead
GET /api/v1/pipelinesLoad pipeline list for stage picker

Minimum Required API Key Scopesโ€‹

ScopeReason
read:leadsView leads
write:leadsUpdate lead status, stage, and tags
read:pipelinesPopulate the pipeline stage picker

App Store Privacy Disclosureโ€‹

When submitting to the App Store, declare the following data usage in your App Privacy section:

  • Contact Info (email, phone) โ€” collected from leads, not users
  • Identifiers (API key) โ€” linked to the user, used for authentication
  • Usage Data โ€” not collected