Skip to main content

location

Namespace for reading the device's location once or subscribing to live updates as the user moves. Covers location-aware UX like nearby-store search, delivery-address autofill, and walking/running distance tracking.

Unofficial docs

This page is community-written. The SDK behavior itself is defined by the upstream @apps-in-toss/web-framework release.

Methods​

MethodPurpose
getCurrentLocationRead the current location once.
startUpdateLocationSubscribe to location changes via callback; returns an unsubscribe function.

Permission​

The whole namespace shares a single geolocation permission. Both methods are bound to the same PermissionName, so granting access through one immediately enables the other.

  • Calling either method while the status is denied throws — check the status first.
  • When the status is notDetermined, prompt the user via the system dialog before calling.
  • Accuracy (accuracy) and the granted access tier (accessLocation: FINE / COARSE) are independent. iOS and Android both let users grant only "approximate" access — in that case accessLocation comes back as COARSE and the coordinate error radius is much wider.

Both methods expose getPermission() / openPermissionDialog() helpers on the function object — see each page's "Permission" section.

Coordinate payload​

Both methods resolve to the same Location shape.

interface Location {
  coords: {
    latitude: number;
    longitude: number;
    altitude: number;          // meters; normalized to 0 when the platform reports it as unavailable — 0 is therefore not a usable "no fix" sentinel (sea level is also 0).
    accuracy: number;          // horizontal error radius in meters; smaller is better
    altitudeAccuracy: number;  // vertical error in meters
    heading: number;           // direction of travel (0–360°); returns 0 when stationary OR when heading is unavailable, so it can't be distinguished from "due north".
  };
  timestamp: number;           // measurement time (ms epoch)
  accessLocation?: 'FINE' | 'COARSE';
}

UX guidance​

  • Show the reason before asking for permission. A one-liner like "We need your location to find nearby stores" measurably increases acceptance rates.
  • Use getCurrentLocation for one-shot reads, startUpdateLocation for tracking. Subscribing when one fix would suffice wastes battery/data and risks OS-level throttling in the background.
  • Always call the returned unsubscribe function. In React, do this from a useEffect cleanup.
  • Always inspect the accuracy value. Indoors, in tunnels, or without GPS, it can drift to hundreds of meters.
  • Don't show raw coordinates to users — run reverse geocoding and present an address or neighborhood name.

Try it live​

Both methods are available on the Location page in sdk-example.

Open in sdk-example

External references​