📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). 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](https://developer.incode.com/docs/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

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