feat: Add local development server support for sample app

Add ability to configure the sample app to connect to a local development
server instead of production MaxMind servers. This is useful for testing
the SDK against a local backend.

Configuration via local.properties (gitignored):
- debug.server.url: Custom server URL (e.g., https://localhost:8443)
- debug.ca.cert: Path to CA certificate for self-signed HTTPS

When debug.ca.cert is configured, the build system:
- Copies the certificate to res/raw/debug_ca.crt (gitignored)
- Generates a network_security_config.xml that trusts the bundled cert
- Sets BuildConfig.DEBUG_SERVER_URL for the app to use

Without configuration, the sample app connects to production servers.

Also documents ADB reverse port forwarding for physical device testing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: oschwald

.gitignore

@@ -102,3 +102,6 @@ inputs.csv
 summary.md
 plan.md
 build-log.txt
+
+# Generated debug CA certificate (configured via local.properties)
+sample/src/main/res/raw/debug_ca.crt

SETUP.md

@@ -188,6 +188,98 @@ device-android/
 └── README.md            # Main documentation
 ```
 
+## Local Development Server
+
+The sample app can be configured to connect to a local development server
+instead of the production MaxMind servers. This is useful for testing the SDK
+against a local backend.
+
+### Quick Start
+
+1. **Add to `local.properties`**:
+
+   ```properties
+   debug.server.url=https://localhost:8443
+   debug.ca.cert=/path/to/your/ca.crt
+   ```
+
+2. **Set up ADB reverse port forwarding**:
+
+   ```bash
+   adb reverse tcp:8443 tcp:8443
+   ```
+
+3. **Build and install**:
+
+   ```bash
+   ./gradlew :sample:installDebug
+   ```
+
+### Configuration Options
+
+Add these to `local.properties` (gitignored):
+
+| Property           | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `debug.server.url` | Server URL (e.g., `https://localhost:8443`)  |
+| `debug.ca.cert`    | Path to CA certificate for self-signed HTTPS |
+
+Both properties are optional. Without them, the sample app connects to
+production MaxMind servers.
+
+### ADB Reverse Port Forwarding
+
+When running the sample app on a physical device, `localhost` on the device
+refers to the device itself, not your development machine. ADB reverse creates a
+tunnel:
+
+```bash
+# Forward device's localhost:8443 to your machine's localhost:8443
+adb reverse tcp:8443 tcp:8443
+
+# Verify the forwarding is active
+adb reverse --list
+
+# Remove forwarding when done
+adb reverse --remove tcp:8443
+```
+
+**Note:** You must re-run `adb reverse` each time you reconnect the device.
+
+For emulators, you can alternatively use `10.0.2.2` which automatically routes
+to the host machine's localhost.
+
+### How Certificate Bundling Works
+
+When `debug.ca.cert` is configured and the file exists, the build system:
+
+1. Copies the certificate to `sample/src/main/res/raw/debug_ca.crt` (gitignored)
+2. Generates a `network_security_config.xml` that trusts the bundled certificate
+3. Sets `BuildConfig.DEBUG_SERVER_URL` for the app to use
+
+When not configured, the sample app behaves normally with the default network
+security config.
+
+### Troubleshooting
+
+**"Trust anchor for certification path not found"**
+
+- Ensure `debug.ca.cert` points to a valid CA certificate file (not a leaf cert)
+- Rebuild: `./gradlew :sample:clean :sample:installDebug`
+- Verify the certificate was copied: `ls sample/src/main/res/raw/`
+
+**Connection refused / timeout**
+
+- Verify ADB reverse is active: `adb reverse --list`
+- Ensure your local server is running on the correct port
+- Check that the server binds to `0.0.0.0` or `localhost`
+
+**Changes not taking effect**
+
+- Run a clean build: `./gradlew :sample:clean :sample:installDebug`
+- The network security config is generated at build time based on
+  `local.properties`
+
 ## Support
 
 If you encounter issues:

sample/build.gradle.kts

@@ -1,3 +1,5 @@
+import java.util.Properties
+
 plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
@@ -6,6 +8,15 @@ plugins {
     alias(libs.plugins.ktlint)
 }
 
+// Read local.properties for debug configuration
+val localPropertiesFile = rootProject.file("local.properties")
+val localProperties = Properties()
+if (localPropertiesFile.exists()) {
+    localProperties.load(localPropertiesFile.inputStream())
+}
+val debugServerUrl = localProperties.getProperty("debug.server.url", "")
+val debugCaCertPath = localProperties.getProperty("debug.ca.cert", "")
+
 android {
     namespace = "com.maxmind.device.sample"
     compileSdk =
@@ -27,6 +38,8 @@ android {
         versionName = "1.0"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        buildConfigField("String", "DEBUG_SERVER_URL", "\"$debugServerUrl\"")
     }
 
     buildTypes {
@@ -53,6 +66,7 @@ android {
 
     buildFeatures {
         viewBinding = true
+        buildConfig = true
     }
 }
 
@@ -85,3 +99,64 @@ detekt {
     config.setFrom(files("$rootDir/config/detekt/detekt.yml"))
     buildUponDefaultConfig = true
 }
+
+// Debug CA certificate support for local development
+// Usage: Add to local.properties:
+//   debug.ca.cert=/path/to/your/ca.crt
+//   debug.server.url=https://localhost:8443
+val hasDebugCert = debugCaCertPath.isNotEmpty() && file(debugCaCertPath).exists()
+
+if (hasDebugCert) {
+    // Copy certificate to res/raw
+    tasks.register<Copy>("copyDebugCaCert") {
+        from(debugCaCertPath)
+        into("src/main/res/raw")
+        rename { "debug_ca.crt" }
+    }
+
+    // Generate network security config that includes the bundled cert
+    tasks.register("generateNetworkSecurityConfig") {
+        dependsOn("copyDebugCaCert")
+        val outputFile = file("src/main/res/xml/network_security_config.xml")
+        outputs.file(outputFile)
+        doLast {
+            outputFile.parentFile.mkdirs()
+            outputFile.writeText(
+                """
+                |<?xml version="1.0" encoding="utf-8"?>
+                |<!-- Generated - do not edit. Configure via local.properties -->
+                |<network-security-config>
+                |    <debug-overrides>
+                |        <trust-anchors>
+                |            <certificates src="@raw/debug_ca" />
+                |            <certificates src="user" />
+                |            <certificates src="system" />
+                |        </trust-anchors>
+                |    </debug-overrides>
+                |    <domain-config>
+                |        <domain includeSubdomains="false">localhost</domain>
+                |        <trust-anchors>
+                |            <certificates src="@raw/debug_ca" />
+                |            <certificates src="user" />
+                |            <certificates src="system" />
+                |        </trust-anchors>
+                |    </domain-config>
+                |</network-security-config>
+                """.trimMargin(),
+            )
+        }
+    }
+
+    tasks.named("preBuild") {
+        dependsOn("generateNetworkSecurityConfig")
+    }
+
+    // Clean up generated files
+    tasks.named("clean") {
+        doLast {
+            delete("src/main/res/raw/debug_ca.crt")
+        }
+    }
+} else if (debugCaCertPath.isNotEmpty()) {
+    logger.warn("Debug CA certificate not found at: $debugCaCertPath")
+}

sample/src/main/AndroidManifest.xml

@@ -4,6 +4,7 @@
     <application
         android:allowBackup="false"
         android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:supportsRtl="true"
         android:theme="@style/Theme.DeviceTrackerSample">
         <activity

sample/src/main/java/com/maxmind/device/sample/MainActivity.kt

@@ -69,11 +69,17 @@ class MainActivity : AppCompatActivity() {
 
             // Create SDK configuration
             // Note: Replace with your actual MaxMind account ID
-            val config =
+            val configBuilder =
                 SdkConfig
                     .Builder(123456) // Demo account ID - replace with real one
                     .enableLogging(true)
-                    .build()
+
+            // Use debug server URL if configured in local.properties
+            if (BuildConfig.DEBUG_SERVER_URL.isNotEmpty()) {
+                configBuilder.serverUrl(BuildConfig.DEBUG_SERVER_URL)
+            }
+
+            val config = configBuilder.build()
 
             // Initialize SDK
             DeviceTracker.initialize(this, config)

sample/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated - do not edit. Configure via local.properties -->
+<network-security-config>
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="@raw/debug_ca" />
+            <certificates src="user" />
+            <certificates src="system" />
+        </trust-anchors>
+    </debug-overrides>
+    <domain-config>
+        <domain includeSubdomains="false">localhost</domain>
+        <trust-anchors>
+            <certificates src="@raw/debug_ca" />
+            <certificates src="user" />
+            <certificates src="system" />
+        </trust-anchors>
+    </domain-config>
+</network-security-config>