# Geolocation Module

<WebSDK2 />

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](doc: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;
};
```

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

## State machine

`GeolocationState` is a discriminated union over `status`:

| Status               | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| `idle`               | Initial state.                                                        |
| `requestingLocation` | Browser permission prompt visible / location lookup in progress.      |
| `locationAcquired`   | Got coordinates; transitioning to submit.                             |
| `permissionDenied`   | User denied permission. Show retry instructions or Skip (if enabled). |
| `submitting`         | Sending coordinates to the backend.                                   |
| `finished`           | Terminal.                                                             |

## See also

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