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

# Flutter SDK

> SDK Version 0.0.4 (Preview)

## Import

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
import 'package:ones1ght_sdk/ones1ght_sdk.dart';
```

## Initialization

### .initialize

Initializes the positioning engine with your OneS1ght API key.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.initialize(sdkKey: 'YOUR_SDK_KEY');
```

### .requestPermission

Requests the app permissions needed to use the positioning engine.

| Result | Meaning |
| - | - |
| `authorized` | Positioning available |
| `denied` | Permission denied |
| `unsupported` | Device without positioning support |

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final status = await OneS1ght.requestPermission();
```

### .setLanguage

Sets the language of SDK log messages.<br />
`ko`: Korean,  `ja`: Japanese,  `en`: English, `null`: system language

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.setLanguage('en');
```

### .onDebugLog

Receives SDK logs.<br />
`level`: log level, `message`: log message

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
OneS1ght.onDebugLog.listen((log) => debugPrint('[OneS1ght] ${log.level} ${log.message}'));
```

### .reset

Undoes initialization and discards the current session. No new session is created; call `initialize` again to continue (a different key also works).

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.reset();
```

## State

### .isInitialized

Returns whether initialization succeeded.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final ready = await OneS1ght.isInitialized();
```

### .deviceAvailability

Tells whether the device supports positioning and, if not, why.

| Value | Meaning |
| - | - |
| `available` | Positioning available |
| `osVersionTooLow` | Below iOS 27 · Android 17 (API 37) |
| `deviceNotSupported` | Device without UWB |

On Android, read it after `initialize()`. Before that the SDK cannot tell and returns `deviceNotSupported`.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
switch (await OneS1ght.deviceAvailability()) {
  case DeviceAvailability.available:
    break;
  case DeviceAvailability.osVersionTooLow:
    break;
  case DeviceAvailability.deviceNotSupported:
    break;
}
```

### .googleMapKey

Returns the Google Maps API key for displaying the floor plan.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final mapKey = await OneS1ght.googleMapKey();   // String?
```

### .sdkVersion

Returns the native SDK version in use. <br />
For the plugin version, see `OneS1ght.pluginVersion`.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final version = await OneS1ght.sdkVersion();
```

## Profiles

### .createProfile

Creates a new personalization profile. Returns a unique profile ID on success.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final profileId = await OneS1ght.createProfile({'gender': 'F', 'ageBand': '20s'});
```

### .identify

Links the profile that collected positioning data is grouped under. Set `null` to unlink.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.identify(profileId: profileId);
```

### .fetchProfile

Fetches the profile's attributes.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final attributes = await OneS1ght.fetchProfile(profileId);
```

### .replaceProfile

Replaces the profile's attributes. The previous data is deleted.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.replaceProfile(profileId, attributes: {'gender': 'F', 'ageBand': '30s'});
```

### .deleteProfile

Permanently deletes the profile.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.deleteProfile(profileId);
```

## Space lookup

### .buildings

Fetches every building that belongs to the tenant.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final buildings = await OneS1ght.buildings();
final building = await OneS1ght.building(id: buildingId);
```

### .floors

Fetches the floors of a building.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final floors = await OneS1ght.floors(buildingId: buildingId);
```

### .floor

Fetches the details of the selected floor.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final floor = await OneS1ght.floor(buildingId: buildingId, floorId: floorId);
final png = floor.image;   // Uint8List? — Image.memory(png)
```

### .zones

Fetches every zone on the selected floor.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final zones = await OneS1ght.zones(buildingId: buildingId, floorId: floorId);
final zone = await OneS1ght.zone(buildingId: buildingId, floorId: floorId, zoneId: zoneId);
```

### .locators

Fetches the locators on the selected floor.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final floorLocators = await OneS1ght.locators(buildingId: buildingId, floorId: floorId);
```

## Setting the floor

### .setFloorMap

Sets the floor to start positioning on.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final floor = await OneS1ght.floor(buildingId: buildingId, floorId: floorId);
await OneS1ght.setFloorMap(floor, buildingId: buildingId);
```

### .refreshZones

Fetches the latest zone data.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final zones = await OneS1ght.refreshZones();
```

## Positioning session

### .floorSession

Gets the locator session for the selected floor.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final session = await OneS1ght.floorSession();
```

### .begin

Starts positioning the user.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await session.begin();
```

### .end

Stops positioning the user.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await session.end();
```

### .pause · .resume

Pauses and resumes positioning. Unlike `end`, the positioning engine inside the SDK keeps running.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await session.pause();
await session.resume();
```

### .isRunning · .isPaused

Returns whether positioning is running and whether it is paused.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
final running = await session.isRunning();
final paused = await session.isPaused();
final current = await session.floor();   // Floor?
```

## Session events

### .onPosition

Fires with the user's coordinates in real time (4 times per second by default).

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onPosition.listen((c) => debugPrint('${c.x}, ${c.y}'));
```

### .onZoneEnter · .onZoneExit

Fires when the user enters or exits a zone.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onZoneEnter.listen((zone) => debugPrint('IN ${zone.name}'));
session.onZoneExit.listen((zone) => debugPrint('OUT ${zone.name}'));
```

### .onZoneDwell

Fires when the dwell time in a zone exceeds the threshold (`dwellSeconds`).

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onZoneDwell.listen((d) => debugPrint('DWELL ${d.zone.name} ${d.seconds}s'));
```

### .onTriggers

Fires when an in-space event (campaign) is triggered.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onTriggers.listen((t) {
  for (final trigger in t.triggers) {
    debugPrint('${t.zoneId} ${trigger.type}');
  }
});
```

### .onFloorDetected

Fires when a locator's BLE signal is received.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onFloorDetected.listen((floorId) async {
  if (floorId == null) return;
  final floor = await OneS1ght.floor(buildingId: buildingId, floorId: floorId);
  await OneS1ght.setFloorMap(floor, buildingId: buildingId);
});
```

### .onStopped

Fires when positioning stops.

| Reason | Meaning |
| - | - |
| `ended` | `end()` · `reset` · key change |
| `engineFailed` | The positioning engine failed to run |

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onStopped.listen((reason) {
  if (reason == StopReason.engineFailed) { }
});
```

### .onConfigChanged

Fires when settings change in the console.

| Signal | Meaning |
| - | - |
| `ZonesChanged(floorId)` | Zones changed |
| `PlanChanged(floorId)` | Floor plan changed |
| `RulesChanged(zoneId)` | Campaigns changed |
| `SdkConfigChanged` | Remote config changed |
| `ResyncNeeded` | Reconnected · events missed |

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
session.onConfigChanged.listen((change) {
  switch (change) {
    case ZonesChanged() || ResyncNeeded():
      OneS1ght.refreshZones();
    case PlanChanged(:final floorId):
      debugPrint('redraw $floorId');
    default:
      break;
  }
});
```

## Data upload

Coordinates are uploaded automatically every 300 entries or 60 seconds, as well as when the app goes to the background and on `end()`.

### .uploadPendingPositions

Uploads buffered coordinates immediately.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.uploadPendingPositions();
```

### .discardPendingPositions

Discards buffered coordinates.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
await OneS1ght.discardPendingPositions();
```

## Error handling

Every failure is a `OneS1ghtException`. See [Error codes](/en/sdk/troubleshooting/error-codes) for details.

```dart Dart icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/dart.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=02dee5dd767b4c76ef0e07bc8663c542" theme={null}
try {
  await OneS1ght.initialize(sdkKey: key);
} on OneS1ghtException catch (e) {
  debugPrint('${e.code} ${e.message}');   // "E1003" …
}
```

## Models

Lists are `List<T>`, bytes are `Uint8List`.

### Coordinates

| Field | Type | Description |
| - | - | - |
| `x` · `y` | `double` | Meters, local to the floor plan |
| `z` | `double` | Height |

### Building · Floor

| Type | Field | Description |
| - | - | - |
| `Building` | `id` · `name` | Building ID · name |
| | `floorCount: int?` | Number of floors |
| `Floor` | `id` · `name` | Floor ID · name |
| | `image: Uint8List?` | Floor plan image (raw bytes, e.g. PNG) |
| | `hasPlan: bool` | Whether a floor plan is registered |
| | `originX` · `originY` | Floor plan origin (meters) |
| | `widthM` · `heightM` | Floor plan size (meters) |
| | `minX` · `minY` · `maxX` · `maxY` | Placement bounds |

### Locator · FloorLocators

| Type | Field | Description |
| - | - | - |
| `Locator` | `address: int` | Last 2 bytes of the UWB MAC |
| | `x` · `y` · `z` | Meters, local to the floor plan |
| `FloorLocators` | `locators` | Locators on the floor |
| | `sessionId: int?` | UWB session — differs per floor |
| | `positioningReady: bool` | Whether both locators and a session exist |

### Zone

| Field | Type | Description |
| - | - | - |
| `id` · `name` | `String` | Zone ID · name |
| `polygon` | `List<Position>` | Vertices (`x`, `y` in meters) |
| `dwellSeconds` | `int?` | Dwell event threshold (seconds) |

### Trigger

| Field | Type | Description |
| - | - | - |
| `triggerId` | `String` | Trigger ID |
| `type` | `String` | `signage` · `coupon` · `tracking` · `merch` · `generic` |
| `payload` | `Map<String, String>?` | Extra data per type |

Enums (`ConfigChange` · `StopReason` · `PermissionStatus` · `DeviceAvailability` · `LogLevel`) may gain values in minor versions — keep a `default` in `switch`.

## Limitations

* Every call is a `Future` and every event a `Stream` — you can update the UI directly.
* UWB positioning is foreground only — it stops in the background and resumes when the app returns.
* The coordinate buffer is kept in app memory — unsent coordinates are lost if the app is force-quit.
* Positioning does not work on the emulator.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.