DocumentationAPI Reference
SDK reference, Incode Web SDK 2 Reference / Web SDK 2 Individual Modules

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.

This module 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 Location submitted successfully; awaiting user confirmation. 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. No manager action leaves this state; restore connectivity and reload the page. –
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() Return to idle; then call request() again from a user gesture. error, with attempts remaining
skip() Skip geolocation. Requires allowUserToSkipGeolocation. permissionDenied, error (canSkip)
quit() Give up and leave the module. error

Plus the universal lifecycle: subscribe, getState, stop.

The built-in noNetwork screen offers a page reload. A headless host should provide the same recovery after connectivity returns; retry() does nothing in noNetwork.

See also

Was this page helpful?