@robono/location-react-native
v0.4.2
Published
Optional Robono map screens, location cards and Expo tracking adapter.
Readme
Optional Robono mobile Maps
Recommended hosted setup
Use the hosted installer and the
supplied CustomerMessenger. Maps connects automatically when selected in
Features & preview. Your existing server verifies sign-in and sets sharing
eligibility; Robono runs the location service. Your users still choose when to
share. Native map registration and background permissions are described below.
For a separate route outside Messenger, connect the same verified login:
import {connectHostedRobono, hostedRobonoTokenProvider} from '@robono/messaging';
import {createExpoMaps, RobonoMaps} from '@robono/location-react-native/expo';
const connection = await connectHostedRobono({
userId: session.userId,
tokenProvider: hostedRobonoTokenProvider({
tokenEndpoint: 'https://your-company.com/api/robono-token',
getAccessToken: () => session.getAccessToken(),
}),
});
const maps = createExpoMaps(connection);
<RobonoMaps workspace={maps.workspace} contacts={contacts} />
try { await maps.signOut(); }
finally { await connection.signOut(); }Create these objects once after sign-in, outside React render. When sharing the connection with Messenger, stop both screens before signing out the connection.
Optional customer-hosted forwarding connection
Use createExpoMaps and RobonoMaps for a complete separate page:
import {createExpoMaps, RobonoMaps} from '@robono/location-react-native/expo';
const maps = createExpoMaps({
endpoint: 'https://your-company.com/api/robono',
userId: session.userId,
getAccessToken: () => session.getAccessToken(),
});
<RobonoMaps workspace={maps.workspace} contacts={contacts} />
// Before signing out of your own account service:
await maps.signOut();Create once per signed-in account, outside React render. The same complete screen
is connected automatically by createExpoMessenger; Features & preview
controls whether Maps appears separately, inside messaging, or both. Your backend
sets time-bounded viewing eligibility with messenger.location.setGrant. The
supplied UI handles the user's Share/Stop choice and the phone's permission prompt.
The installer adds native dependencies. Register the iPhone bundle ID and Android
package/signing fingerprint in Robono Maps, save both downloaded registrations as
.robono/maps-ios.json and .robono/maps-android.json, then run the installer with
--upgrade and rebuild both apps. No customer Google/LocationIQ account is needed.
Apple/Google notification credentials are a separate requirement for background
alerts, entered privately in the Robono notification setup.
The connected factory owns capture, expiry, token refresh, encrypted recovery and stop retries. Import the Expo entry point from the app's normal startup code so its background task is registered on a background launch. Do not define a second custom task when using this factory.
Background GPS needs permission and the supplied native configuration; Android shows an ongoing notification. Force-quitting or OS restrictions can stop updates. Independent movement sensing pauses when iPhone suspends the app, even with the screen unlocked; Android can use the supplied foreground service. Never label an old reading as a current movement or position.
Lower-level composition
The supplied map controls use Robono’s shared SVG icons. Install react-native-svg with your framework’s native dependency installer.
Use these components together or individually. Your app owns navigation, authentication, consent and permission policy. Maps can be a standalone screen, part of messaging, or both.
Exports:
LocationScreen: sharing controls, freshness, speed, heading, duration and stop control.LocationMessage: a location card for your chat UI.GeofenceEditor: controlled circle/polygon drawing, arrival/departure toggles and validated saving.AvatarLocationMap: avatar pins with tap-to-open name/update details, a Directions action and a destination route. Tapping the map closes the details without removing the avatar.RobonoMapView: Google map, markers, circles, polygons and routes.@robono/location-react-native/expo: foreground/background GPS adapters.@robono/location-react-native/motion: opt-in movement sharing with durable stop recovery.@robono/location-react-native/app.plugin.cjs: Expo native configuration.
Register your bundle ID and Android package/signing certificate with Robono. Activate access in Maps → Add Maps to your app, then download each platform’s app configuration. Robono provides map access restricted to those identifiers. Keep that managed build configuration in your private build environment. Do not ask end users for keys.
plugins: [['@robono/location-react-native/app.plugin.cjs', {
accessFiles: {ios: './robono-maps-ios.json', android: './robono-maps-android.json'},
background: true,
permissionText: 'Share your location with the people you choose.',
}]]Native map/location dependencies require a native build. Match Expo dependencies to the host's supported Expo version and commit its lockfile. These peers are optional at the product level: apps not using Maps do not install this package.
Start only after the user chooses to share
import {defineLocationTask, createExpoLocationSharing} from '@robono/location-react-native/expo';
// Module scope, including on a background launch:
defineLocationTask({taskName: 'app-location-sharing', store: trackingStore,
getClient: restoreAuthenticatedLocationClient, createId, onError: handleTrackingError});
const sharing = createExpoLocationSharing({client, createId,
taskName: 'app-location-sharing', store: trackingStore,
notificationTitle: 'Location sharing is active',
notificationBody: 'Open the app to stop sharing.',
});
await sharing.start({grantId, mode: 'live', durationMinutes: 60,
intervalSeconds: settings.updateIntervalSeconds, background: true});
await sharing.stop();trackingStore implements async load() and save(context|null) using the app's persistent storage. It stores only session ID, expiry and update interval. Authentication is restored separately using the app's secure session storage. Never persist a network API key there. Register the task once, outside React render functions.
Android requires an ongoing foreground-service notification for background sharing. iPhone requires background location permission and displays its location indicators. Ask for background access only for a user-selected feature. The OS may delay updates or stop tracking when the app is force-closed; show stale data as last known. On sign-out, call stop() before discarding authentication. If offline, stop local GPS immediately and retry the server stop once connected; the share also expires on the server.
Use observeLocation from the core client for viewers. Clear old positions when its view becomes null. dispose() releases foreground watchers; it deliberately does not stop a separately requested background share. Stop background sharing explicitly with stop().
Do not treat an ordinary contact relationship as permission to track someone. The backend must establish directed, time-bounded grants and synchronize revocation.
Chat map
<AvatarLocationMap position={view.position} name={view.name}
avatar={view.avatar} updated={locationAge(view.position.capturedAt)}
route={view.route?.coordinates} destination={view.destination}
onDirections={openExternalDirections}
onLocateMe={getForegroundPosition} />Import getForegroundPosition from @robono/location-react-native/expo for the optional Locate Me control. It requests foreground access only when pressed, uses the viewer position locally, and cancels pending GPS work when the map closes. It does not share that position with the other participant. The friend control zooms to the shared pin; Locate Me fits both positions within the visible map. The map includes Regular and Satellite views. Dragging keeps the details open; tapping elsewhere dismisses them.
The containing screen controls navigation and clears the map when access expires or is withdrawn. onDirections should open Apple Maps directly on iPhone or Google Maps directly on Android. Render tripSummary(view, units) beside a live trip for speed and estimated arrival; do not present stale estimates as current.
For an atomic chat start, pass startWithPosition to createExpoLocationSharing. It receives the user's first accurate fix and a request ID before background GPS starts. Forward those to LocationChatClient.start; the adapter skips the redundant first update. Persist a start-recovery record before sending the request, so your app can recover a lost response or interrupted start. Store only session/recovery metadata, never a history of coordinates.
Permission recovery: the Expo adapter throws LocationPermissionError with permission (foreground or background) and canAskAgain. Offer a settings link if access is denied; do not silently downgrade a background share. A host can offer an explicit open-app-only trip using background: false, keep the sharing controller alive after its sheet closes, and call stop() when the app enters the background. Robono Messenger supplies this recovery flow.
Improve accuracy
Call getPrecisePosition({signal, onPosition}) from the Expo entry point only after
the user selects Improve accuracy. It reports usable fixes while refining for
up to 12 seconds and returns the best recent reported radius. Pass the resulting
position to your map and display locationAccuracyLabel(position) from the core
package. Additional decimal places do not mean additional accuracy. This does
not promise an exact position or upload Wi-Fi/Bluetooth scans.
Share device movement
Install the expo-sensors version compatible with your Expo SDK and enable
motion: true in the Robono location plugin. Use an account-specific persistent
store implementing load() and save(value|null) for pending stop recovery.
import {createExpoMovementSharing} from '@robono/location-react-native/motion';
const movement = createExpoMovementSharing({
client, store: movementStore, createId, onError: showMovementError,
});
await movement.recover(); // On signed-in startup: finish a pending stop.
// Only after the user chooses Share movement. No location session or GPS needed:
await movement.start({grantId, durationMinutes: 15});
await movement.stop();Keep one controller per signed-in account. Call stop() when sharing ends or
before signing out. It stops sensors immediately, even without a network, and
retains a failed server-stop request for the next authenticated startup. A restart
never automatically resumes movement capture. Do not reuse another account's store.
Use client.listMovement() and client.viewMovement(sessionId) for independent
shares. The server checks the same authenticated participants and selected movement
access on both networks, limits sessions to 15 minutes, and rejects coordinates,
map history and geofences on movement-only sessions. Location sharing can run or
stop separately. Independent views hide readings older than 15 seconds. Recheck
the view every five seconds while visible, and show unavailable on a failed read.
movement.start(existingLocationSessionId) remains supported
when attaching movement to an existing location share is intentional.
Pass view.motion to LocationScreen for the viewer. Readings distinguish still,
slight movement and moving; stale readings display unavailable. Raw sensor samples
stay on the phone. iPhone capture pauses in the background; the Android service
described below supports background capture. These indicators cannot establish whether someone is touching
the screen, reading, or using another app.
GeofenceEditor offers entry/exit alerts, arm-on-entry, and optional schedules
with days, local time zone, and expected arrival/departure times. A missing or
inaccurate position produces location unavailable, not a claim that the person
is outside. Schedule times apply to the chosen time zone, including daylight saving.
Independent background movement (unreleased)
observeDeviceMovement and createExpoMovementSharing use a native Android
service by default. Install the updated package and rebuild the native app;
a JavaScript-only update cannot add this service. Start from the person's existing
Share movement action while the app is open. Android asks for notification access
and shows an ongoing notification with Stop. No location permission, coordinates,
microphone or audio workaround is used. Samples stay on-device; only the same
classified reading is passed to the publisher.
The service stops after durationMs (default and maximum 900,000 ms), on Stop,
app-task removal or native-runtime destruction. It is not restarted after process
death. The existing durable stop record revokes interrupted sharing when the app
returns. Its short-lived CPU wake lock allows non-wake-up sensors to work with the
screen off; the display remains off. Register the specialUse foreground-service
use case when submitting an Android app. Native code and notification permissions
are included through React Native autolinking.
On iPhone, independent continuous background movement is not supported by the
standard iOS execution model. The observer remains foreground-only and reports
unknown when the app backgrounds; background: true rejects explicitly.
movementBackgroundSupport() exposes this distinction. Historical accelerometer
records and activity classifications are not substitutes for current slight-device-
movement readings. The ready-made iPhone screen explains the foreground limit.
Android source compilation and fixture tests do not establish locked-screen physical-device behavior. That acceptance check is still required before release.
Language and native Maps readiness
Pass interfaceLocale={{locale:'es'}} to RobonoMaps or LocationScreen, or wrap
individual components in RobonoLocationLocaleProvider. 23 interface languages are
supplied; messages, plurals and direction allow customer wording/languages.
Names and addresses stay unchanged. The supplied Messenger forwards its language
automatically. See the interface language guide.
Rebuild both phone apps after upgrading this package. The iPhone pod and
Android module check the compiled Maps configuration before mounting a Google
map, so missing setup shows an unavailable notice rather than crashing the app.
nativeMapsReady() returns this check without revealing the map key. Use the
Maps setup plugin and both downloaded app registrations. For a manually managed
iOS project, install the pod and initialize GMSServices.provideAPIKey before
React starts. A JavaScript-only update cannot install or configure native Maps.
Routes with several stops
Use client.planRoute(stops, {optimize: true}) for 2–25 stops with a fixed start and finish. The web and phone UI packages supply RobonoRoutePlanner using the same authenticated Maps client and existing directions spending controls. Supply your business stop names and coordinates; no additional provider key is needed. Setup, UI options, usage and limitations.
