> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the TypeScript Bridge SDK options, timeouts, and React provider

The bridge requires minimal configuration. In most cases, auto-detection handles everything.

## Bridge options

Options are passed to `NativeBridge.getInstance()` (or to `<BridgeProvider options={...}>` in React).

```typescript theme={null}
interface NativeBridgeOptions {
  environment?: Environment;
  channel?: MessageChannel;
  iframeAllowedOrigins?: string[];
  iframeTargetOrigin?: string;
}
```

All fields are optional.

### `environment`

Override automatic environment detection. Useful for testing or debugging.

```typescript theme={null}
const bridge = NativeBridge.getInstance({ environment: 'ios' });
```

In production, omit this — the bridge auto-detects the environment.

### `channel`

Inject a custom `MessageChannel` implementation for testing.

```typescript theme={null}
const mockChannel: MessageChannel = {
  send(message) { /* capture or relay messages */ },
  onMessage(callback) { /* store callback to simulate responses */ },
  destroy() { /* cleanup */ },
};

const bridge = NativeBridge.getInstance({
  environment: 'ios',
  channel: mockChannel,
});
```

### `iframeAllowedOrigins`

An allowlist of origins for incoming `postMessage` events. Only applies to iframe transport.

```typescript theme={null}
const bridge = NativeBridge.getInstance({
  iframeAllowedOrigins: ['https://app.example.com', 'https://staging.example.com'],
});
```

If empty (default), all origins are accepted. **In production, always specify allowed origins** for iframe embeddings.

### `iframeTargetOrigin`

The target origin for outgoing `postMessage` calls. Only applies to iframe transport.

```typescript theme={null}
const bridge = NativeBridge.getInstance({
  iframeTargetOrigin: 'https://app.example.com',
});
```

Defaults to `window.location.origin`. Set this explicitly when the parent frame is on a different origin.

## Timeouts

| Operation                            | Default timeout |            Configurable?           |
| ------------------------------------ | --------------- | :--------------------------------: |
| `discoverCapabilities()`             | 5,000 ms        |           Yes (parameter)          |
| `request()`                          | 30,000 ms       | Yes (via `RequestOptions.timeout`) |
| `useNativeCamera().requestCapture()` | 120,000 ms      |           No (hardcoded)           |

```typescript theme={null}
// Custom discovery timeout
await bridge.discoverCapabilities(10_000); // 10 seconds

// Custom request timeout
await bridge.request('camera.document.capture', data, {
  timeout: 60_000, // 60 seconds
});
```

## React configuration

Pass options to `<BridgeProvider>`:

```tsx theme={null}
<BridgeProvider
  options={{
    iframeAllowedOrigins: ['https://app.example.com'],
    iframeTargetOrigin: 'https://app.example.com',
  }}
  discoverOnMount={true}
>
  <App />
</BridgeProvider>
```

The `discoverOnMount` prop controls whether `discoverCapabilities()` runs automatically:

| Value            | Behaviour                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `true` (default) | Discovery runs on mount. `capabilitiesReady` becomes `true` when complete.               |
| `false`          | Discovery is skipped. `capabilitiesReady` is `true` immediately with empty capabilities. |

## No API keys or tokens required

The bridge itself does not require API keys, base URLs, or authentication tokens. It is a transport layer between the web app and its host. Any authentication or configuration for GBG GO services is handled separately by the application layer.