# Heritage Compass Android Beta - Installation Guide

Welcome to the Heritage Compass Android beta program! Follow these simple steps to install the app on your Android phone.

## Requirements
- Android device running Android 7.0 (Nougat) or higher
- Approximately 60MB of free storage space
- Internet connection for initial setup and geocoding

## Installation Steps

### Step 1: Enable Installation from Unknown Sources

Since this is a beta app not distributed through the Google Play Store, you'll need to allow installation from external sources:

1. Open **Settings** on your Android phone
2. Navigate to **Security** or **Privacy** (location varies by device)
3. Look for **Install unknown apps** or **Unknown sources**
4. Find your web browser (Chrome, Firefox, etc.) in the list
5. Toggle the switch to **Allow from this source**

**Note:** On newer Android versions (8.0+), you grant permission per app rather than globally. You only need to allow your browser to install apps.

### Step 2: Download the App

1. Open this link on your Android phone:
   ```
   https://siorailabs.com/downloads/heritage-compass-android-beta-release.apk
   ```

2. Your browser will download the APK file (approximately 53MB)

3. You may see a warning message - this is normal for apps outside the Play Store

4. Tap **Download anyway** or **OK** to continue

### Step 3: Install the App

1. Once downloaded, tap **Open** in the download notification
   - OR go to your **Downloads** folder and tap the APK file

2. You'll see an install confirmation screen

3. Tap **Install**

4. Wait for installation to complete (10-20 seconds)

5. Tap **Open** to launch Heritage Compass

### Step 4: Grant Permissions

On first launch, Heritage Compass will request permissions:

1. **Location Permission** - Required for geofencing and location-based alerts
   - Tap **Allow all the time** or **While using the app**
   - Background location access enables automatic alerts when near ancestral locations

2. **Storage Permission** - Required to access GEDCOM files
   - Tap **Allow**

## Getting Started

### Upload Your GEDCOM File

1. Tap **Upload GEDCOM File** on the home screen

2. Tap **Choose GEDCOM File (.ged)**

3. Navigate to your GEDCOM file and select it

4. Tap **Upload & Process**

5. Wait while the app:
   - Parses your family tree (10-30 seconds)
   - Geocodes location names (1-2 minutes for large files)
   - Creates location events and geofences

6. Once complete, you'll see your heritage statistics on the home screen

### Explore Your Heritage

**Home Tab**
- View statistics (people, families, places, events)
- See background monitoring status
- Upload new GEDCOM files

**Data Tab**
- **People**: Browse individuals, view detailed life stories with narratives
- **Places**: See all ancestral locations with coordinates and event counts
- **Events**: Browse by event type (births, marriages, deaths, etc.)
- **Families**: Explore family units grouped by surname

**Map Tab**
- View all ancestral locations on an interactive map
- See location markers colour-coded by event type
- Tap markers to view details

### Location Alerts

Once you've uploaded your GEDCOM file:

1. Heritage Compass automatically monitors your location in the background
2. When you come within **500 metres** of an ancestral location, you'll receive:
   - A notification alert
   - A personalised voice narrative about your ancestor and that place
3. Voice narrations use appropriate accents:
   - British English for European locations
   - American English for US/Canadian locations

## Troubleshooting

### App Won't Install
- **Solution**: Make sure you've enabled "Install unknown apps" for your browser
- Go to Settings > Security > Install unknown apps > [Your Browser] > Allow

### "App Not Installed" Error
- **Solution**: You may have an older version installed
- Go to Settings > Apps > Heritage Compass > Uninstall
- Then try installing again

### Location Alerts Not Working
- **Solution**: Check location permissions
- Go to Settings > Apps > Heritage Compass > Permissions
- Ensure Location is set to "Allow all the time"

### GEDCOM Upload Fails
- **Solution**: Check file format
- Ensure file is .ged or .gedcom format
- File should be GEDCOM 5.5 or 5.5.1 standard
- Try with a smaller file first to test

### No Voice Narration
- **Solution**: Check volume and TTS settings
- Ensure media volume is turned up
- Go to Settings > Accessibility > Text-to-speech
- Ensure Google TTS or Samsung TTS is enabled

### App Crashes or Freezes
- **Solution**: Clear app data and restart
- Go to Settings > Apps > Heritage Compass > Storage > Clear Cache
- If problem persists, uninstall and reinstall

## Beta Feedback

This is a beta release - your feedback is invaluable!

**How to Report Issues:**
1. Email: martin@siorailabs.com
2. Include:
   - Your device model and Android version
   - Description of the issue
   - Steps to reproduce
   - Screenshots if relevant

**What to Test:**
- GEDCOM file upload and parsing
- Location accuracy on the map
- Data browsing (People, Places, Events, Families)
- Search functionality
- Voice narratives when tapping speaker icons
- Background location monitoring
- Performance and battery usage

## Privacy & Data

- All GEDCOM data is processed **locally** on your device
- Location names are geocoded via Siorai Labs service (cached for efficiency)
- No personal genealogy data is uploaded to servers
- Background location is used only for ancestral geofencing
- You can delete all data by uninstalling the app

## Support

For questions or assistance:
- Email: martin@siorailabs.com
- Web: https://siorailabs.com

Thank you for being part of the Heritage Compass beta program!

---

**Version:** Android Beta Release 2026-04-12
**Build:** Release APK (52.7MB)