# Android Custom API IP Configuration

**Author**: Matthew Raymer  
**Date**: 2025-01-27  
**Status**: ✅ **COMPLETE** - Custom API IP support for physical device development

## Overview

When deploying TimeSafari to physical Android devices during development, you may need to specify a custom IP address for the claim API server. This is necessary because physical devices cannot access `localhost` or `10.0.2.2` (Android emulator IP) to reach your local development server.

## Problem

During Android development:
- **Emulator**: Uses `10.0.2.2:3000` to access host machine's localhost (default)
- **Physical Device**: Cannot access `localhost` or `10.0.2.2` - needs actual IP address

## Solution

The Android build system defaults to `10.0.2.2:3000` for emulator development and supports specifying a custom IP address for the claim API server when building for physical devices.

## Usage

### Command Line Usage

```bash
# Default behavior (uses 10.0.2.2 for emulator)
./scripts/build-android.sh --dev

# Custom IP for physical device
./scripts/build-android.sh --dev --api-ip 192.168.1.100

# Test environment with custom IP
./scripts/build-android.sh --test --api-ip 192.168.1.100

# Build and auto-run with custom IP
./scripts/build-android.sh --dev --api-ip 192.168.1.100 --auto-run
```

### NPM Scripts

```bash
# Default development build (uses 10.0.2.2 for emulator)
npm run build:android:dev

# Development build with custom IP (requires IP parameter)
npm run build:android:dev:custom 192.168.1.100

# Test build with custom IP (requires IP parameter)
npm run build:android:test:custom 192.168.1.100

# Development build + auto-run with custom IP
npm run build:android:dev:run:custom 192.168.1.100

# Test build + auto-run with custom IP
npm run build:android:test:run:custom 192.168.1.100
```

## Examples

### Scenario 1: Development on Emulator (Default)

```bash
# Default behavior - uses 10.0.2.2 for emulator
npm run build:android:dev

# Build and immediately run on emulator
npm run build:android:dev:run
```

### Scenario 2: Development on Physical Device

```bash
# Your development server is running on 192.168.1.50:3000
npm run build:android:dev:custom 192.168.1.50

# Build and immediately run on device
npm run build:android:dev:run:custom 192.168.1.50
```

### Scenario 3: Testing on Physical Device

```bash
# Your test server is running on 192.168.1.75:3000
npm run build:android:test:custom 192.168.1.75

# Build and immediately run on device
npm run build:android:test:run:custom 192.168.1.75
```

### Scenario 4: Direct Script Usage

```bash
# Default behavior (emulator)
./scripts/build-android.sh --dev --studio

# Custom IP for physical device
./scripts/build-android.sh --dev --api-ip 192.168.1.100 --studio
./scripts/build-android.sh --test --api-ip 192.168.1.100 --apk
```

## How It Works

### Environment Variable Override

The build system handles API server configuration as follows:

1. **Default behavior**: Uses `http://10.0.2.2:3000` for emulator development
2. **Custom IP specified**: Overrides with `http://<custom-ip>:3000` for physical device development
3. **Maintains other APIs**: Image and Partner APIs remain at production URLs
4. **Logs the configuration**: Shows which IP is being used in build logs

### Build Process

```bash
# Development mode with default IP (10.0.2.2)
export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
npm run build:capacitor -- --mode development

# Development mode with custom IP
export VITE_DEFAULT_ENDORSER_API_SERVER="http://192.168.1.100:3000"
npm run build:capacitor -- --mode development
```

### Default Behavior

- **No `--api-ip` specified**: Uses default emulator IP (`10.0.2.2:3000`)
- **Custom IP specified**: Uses provided IP address for physical device development
- **Invalid IP format**: Build will fail with clear error message
- **Network unreachable**: App will show connection errors at runtime

## Finding Your IP Address

### On Linux/macOS

```bash
# Find your local IP address
ifconfig | grep "inet " | grep -v 127.0.0.1
# or
ip addr show | grep "inet " | grep -v 127.0.0.1
```

### On Windows

```bash
# Find your local IP address
ipconfig | findstr "IPv4"
```

### Common Network Patterns

- **Home WiFi**: Usually `192.168.1.x` or `192.168.0.x`
- **Office Network**: May be `10.x.x.x` or `172.16.x.x`
- **Mobile Hotspot**: Often `192.168.43.x`

## Troubleshooting

### Common Issues

#### 1. Device Cannot Connect to API

```bash
# Check if your IP is accessible
ping 192.168.1.100

# Check if port 3000 is open
telnet 192.168.1.100 3000
```

#### 2. Build Fails with Invalid IP

```bash
# Ensure IP format is correct
./scripts/build-android.sh --dev --api-ip 192.168.1.100  # ✅ Correct
./scripts/build-android.sh --dev --api-ip localhost        # ❌ Wrong
```

#### 3. Firewall Blocking Connection

```bash
# Check firewall settings
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-all  # CentOS/RHEL
```

### Debug Mode

```bash
# Enable verbose logging
./scripts/build-android.sh --dev --api-ip 192.168.1.100 --verbose
```

## Best Practices

### 1. Use Consistent IP Addresses

```bash
# Create aliases for common development scenarios
alias build-dev="npm run build:android:dev:custom 192.168.1.100"
alias build-test="npm run build:android:test:custom 192.168.1.100"
```

### 2. Document Your Setup

```bash
# Create a development setup file
echo "DEV_API_IP=192.168.1.100" > .env.development
echo "TEST_API_IP=192.168.1.100" >> .env.development
```

### 3. Network Security

- Ensure your development server is only accessible on your local network
- Use HTTPS in production environments
- Consider VPN for remote development scenarios

### 4. Team Development

```bash
# Share IP configuration with team
# Add to .env.example
DEV_API_IP=192.168.1.100
TEST_API_IP=192.168.1.100
```

## Integration with CI/CD

### Environment Variables

```yaml
# Example CI/CD configuration
variables:
  DEV_API_IP: "192.168.1.100"
  TEST_API_IP: "192.168.1.100"

build:
  script:
    - npm run build:android:dev:custom $DEV_API_IP
```

### Automated Testing

```bash
# Test with different IP configurations
npm run build:android:test:custom 192.168.1.100
npm run build:android:test:custom 10.0.0.100
```

## Migration from Legacy

### Previous Workarounds

Before this feature, developers had to:
1. Manually edit environment files
2. Use different build configurations
3. Modify source code for IP addresses

### New Approach

```bash
# Simple one-liner
npm run build:android:dev:custom 192.168.1.100
```

## Future Enhancements

### Planned Features

1. **IP Validation**: Automatic IP format validation
2. **Network Discovery**: Auto-detect available IP addresses
3. **Port Configuration**: Support for custom ports
4. **Multiple APIs**: Support for custom IPs for all API endpoints

### Integration Opportunities

1. **Docker Integration**: Automatic IP detection in containerized environments
2. **Network Profiles**: Save and reuse common network configurations
3. **Hot Reload**: Automatic rebuild when IP changes

---

**Status**: Complete and ready for production use  
**Last Updated**: 2025-01-27  
**Version**: 1.0  
**Maintainer**: Matthew Raymer