Geolocation Module

Note

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

The Geolocation module captures the user's coordinates via the browser's geolocation API and submits them to the backend. Useful for jurisdictional rules and fraud signals.

Follows a backend-process pattern variant with a permission step. Requires a user gesture before the browser will prompt for permission.

Tag

<incode-geolocation> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/geolocation';
import '@incodetech/web/geolocation/styles.css';

Properties

Property	Type	Required	Description
`config`	`GeolocationConfig`	❌	Configuration options
`onFinish`	`() => void`	❌	Called when location is captured (or skipped)
`onError`	`(error: string) => void`	❌	Called when an error occurs

Configuration

type GeolocationConfig = {
  allowUserToSkipGeolocation?: boolean;
  maxAttempts?: number;
};

Option	Type	Required	Description
`allowUserToSkipGeolocation`	`boolean`	❌	When `true`, a Skip button is shown on the permission-denied screen. Default `false`. Backend-driven via flow config.
`maxAttempts`	`number`	❌	How many backend submit attempts the `error` screen offers before it stops showing "Try again" and falls back to skip or quit. Default `3`.

State machine

GeolocationState is a discriminated union over status:

Status	Description	Extra properties
`idle`	Initial state.	–
`requestingLocation`	Browser permission prompt visible / location lookup in progress.	–
`locationAcquired`	Got coordinates; transitioning to submit.	`location`
`permissionDenied`	The user actually denied permission. Show device-specific instructions, plus Skip when enabled.	`deviceType`, `canSkip`
`submitting`	Sending coordinates to the backend.	–
`error`	A submit attempt failed and the user can try again. Offer "Try again" while `attemptsRemaining` is above zero, then Skip or Quit.	`attemptsRemaining`, `canSkip`
`noNetwork`	A backend request failed because the device lost connectivity. The module parks here until the user retries with a connection back.	–
`finished`	Terminal.	–
`closed`	User dismissed the module.	–

permissionDenied** means a real denial only.** Transient browser failures — position unavailable, lookup timeout — route to error instead, so branch on error if you want to offer a retry for those.

API methods

Method	Purpose	Callable when
`request()`	Start the browser permission request. Needs a user gesture.	`idle`
`continue()`	Confirm the acquired location and complete the module.	`locationAcquired`
`retry()`	Retry the failed submit.	`error`, `noNetwork`
`skip()`	Skip geolocation. Requires `allowUserToSkipGeolocation`.	`permissionDenied`, `error` (`canSkip`)
`quit()`	Give up and leave the module.	`error`

Plus the universal lifecycle: subscribe, getState, stop.

Geolocation Module

Tag

Properties

Configuration

State machine

API methods

See also