android

elonn-world-android is the Android phone runtime for Elonn. Package: com.elonn.worldar. Production services are on the elonn.com domain.

Download APK →

The Android runtime authenticates through World, fetches surface runtime, world bridge data, and nearby places from the same .com services used by the browser runtime, and renders the two-layer model using an ARCore geospatial field plus standard Compose/UI overlays for carry.

Android follows the same Find boundary as Web: it talks to World, World orchestrates Find and Surface, and Android renders normalized surface runtime objects. Android does not call Brave, OSM, Nominatim, Overpass, or Find service endpoints directly.

The Runtime Contract is the normative runtime contract. This page describes the current Android implementation and platform constraints.

Local setup

• ARCORE_API_KEY must be present in android.elonn.app/local.properties.
• The app declares com.google.ar.core as optional and uses the ARCore API key manifest metadata.
• Camera and location permissions are required for the field layer.

Presence identifier

The runtime parameter used in panel URLs is android. A dedicated presence identifier string (equivalent to web.elonn for the browser runtime) is not yet confirmed in the codebase.

What it renders

Field layer — Rendered through ARCore Geospatial tracking. Nearby places are sourced from world and projected through the AR camera pose. The field is not the same 2D panorama used in the web runtime.

Carry layer — Rendered as standard Android Views, not AR-anchored:

• Top dock bar — surface and app buttons
• Left sidebar — World Contract context rail
• Central stack — focused durable carry surfaces only
• Right sidebar — service controls, including the native Find query workspace
• Bottom dock bar — app buttons
• Finding overlay — detached finding_surface cards positioned from Surface placement data

Runtime data path

The Android runtime composes its runtime session through World:

• GET https://world.elonn.com/world/identity/me — authenticated member identity
• GET https://world.elonn.com/world/session — world contract, including surface_runtime surfaces/stacks and bridge data such as social object counts
• GET https://world.elonn.com/world/session also supplies field_runtime.objects[], the field dataset consumed by the field
• POST https://world.elonn.com/world/find/query — submits Find queries and receives an updated surface_runtime
• POST https://world.elonn.com/world/surface/surfaces/{surface_id}/placement — persists movement for movable surfaces

Android does not call Maps directly for the field layer.

Android also does not call Find providers directly. Brave and OSM provider configuration remains inside Find.

Find runtime behavior

Find is a right-rail/native control surface in Android, not a fake center-stack service panel.

When a user submits a query:

1. Android posts the query to World /world/find/query.
2. Find executes provider search and produces normalized findings.
3. Surface turns those findings into finding_surface runtime objects.
4. World returns the updated surface_runtime.
5. Android renders detached findings as individual movable cards in the carry overlay.

Detached finding cards use placement.x, placement.y, placement.width, placement.height, and placement.z. Dragging a card updates local state first and then persists placement through World. Finding cards are filtered out of dock items and are not treated as center stack focus members.

The Android runtime intentionally does not synthesize Social, Time, Messages, or Find as fake center runtime surfaces. Those service buttons use native panel loading or service controls. The center stack is reserved for real durable carry surfaces from the Surface runtime contract.

Panel loading

Panels load from service/world URLs inside runtime WebViews. The runtime centers on the current focused surface and uses the same service-backed content model as web, but the field itself is native.

Panel endpoints (served by world.elonn.com):

• /world/panels/social
• /world/panels/messages
• /world/panels/time

Find query is handled by POST /world/find/query; Android should not depend on /world/panels/find for the current Find proof.

Session startup

1. Check stored auth token in SharedPreferences
2. If valid, call GET /world/identity/me on world.elonn.com to confirm
3. If expired or absent, present the login WebView at https://elonn.com/account/login
4. On success, extract the elonn_api_token cookie from the login session and store it as the bearer token
5. Fetch world contract from world.elonn.com/world/session
6. Apply contract to AR scene and carry surface stack
7. Request camera permission and create ARCore Geospatial session

Find boundary rules

• Android consumes normalized findings through surface_runtime.
• Android must not inspect provider-specific payloads.
• Android must not receive or forward BRAVE_API_KEY.
• Android placement writes go through World; Surface remains the placement authority.
• Android may optimistically move cards locally, but persisted placement comes back through the World/Surface contract.
• Save, share, pin, place, provider selection UI, and first-party content search are not implemented in Android yet.

Notable constraints

• No push notifications (not implemented)
• No background sync (not implemented)
• All production hosts are hardcoded constants — no build-type switching
• Camera permission and fine location permission are required for the full field demo
• Finding cards can move, but resize and open actions are not fully implemented yet
• Bluetooth mouse not yet supported (planned: click = select, right-click = back, scroll = flip surfaces)

Canonical terms

• runtime — the execution environment
• carry — user-following layer rendered as Android Views
• field — spatial layer rendered as a camera-backed orientation overlay
• panel — service-owned content loaded inside a surface, loaded in a WebView
• surface — contextual presentation layer within a stack