---
title: "Geolocation Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-geolocation/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# Geolocation Module

:::note
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](/sdk-reference/web-sdk-reference).  Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade. <br /><br />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](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules) 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.

```ts
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

```typescript
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`.

## See also

- [Module Patterns → backend-process](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)
- [Troubleshooting → CSP](/sdk-reference/web-sdk-2-troubleshooting/#content-security-policy): geolocation needs no special CSP, but may need feature-policy delegation in iframes