@robono/location
v0.4.1
Published
Location sharing, tracking and geofence contracts for Robono managed Maps.
Readme
Robono location client
@robono/location provides location-sharing contracts, validation, geofence geometry, a client, a serial GPS publisher and a polling viewer. Use it with optional Robono screens or your own interface. Maps does not require messaging or Bridge membership.
Choose Maps for the app/environment in Features & preview. The public integration guide is /docs#maps; the full server contract is /api/location-openapi.json.
Start here
For supplied Maps screens, use the hosted setup guide. Choose Maps and its placement in Features & preview, register the website origin or phone app identifiers, and run the Robono installer. The supplied Messenger connects Maps automatically using the same verified account. Your server supplies viewer permissions; each person chooses when to share.
This core package documents lower-level location controls for custom interfaces. The forwarding example below is an advanced alternative, not a required server for the hosted Messenger.
Advanced: custom client authentication
Phones and browsers call your authenticated backend, using your user access token. Your backend injects the actor ID and forwards approved operations through RobonoLocationBackend. Keep Robono API keys and permission-management operations on the server.
import {LocationClient, createLocationTransport, observeLocation} from '@robono/location';
const client = new LocationClient(createLocationTransport({
url: `${yourBackend}/location`,
getAccessToken: getSignedInUserToken,
sdk: {platform: 'web', component: 'web'},
}));
const watcher = observeLocation(client, {
sessionId,
onChange: view => renderLocation(view), // null means clear the old location
onError: showLocationError,
});
// Leave the screen:
watcher.stop();Sharing
Your server grants permission to a named viewer before a user starts a share. Cross-app permission also requires the accepted Bridge connection and the receiving app's explicit approval. Permission changes carry monotonically increasing revisions. A stop or revocation permanently ends that share.
const share = await client.start(grantId, 'live', createRequestId(), 60);
await client.update(share.sessionId, {
latitude, longitude, accuracyMeters,
capturedAt: new Date(gpsTimestamp).toISOString(),
speedMps: speed >= 0 ? speed : null,
}, createRequestId());
await client.stop(share.sessionId);Use pin for one fixed position, live for a timed share, and ongoing for permitted tracking until stopped or the permission expires. Reuse a request ID only to retry the same operation. createPositionPublisher coalesces GPS updates, respects rate limits and stops on terminal permission errors. The SDK never starts GPS on import.
Movement
Independent movement sharing uses client.startMovement(grantId, requestId, minutes)
and never starts GPS or accepts coordinates. Use the native
createExpoMovementSharing controller to handle consent, sensors and stop recovery;
call start({grantId, durationMinutes: 15}) only from the person's sharing action.
Authorized viewers use client.listMovement() and client.viewMovement(sessionId).
Sessions expire within 15 minutes and readings older than 15 seconds are hidden.
Android background capture requires the updated native service. iPhone capture
pauses when the app leaves the foreground, even with the screen unlocked.
Area alerts
client.fence(sessionId, {id, name, shape, onEnter, onExit, enabled, revision}) creates or updates an area owned by the authenticated user. A circle has a center and radius in metres (50–100,000). A polygon has 3–50 non-crossing vertices. Increment revision when editing. Set enabled to false to remove its alerts.
Crossings require multiple accurate updates and the configured confirmation period. Unknown accuracy and long update gaps reset confirmation; offline does not mean outside. Events are available through client.events and the signed location.geofence_crossed webhook. Your application delivers the resulting notifications. Deduplicate using the event ID and respect current permission when notifying.
Directions, history and usage
directionsLink opens Apple Maps or Google Maps. client.directions requests a managed walking/driving route. client.address resolves a coordinate to an address. Display the returned attribution. Honour 429 Retry-After; do not poll address or route endpoints with every GPS update.
History requires both apps to enable it and uses their shorter retention period. client.history is paginated newest-first by before. Location positions are not copied into billing counters. client.mapOpened() reports a rendered map for analytics; report once per map opening, not each position refresh. SDK identification is diagnostic metadata, not proof of a billable provider load.
Privacy lifecycle
Clear visible locations on permission errors, expiry, sign-out and user changes. Stop GPS when sharing stops. On deletion, your backend calls eraseLocationUser and removes its own cached locations/notifications. Do not log precise positions or access tokens. Use a consent flow appropriate to your app; friendship alone is not location permission.
Locations inside an existing Bridge chat
Use LocationChatClient for an accepted one-to-one Bridge conversation. Your authenticated server forwards its operations through RobonoLocationChatBackend and supplies the signed-in user's actor ID; never trust an actor supplied by the phone. Only your server may call setPermission.
Synchronize canSend and canReceive separately for each external user/conversation, with an increasing revision. These permissions are independent of messaging and calling. Both networks must enable the requested location feature. Render a share button only when availability(conversationId) returns canSend and at least one of pinAvailable or journeyAvailable.
start({conversationId, mode: 'pin', position, requestId})sends a fixed position. It does not start continuous GPS updates.- When
trackingAvailableis true, offer Share Tracking. Callstart({conversationId, mode: 'journey', targetKind: 'friend', estimateMode: 'progress', position, requestId}). This creates a request, not permission to view either location.view()returnstrackingState: 'pending'andposition: nulluntil acceptance. Unanswered requests expire after ten minutes. - The recipient taps Accept, obtains a fresh accurate position (within 30 seconds, accuracy at most 50 metres), and calls
accept(sessionId, position). Explain that this becomes a fixed meeting point, even if the recipient later moves. Only the recipient can accept or calldecline(sessionId). Repeating acceptance never changes the agreed point. Either participant can stop accepted friend tracking. Both directional location permissions must remain enabled. - Offer Choose another destination as a secondary action.
search(conversationId, query)resolves its address. Start withmode: 'journey', destination, estimateMode: 'progress'. It starts immediately without recipient acceptance or a travel-mode choice. - Progress tracking draws no suggested route.
distanceMetersis straight-line distance;etaSecondsis a rough estimate from recent progress. An estimate is absent when stopped, moving away, or GPS is insufficient.tripSummaryformats distance, speed and approximate arrival. - Progress tracking ends after accurate fixes show the traveller within 50 metres of the meeting point, at no more than 3 m/s, for at least 30 seconds with no update gap above 20 seconds.
update()returnsstopped: true, reason: 'arrived'; stop native GPS immediately. Later requests returnsharing_ended. The Expo adapter handles this stop in foreground and background. Coordinates and derived estimates are erased; the chat entry retainstrackingState: 'arrived'. start({conversationId, mode: 'journey', position, destination, travelMode, requestId})remains available for integrations that explicitly want a routed trip.destinationcontains latitude, longitude and label; travel mode iswalkingordriving.update(sessionId, position, requestId)updates the trip's position and speed. Send accurate fixes no more often than every five seconds. The service refreshes its route estimate at most once a minute.list(conversationId)supplies chat entries without coordinates.view(sessionId)checks current permission before returning location, avatar, route and estimated travel time.stop(sessionId)permanently ends the sender's share and erases its coordinates. The sender can stop any share; either participant can stop friend tracking.
Fixed pins expire after 30 days; trips expire after eight hours or the shorter limit set by either app. Permission withdrawal, blocking or disconnection ends affected shares immediately. Display an ended entry without its old location. locationAge and tripSummary distinguish current data from stale positions and estimates.
The signed location.chat_shared webhook contains session_id, conversation_id, recipient_external_user_id and mode. Fetch the location through the authenticated service when opened. Do not copy precise locations into push notifications. Reuse the exact request ID and payload after a lost response; changing a retried payload returns a conflict.
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.
Location quality
Maps supplies advisory simulation, timing and accuracy warnings through view.integrity. The supplied UI shows them automatically; custom screens can use locationIntegrityWarning. Signals, display options and platform limits. A missing warning never verifies that a location is genuine.
