Android App

This guide is for developers building or customizing the LeadHub Android companion app. The app source code is written in Kotlin and follows standard Android development patterns.

---

Requirements

• Android Studio (latest stable release)
• JDK 17 or later
• Android SDK — minimum API level 26 (Android 8.0)
• A LeadHub instance with a valid HTTPS URL and an active API key

---

Project Setup

1. Open the android/ folder from your LeadHub purchase in Android Studio.
2. Let Gradle sync and download dependencies automatically.
3. Open app/src/main/res/values/config.xml (or the equivalent config file in the project) and set your default instance URL if you want to pre-fill it for users.

---

Architecture

The app uses a standard Android architecture:

• Retrofit for HTTP calls to the LeadHub REST API
• ViewModel + LiveData for UI state management
• Room for local caching of leads between sessions
• Firebase Cloud Messaging (FCM) for push notifications

All API calls use the Authorization: Bearer {api_key} header pattern. The API key is stored in Android's EncryptedSharedPreferences.

---

Authentication Flow

1. The user enters their LeadHub instance URL and API key on the login screen.
2. The app calls GET /api/v1/health to verify the instance is reachable.
3. It then calls GET /api/v1/users/me (or equivalent) to verify the key is valid and fetch the user profile.
4. The URL and key are stored in EncryptedSharedPreferences for subsequent launches.

---

Push Notifications

Push notifications are delivered through Firebase Cloud Messaging. To enable them:

1. Create a Firebase project at console.firebase.google.com.
2. Add an Android app to the project with your app's package name.
3. Download google-services.json and place it in the app/ directory.
4. In your LeadHub backend configuration, set FCM_SERVER_KEY to your Firebase server key.

The app registers its FCM token with the LeadHub backend when the user logs in.

---

Building for Release

1. Generate a signing keystore: keytool -genkey -v -keystore leadhub.keystore -alias leadhub -keyalg RSA -keysize 2048 -validity 10000
2. Add signing config to app/build.gradle.
3. Build a signed APK or AAB via Build → Generate Signed Bundle/APK.
4. Upload the AAB to the Google Play Console.

---

API Endpoints Used

The app uses these LeadHub API endpoints. All require a valid Bearer token:

Endpoint	Purpose
GET /api/v1/health	Verify instance connectivity
GET /api/v1/leads	Load 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}/tags	Add tag to lead
GET /api/v1/pipelines	Load pipeline list for stage picker

---

Minimum Required API Key Scopes

Scope	Reason
read:leads	View leads
write:leads	Update lead status, stage, and tags
read:pipelines	Populate the pipeline stage picker