Android Implementation

Platform Goals#

The Android implementation is designed to:

• Maintain a fully permissionless footprint across all supported Android versions.
• Use only foreground‑safe APIs without background services.
• Provide consistent behavior across manufacturers and device classes.
• Integrate cleanly with the Awareness model and UI layer.
• Avoid sensors, radio access, VPN profiles, or system configuration changes.

These constraints ensure a reviewer‑friendly app suitable for Play Store distribution.

Signal Layer#

The signal layer gathers local observations using stable, permissionless Android APIs.

Network Signals#

Android exposes several reliable indicators of network clarity without requiring permissions:

• DNS resolution timing using standard InetAddress lookups or OkHttp/HttpURLConnection timing.
• TLS handshake duration via EventListener in OkHttp or NetworkSecurityConfig callbacks.
• Protocol negotiation observed through ConnectionSpec and HTTP/3 fallback behavior.
• QUIC handshake success when using libraries that expose protocol metrics.
• Retry patterns inferred from client‑side interceptors.
• Captive portal detection via redirect behavior during normal requests.

These signals behave consistently across Android versions and map directly to the Awareness model.

Device Stability Signals#

Android provides several runtime indicators without requiring permissions:

• UI thread jank measured via Choreographer frame callbacks.
• Memory pressure via onTrimMemory() and onLowMemory().
• Thermal throttling via ThermalStatusListener (no permission required).
• Foreground/background transitions via LifecycleOwner and ProcessLifecycleOwner.
• Event loop jitter measured using monotonic timestamps.

These signals reflect local drift without accessing sensitive system data.

Server Layer#

The Android app retrieves the server‑declared Awareness document using standard networking:

• Fetches /.well-known/rtt-awareness using OkHttp or HttpURLConnection.
• Parses JSON using Moshi, Gson, or the platform JSON parser.
• Stores the result in a lightweight cache (SharedPreferences or in‑memory).
• Uses cached values when offline or degraded.

No background services, WorkManager jobs, or privileged networking APIs are used.

Merge Layer#

The merge logic on Android follows the same rules defined in the Awareness model:

• Local signals → Stable or Unstable.
• Server signals → Stable or Unstable.
• Merge → Clear, Local Drift, Global Drift, or Drift.

The merge runs:

• On app launch.
• When returning to the foreground.
• When local signals change classification.
• When server state refreshes.

The merge layer is shared across iOS and Android for consistency.

UI Layer#

The Android UI expresses Awareness using a minimal, ambient indicator:

• Implemented using Jetpack Compose or traditional Views.
• Uses color, opacity, and subtle motion to reflect state.
• Updates only when the Awareness state changes.
• Avoids intrusive animations or notifications.
• Integrates with the portal link to RTT documentation.

The UI remains consistent with the design principles defined in the UI documentation.

App Lifecycle Integration#

Android’s lifecycle provides natural hooks for Awareness updates:

• onStart() or onResume() — refresh server state and local signals.
• onStop() — pause signal sampling.
• onTrimMemory() — update local drift classification.
• Choreographer callbacks — update UI thread stability metrics.

These hooks ensure stable behavior without background execution.

Performance and Battery Considerations#

The implementation minimizes overhead:

• Network requests are infrequent and cached.
• Signal sampling uses lightweight callbacks or OS‑provided events.
• No continuous polling or background services.
• Motion effects in the UI are subtle and low‑cost.

This keeps the app efficient across a wide range of Android devices.

Future Extensions#

The Android implementation leaves room for RTT‑Inside features in later versions:

• Optional deeper sensing for users who opt in.
• Additional signal types using permitted APIs.
• Expanded UI states or metadata.

These extensions will not alter the core v1 permissionless model.