# ProofMode Android Example
This is a complete Android application demonstrating the usage of the ProofMode Rust library for generating and verifying cryptographic proofs for photos.
## Features
- **Generate Proofs**: Take photos with camera or select from gallery to create cryptographic proofs
- **Verify Proofs**: Check existing proof bundles for authenticity
- **Display Proof Information**: View detailed proof data including hash, timestamp, location, and device info
- **Share Proofs**: Export and share proof bundles with other apps
- **Progress Tracking**: Real-time progress updates during proof generation
- **Permission Handling**: Graceful handling of camera, storage, and location permissions
## Quick Setup
### Option 1: Automated Setup (Recommended)
Run the automated setup script from the project root:
```bash
# This will build everything needed for Android
./scripts/setup-android.sh
```
This will:
1. Install Android targets
2. Set up Android NDK (if available)
3. Build native libraries for all Android architectures
4. Generate Kotlin bindings
5. Create AAR structure
6. Configure the Android project
### Option 2: Manual Setup
#### Step 1: Build Native Libraries
From the project root directory:
```bash
# Setup Android environment
./scripts/setup-android.sh
# Build AAR structure
./scripts/android/build-aar.sh
```
#### Step 2: Build AAR
```bash
# Navigate to AAR directory and build
cd target/aar
./gradlew assembleRelease
```
#### Step 3: Setup Android Studio Project
```bash
# Setup Android Studio project with AAR
./scripts/android/setup-studio-project.sh
```
#### Step 4: Open in Android Studio
1. Open Android Studio
2. Select "Open an existing Android Studio project"
3. Navigate to and select the `android-example/` directory
4. Wait for Gradle sync to complete
5. Build and run the app
## Prerequisites
- **Android Studio**: Arctic Fox (2020.3.1) or newer
- **Android SDK**: API 21 (minimum) to API 34 (target)
- **Kotlin**: 1.9.22 or newer
- **Gradle**: 8.0 or newer
- **Android NDK**: For building native libraries (optional if using prebuilt)
## Project Structure
```
android-example/
├── app/
│ ├── src/main/
│ │ ├── java/org/proofmode/android/example/
│ │ │ ├── MainActivity.kt # Main activity
│ │ │ ├── ProofDetailActivity.kt # Proof details view
│ │ │ └── proofmode/ # ProofMode integration
│ │ │ ├── ProofModeManager.kt # Main ProofMode wrapper
│ │ │ ├── LocationProviderImpl.kt # GPS location provider
│ │ │ ├── DeviceInfoProviderImpl.kt # Device info collector
│ │ │ └── NetworkInfoProviderImpl.kt # Network info provider
│ │ ├── res/ # Android resources
│ │ └── AndroidManifest.xml # App manifest
│ ├── libs/ # AAR dependencies
│ └── build.gradle # App build configuration
├── build.gradle # Project build configuration
└── README.md # This file
```
## Usage
### Generating a Proof
1. Launch the app
2. Tap "Generate Proof"
3. Choose to either:
- Take a new photo with the camera
- Select an existing photo from the gallery
4. The app will automatically:
- Calculate the SHA-256 hash
- Collect device and location metadata (if permitted)
- Generate a PGP signature
- Save the proof bundle to storage
### Verifying a Proof
1. Tap "Verify Proof"
2. Select a proof bundle from storage
3. View the verification results including:
- Proof validity status
- Original image
- Cryptographic hash
- Location data (if included)
- Device information
- Digital signature verification
## Integration Notes
The example app includes implementations of all required ProofMode interfaces:
- **LocationProviderImpl**: Uses Android's LocationManager for GPS data
- **DeviceInfoProviderImpl**: Collects device manufacturer, model, OS version, etc.
- **NetworkInfoProviderImpl**: Gathers network type, carrier, and WiFi information
- **ProofModeManager**: Main wrapper class that coordinates proof generation and verification
To integrate ProofMode into your own app:
1. Include the ProofMode AAR in your project
2. Copy the provider implementations or create your own
3. Initialize ProofMode with your configuration
4. Call proof generation/verification methods as needed
## Permissions
The app requires these permissions (defined in AndroidManifest.xml):
- **CAMERA**: For taking photos
- **READ_EXTERNAL_STORAGE**: For accessing existing photos
- **WRITE_EXTERNAL_STORAGE**: For saving proof files
- **ACCESS_FINE_LOCATION**: For GPS data in proofs (optional)
- **ACCESS_COARSE_LOCATION**: For approximate location (optional)
- **INTERNET**: For network connectivity checks
- **ACCESS_NETWORK_STATE**: For network type detection
All permissions are requested at runtime following Android best practices.
## Architecture
The app follows Android development best practices:
- **MVVM Architecture**: Clean separation between UI, business logic, and data
- **Kotlin Coroutines**: For asynchronous operations
- **Material Design**: Modern Android UI components
- **Permission Handling**: Runtime permission requests with graceful fallbacks
- **Error Handling**: Comprehensive error management with user feedback
## Building and Testing
### Debug Build
```bash
cd android-example
./gradlew assembleDebug
```
### Release Build
```bash
cd android-example
./gradlew assembleRelease
```
### Running Tests
```bash
cd android-example
./gradlew test
./gradlew connectedAndroidTest
```
### Installing on Device
```bash
cd android-example
./gradlew installDebug
```
## Troubleshooting
### Common Issues
**"Library not found" errors**
- Ensure the AAR is properly built and included
- Check that native libraries exist for your target architecture
- Verify the AAR is in the `app/libs/` directory
**"UnsatisfiedLinkError" on app launch**
- The native library couldn't be loaded
- Check that the correct architecture library is included
- Verify the library was built with the correct NDK version
**Permission denied errors**
- Ensure all required permissions are declared in AndroidManifest.xml
- Check that runtime permissions are properly requested
- Test on a device with appropriate permissions granted
**Gradle sync issues**
- Check that all dependency versions are compatible
- Ensure Android SDK and build tools are up to date
- Try cleaning and rebuilding the project
### Performance Notes
- Proof generation is CPU-intensive and runs on a background thread
- Large images may take several seconds to process
- Consider implementing progress indicators for better UX
- Test on various device specifications for performance validation
## Development
### Adding New Features
1. **New Metadata Types**: Extend the provider interfaces to collect additional data
2. **Enhanced UI**: Improve the user interface with additional Material Design components
3. **Batch Processing**: Add support for processing multiple images at once
4. **Cloud Integration**: Add support for uploading proofs to cloud storage
5. **Advanced Verification**: Implement additional verification methods
### Testing
- **Unit Tests**: Test business logic and ProofMode integration
- **Instrumentation Tests**: Test UI interactions and Android-specific functionality
- **Manual Testing**: Test on various devices and Android versions
- **Performance Testing**: Profile app performance during proof generation
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
## License
This example app is part of the ProofMode-Rust project and follows the same Apache 2.0 license terms.
## Support
For issues and questions:
1. Check the troubleshooting section above
2. Review the main ProofMode documentation
3. Open an issue on the project repository
4. Consult the Android development documentation for platform-specific issues