> ## 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)

## インポート

```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';
```

## 初期化

### .initialize

OneS1ght API キーで測位エンジンを初期化します。

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

測位エンジンの利用に必要なアプリ権限をリクエストします。

| 結果 | 意味 |
| - | - |
| `authorized` | 測位可能 |
| `denied` | 権限拒否 |
| `unsupported` | 測位非対応端末 |

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

SDK のログ文言の言語を設定します。<br />
`ko`: 韓国語、  `ja`: 日本語、  `en`: 英語、 `null`: システム設定の言語

```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('ja');
```

### .onDebugLog

SDK のログを受信します。<br />
`level`: ログレベル、 `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

初期化を取り消し、現在のセッションを破棄します。新しいセッションは作成しないため、続けて使うには `initialize` を再度呼び出してください（別のキーでも可能です）。

```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();
```

## 状態の取得

### .isInitialized

初期化に成功したかを返します。

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

測位可能な端末かを判定し、非対応の場合はその理由を返します。

| 値 | 意味 |
| - | - |
| `available` | 測位可能 |
| `osVersionTooLow` | iOS 27・Android 17（API 37）未満 |
| `deviceNotSupported` | UWB 非対応端末 |

Android では `initialize()` の後に読み取ってください。それより前は判定できず `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

図面を表示するための Google Maps API キーを返します。

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

使用中のネイティブ SDK バージョンを返します。<br />
プラグインのバージョンは `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();
```

## プロフィール

### .createProfile

新しいパーソナライズプロフィールを作成します。成功すると一意のプロフィール ID を返します。

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

収集する測位データを紐付けるプロフィールを設定します。解除する場合は `null` を設定してください。

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

プロフィールの属性を取得します。

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

プロフィールの属性を置き換えます。以前のデータは削除されます。

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

プロフィール情報を完全に削除します。

```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);
```

## 空間の取得

### .buildings

テナントに紐付くすべての建物一覧を取得します。

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

建物のフロア一覧を取得します。

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

選択したフロアの詳細情報を取得します。

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

選択したフロアのすべてのゾーンを取得します。

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

選択したフロアのロケーター情報を取得します。

```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);
```

## フロアの指定

### .setFloorMap

測位を開始するフロアを指定します。

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

最新のゾーン情報を取得します。

```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();
```

## 測位セッション

### .floorSession

選択したフロアのロケーターセッションを取得します。

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

ユーザーの測位を開始します。

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

ユーザーの測位を終了します。

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

ユーザーの測位を一時停止・再開します。終了とは異なり、SDK 内の測位エンジンは停止しません。

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

測位中かどうかと、一時停止中かどうかを返します。

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

## セッションイベント

### .onPosition

ユーザーの座標をリアルタイムで返すイベントが発生します（デフォルトは毎秒 4 回）。

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

ゾーンへの進入・退出時にイベントが発生します。

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

特定ゾーンの滞在時間が基準（`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

空間内のイベント（施策）が動作するとイベントが発生します。

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

ロケーターの BLE 信号を受信するとイベントが発生します。

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

ユーザーの測位が停止するとイベントが発生します。

| 理由 | 意味 |
| - | - |
| `ended` | `end()`・`reset`・キーの変更 |
| `engineFailed` | 測位エンジンの起動失敗 |

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

コンソール画面で設定が変更されるとイベントが発生します。

| シグナル | 意味 |
| - | - |
| `ZonesChanged(floorId)` | ゾーン変更 |
| `PlanChanged(floorId)` | 図面変更 |
| `RulesChanged(zoneId)` | 施策変更 |
| `SdkConfigChanged` | リモート設定変更 |
| `ResyncNeeded` | 再接続・イベントの取りこぼし |

```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;
  }
});
```

## データ送信

座標は 300 件または 60 秒ごと、およびバックグラウンド移行時と `end()` 時に自動で送信されます。

### .uploadPendingPositions

溜めた座標を即時送信します。

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

溜めた座標を破棄します。

```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();
```

## エラー処理

失敗はすべて `OneS1ghtException` で届きます。詳細は[エラーコード](/ja/sdk/troubleshooting/error-codes)を参照してください。

```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" …
}
```

## モデル

リストは `List<T>`、バイト列は `Uint8List` です。

### Coordinates

| フィールド | 型 | 説明 |
| - | - | - |
| `x`・`y` | `double` | 図面ローカルのメートル |
| `z` | `double` | 高さ |

### Building · Floor

| 型 | フィールド | 説明 |
| - | - | - |
| `Building` | `id`・`name` | 建物 ID・名前 |
| | `floorCount: int?` | フロア数 |
| `Floor` | `id`・`name` | フロア ID・名前 |
| | `image: Uint8List?` | 図面画像（PNG などの元のバイト列） |
| | `hasPlan: bool` | 図面登録の有無 |
| | `originX`・`originY` | 図面原点（メートル） |
| | `widthM`・`heightM` | 図面サイズ（メートル） |
| | `minX`・`minY`・`maxX`・`maxY` | 配置範囲 |

### Locator · FloorLocators

| 型 | フィールド | 説明 |
| - | - | - |
| `Locator` | `address: int` | UWB MAC の下位 2 バイト |
| | `x`・`y`・`z` | 図面ローカルのメートル |
| `FloorLocators` | `locators` | フロアのロケーター一覧 |
| | `sessionId: int?` | UWB セッション — フロアごとに異なる |
| | `positioningReady: bool` | ロケーターとセッションの両方があるか |

### Zone

| フィールド | 型 | 説明 |
| - | - | - |
| `id`・`name` | `String` | ゾーン ID・名前 |
| `polygon` | `List<Position>` | 頂点（`x`、`y` メートル） |
| `dwellSeconds` | `int?` | 滞在イベントの基準（秒） |

### Trigger

| フィールド | 型 | 説明 |
| - | - | - |
| `triggerId` | `String` | トリガー ID |
| `type` | `String` | `signage`・`coupon`・`tracking`・`merch`・`generic` |
| `payload` | `Map<String, String>?` | 種類ごとの付加情報 |

列挙型（`ConfigChange`・`StopReason`・`PermissionStatus`・`DeviceAvailability`・`LogLevel`）はマイナーバージョンで値が増えることがあります — `switch` に `default` を置いてください。

## 制約

* すべての呼び出しは `Future`、イベントは `Stream` — UI をそのまま更新できます。
* UWB 測位はフォアグラウンド専用で、バックグラウンドで停止し、復帰すると再開します。
* 座標バッファはアプリのメモリ上に一時保存され、強制終了すると未送信の座標は失われます。
* エミュレーターでは測位できません。


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