Appearance

Location beta ​

The user's device location, exposed to scripting as environment.location. Coarse reads ride the base grant; precise accuracy is an explicit opt-in.

Properties ​

accuracyAuthorization beta ​

  • Type: string
  • Current accuracy authorization: "full" | "reduced" | "unknown".

authorizationStatus beta ​

  • Type: string
  • Current authorization: "notDetermined" | "denied" | "restricted" | "granted".

Methods ​

current() beta ​

javascript
current(options?: Object): Promise<GeoCoordinate>

Read the current location once.

Example:

javascript
await environment.location.requestAccess();
const here = await environment.location.current();
console.log(here.latitude, here.longitude, '±' + here.horizontalAccuracy + 'm');

Parameters:

  • options (Object) (optional) - { timeout?: number (seconds), maximumAge?: number }

Returns: Promise<GeoCoordinate>

on() beta ​

javascript
on(event: string, callback: function): any

Subscribe to a location event. Supported: 'authorizationchange' → callback(status).

Parameters:

  • event (string)
  • callback (function)

Returns: any

requestAccess() beta ​

javascript
requestAccess(): Promise<string>

Request base location access. Prompts once if undetermined; resolves the resulting authorization status. Reads never prompt on their own.

Returns: Promise<string>

requestPreciseAccess() beta ​

javascript
requestPreciseAccess(options?: Object): Promise<boolean>

Request precise (full) accuracy. Shows a confirmation carrying options.reason (once per run), then the OS accuracy prompt. Resolves whether precise is now active.

Example:

javascript
const precise = await environment.location.requestPreciseAccess({ reason: 'to guide you to nearby places' });
if (precise) { const here = await environment.location.current(); }

Parameters:

  • options (Object) (optional) - { reason?: string }

Returns: Promise<boolean>

watch() beta ​

javascript
watch(onPosition: any, options?: Object): any

Observe location continuously. onPosition receives a GeoCoordinate.

Example:

javascript
// Geofence: report distance to a target, act once within 50 m, then stop watching.
const target = new GeoCoordinate(48.1372, 11.5756);
const sub = environment.location.watch(here => {
    const metres = here.distanceTo(target);
    console.log('distance to target', Math.round(metres), 'm');
    if (metres < 50) { sub.stop(); scene.setVariable('arrived', true); }
});

Parameters:

  • onPosition (any)
  • options (Object) (optional) - { onError?: function(string) }

Returns: any