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

# Android SDK

> SDK Version 0.0.9

## インポート

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  import co.onecheck.ones1ght.android.*           // OneS1ght · FloorSession · SdkError · リスナー
  import co.onecheck.ones1ght.android.model.*     // Building · Floor · Zone · Coordinates · Trigger · ConfigChange
  import co.onecheck.ones1ght.android.network.ApiError
  import co.onecheck.ones1ght.android.runtime.LogLevel
  ```

  ```java Java icon="java" theme={null}
  import co.onecheck.ones1ght.android.*;          // OneS1ght · FloorSession · SdkError · Callback · リスナー
  import co.onecheck.ones1ght.android.model.*;    // Building · Floor · Zone · Coordinates · Trigger · ConfigChange
  import co.onecheck.ones1ght.android.network.ApiError;
  import co.onecheck.ones1ght.android.runtime.LogLevel;
  ```
</CodeGroup>

## 初期化

### .initialize

OneS1ght API キーで測位エンジンを初期化します。自社サーバーを構築した場合のみ `baseUrl` を渡します（デフォルトは `OneS1ght.DEFAULT_BASE_URL`）。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.initialize(context = context.applicationContext, sdkKey = "YOUR_SDK_KEY")
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.initialize(context, "YOUR_SDK_KEY", new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .requestPermission

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

| 結果 | 意味 |
| - | - |
| `AUTHORIZED` | 測位可能 |
| `DENIED` | 権限拒否 |
| `UNSUPPORTED` | 測位非対応端末 |

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val status = OneS1ght.requestPermission(activity)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.requestPermission(activity, new Callback<PermissionStatus>() {
      @Override public void onSuccess(PermissionStatus status) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .setLanguage

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.setLanguage("ja")
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.setLanguage("ja");
  ```
</CodeGroup>

### .onDebugLog

SDK のログを受信します。<br />
`level`: ログレベル、 `message`: ログメッセージ

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.onDebugLog = DebugLogListener { level, message ->
      if (level >= LogLevel.WARN) Log.w("OneS1ght", message)
  }
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.setOnDebugLog((level, message) -> {
      if (level.compareTo(LogLevel.WARN) >= 0) Log.w("OneS1ght", message);
  });
  ```
</CodeGroup>

### .reset

セッションを破棄して測位を止め、保存されたキーと建物情報を消去します。その後は `initialize` を再度呼んでください（それまでは `NotInitialized`、`E1001`）。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.reset()
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.reset(new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

## 状態の取得

### .isInitialized

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val ready = OneS1ght.isInitialized
  ```

  ```java Java icon="java" theme={null}
  boolean ready = OneS1ght.isInitialized();
  ```
</CodeGroup>

### .deviceAvailability

測位可能な端末かを判定し、非対応の場合はその理由を返します。`initialize()` の後に読みます — それより前は `DEVICE_NOT_SUPPORTED`（Android 17 未満は `OS_VERSION_TOO_LOW`）です。

| 値 | 意味 |
| - | - |
| `AVAILABLE` | 測位可能 |
| `OS_VERSION_TOO_LOW` | Android 17（API 37）未満 |
| `DEVICE_NOT_SUPPORTED` | UWB 非対応端末 |

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  when (OneS1ght.deviceAvailability) {   // initialize() の後に
      DeviceAvailability.AVAILABLE            -> Unit
      DeviceAvailability.OS_VERSION_TOO_LOW   -> Unit
      DeviceAvailability.DEVICE_NOT_SUPPORTED -> Unit
      else                                    -> Unit
  }
  ```

  ```java Java icon="java" theme={null}
  DeviceAvailability availability = OneS1ght.getDeviceAvailability();
  boolean available = OneS1ght.isDeviceAvailable();
  ```
</CodeGroup>

### .googleMapKey

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val mapKey = OneS1ght.googleMapKey   // String?
  ```

  ```java Java icon="java" theme={null}
  String mapKey = OneS1ght.getGoogleMapKey();
  ```
</CodeGroup>

### .SDK\_VERSION

使用中の SDK バージョンを返します。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val version = OneS1ght.SDK_VERSION   // "0.0.9"
  ```

  ```java Java icon="java" theme={null}
  String version = OneS1ght.SDK_VERSION;
  ```
</CodeGroup>

## プロフィール

### .createProfile

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val profileId = OneS1ght.createProfile(mapOf("gender" to "F", "ageBand" to "20s"))
  ```

  ```java Java icon="java" theme={null}
  Map<String, String> attributes = new HashMap<>();
  attributes.put("gender", "F");
  attributes.put("ageBand", "20s");
  OneS1ght.createProfile(attributes, new Callback<String>() {
      @Override public void onSuccess(String profileId) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .identify

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.identify(profileId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.identify(profileId);
  ```
</CodeGroup>

### .fetchProfile

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val attributes = OneS1ght.fetchProfile(profileId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.fetchProfile(profileId, new Callback<Map<String, String>>() {
      @Override public void onSuccess(Map<String, String> attributes) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .replaceProfile

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.replaceProfile(profileId, mapOf("gender" to "F", "ageBand" to "30s"))
  ```

  ```java Java icon="java" theme={null}
  Map<String, String> attributes = new HashMap<>();
  attributes.put("gender", "F");
  attributes.put("ageBand", "30s");
  OneS1ght.replaceProfile(profileId, attributes, new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .deleteProfile

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.deleteProfile(profileId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.deleteProfile(profileId, new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

## 空間の取得

### .buildings

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val buildings = OneS1ght.buildings()
  val building = OneS1ght.building(id = buildingId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.buildings(new Callback<List<Building>>() {
      @Override public void onSuccess(List<Building> buildings) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .floors

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val floors = OneS1ght.floors(buildingId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.floors(buildingId, new Callback<List<Floor>>() {
      @Override public void onSuccess(List<Floor> floors) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .floor

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val floor = OneS1ght.floor(buildingId, floorId)
  val png = floor.image   // ByteArray?
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
      @Override public void onSuccess(Floor floor) { byte[] png = floor.getImage(); }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .zones

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val zones = OneS1ght.zones(buildingId, floorId)
  val zone = OneS1ght.zone(buildingId, floorId, zoneId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.zones(buildingId, floorId, new Callback<List<Zone>>() {
      @Override public void onSuccess(List<Zone> zones) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .locators

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val floorLocators = OneS1ght.locators(buildingId, floorId)
  val ready = floorLocators.positioningReady
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.locators(buildingId, floorId, new Callback<FloorLocators>() {
      @Override public void onSuccess(FloorLocators floorLocators) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

## フロアの指定

### .setFloorMap

ゾーンイベントに使うフロアを指定します（任意）。指定しなくても座標は届きますが、ゾーンイベント・施策を受け取るには必要です。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val floor = OneS1ght.floor(buildingId, floorId)
  OneS1ght.setFloorMap(floor, buildingId)
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
      @Override public void onSuccess(Floor floor) {
          OneS1ght.setFloorMap(floor, buildingId, new Callback<Void>() {
              @Override public void onSuccess(Void result) { }
              @Override public void onError(Throwable error) { }
          });
      }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .refreshZones

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val zones = OneS1ght.refreshZones()
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.refreshZones(new Callback<List<Zone>>() {
      @Override public void onSuccess(List<Zone> zones) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

## 測位セッション

### .floorSession

測位セッションを返します。フロアに関係なくアプリ全体で 1 つのインスタンスで、`initialize` 前は `NotInitialized` を投げます。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val session = OneS1ght.floorSession()
  ```

  ```java Java icon="java" theme={null}
  FloorSession session = OneS1ght.floorSession();
  ```
</CodeGroup>

### .begin

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.begin()
  ```

  ```java Java icon="java" theme={null}
  session.begin(new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .end

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.end()
  ```

  ```java Java icon="java" theme={null}
  session.end(new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .pause · .resume

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.pause()
  session.resume()
  ```

  ```java Java icon="java" theme={null}
  session.pause();
  session.resume();
  ```
</CodeGroup>

### .isRunning · .isPaused

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  val running = session.isRunning
  val paused = session.isPaused
  val current = session.floor   // Floor?
  ```

  ```java Java icon="java" theme={null}
  boolean running = session.isRunning();
  boolean paused = session.isPaused();
  Floor current = session.getFloor();
  ```
</CodeGroup>

## セッションイベント

### .onPosition

ユーザーの座標をリアルタイムで届けます。エンジンが出す速度のまま届き、サーバー送信だけがコンソールの設定値（デフォルトは毎秒 4 回）に間引かれます。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onPosition = PositionListener { coordinates -> Log.d("OneS1ght", "${coordinates.x}, ${coordinates.y}") }
  ```

  ```java Java icon="java" theme={null}
  session.setOnPosition(coordinates -> Log.d("OneS1ght", coordinates.getX() + ", " + coordinates.getY()));
  ```
</CodeGroup>

### .onZoneEnter · .onZoneExit

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onZoneEnter = ZoneListener { zone -> Log.d("OneS1ght", "IN ${zone.name}") }
  session.onZoneExit  = ZoneListener { zone -> Log.d("OneS1ght", "OUT ${zone.name}") }
  ```

  ```java Java icon="java" theme={null}
  session.setOnZoneEnter(zone -> Log.d("OneS1ght", "IN " + zone.getName()));
  session.setOnZoneExit(zone -> Log.d("OneS1ght", "OUT " + zone.getName()));
  ```
</CodeGroup>

### .onZoneDwell

特定ゾーンの滞在時間が基準（`dwellSeconds`）を超えるとイベントが発生します。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onZoneDwell = DwellListener { zone, seconds -> Log.d("OneS1ght", "DWELL ${zone.name} ${seconds}s") }
  ```

  ```java Java icon="java" theme={null}
  session.setOnZoneDwell((zone, seconds) -> Log.d("OneS1ght", "DWELL " + zone.getName() + " " + seconds));
  ```
</CodeGroup>

### .onTriggers

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onTriggers = TriggersListener { zoneId, triggers ->
      triggers.forEach { trigger -> Log.d("OneS1ght", "${trigger.type} ${trigger.payload}") }
  }
  ```

  ```java Java icon="java" theme={null}
  session.setOnTriggers((zoneId, triggers) -> {
      for (Trigger trigger : triggers) Log.d("OneS1ght", trigger.getType());
  });
  ```
</CodeGroup>

### .onFloorDetected

エンジンがロケーターの BLE 信号でフロアを見つけるとフロア ID で、フロアを見失うと `null` で呼ばれます。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onFloorDetected = SessionFloorListener { floorId ->
      if (floorId == null) return@SessionFloorListener
      lifecycleScope.launch {
          val floor = OneS1ght.floor(buildingId, floorId)
          OneS1ght.setFloorMap(floor, buildingId)
      }
  }
  ```

  ```java Java icon="java" theme={null}
  session.setOnFloorDetected(floorId -> {
      if (floorId == null) return;
      OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
          @Override public void onSuccess(Floor floor) {
              OneS1ght.setFloorMap(floor, buildingId, new Callback<Void>() {
                  @Override public void onSuccess(Void result) { }
                  @Override public void onError(Throwable error) { }
              });
          }
          @Override public void onError(Throwable error) { }
      });
  });
  ```
</CodeGroup>

### .onStopped

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

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onStopped = SessionStoppedListener { reason ->
      when (reason) {
          FloorSession.StopReason.ENDED         -> Unit
          FloorSession.StopReason.ENGINE_FAILED -> Unit
          else                                  -> Unit
      }
  }
  ```

  ```java Java icon="java" theme={null}
  session.setOnStopped(reason -> {
      if (reason == FloorSession.StopReason.ENGINE_FAILED) { }
  });
  ```
</CodeGroup>

### .onConfigChanged

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

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  session.onConfigChanged = ConfigChangeListener { change ->
      when (change) {
          is ConfigChange.ZonesChanged, is ConfigChange.ResyncNeeded -> lifecycleScope.launch { OneS1ght.refreshZones() }
          is ConfigChange.PlanChanged -> redrawFloor()
          else -> Unit
      }
  }
  ```

  ```java Java icon="java" theme={null}
  session.setOnConfigChanged(change -> {
      if (change instanceof ConfigChange.ZonesChanged || change instanceof ConfigChange.ResyncNeeded) {
          OneS1ght.refreshZones(new Callback<List<Zone>>() {
              @Override public void onSuccess(List<Zone> zones) { }
              @Override public void onError(Throwable error) { }
          });
      }
  });
  ```
</CodeGroup>

## データ送信

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

### .uploadPendingPositions

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.uploadPendingPositions()
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.uploadPendingPositions(new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) { }
  });
  ```
</CodeGroup>

### .discardPendingPositions

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

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  OneS1ght.discardPendingPositions()
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.discardPendingPositions();
  ```
</CodeGroup>

## エラー処理

失敗は `SdkError`（SDK の状態）と `ApiError`（通信、`co.onecheck.ones1ght.android.network.ApiError`）で届きます。詳細は[エラーコード](/ja/sdk/troubleshooting/error-codes)を参照してください。

<CodeGroup>
  ```kotlin Kotlin icon="https://mintcdn.com/onecheck/wv66PbaB8dD4xd9I/images/icons/kotlin.svg?fit=max&auto=format&n=wv66PbaB8dD4xd9I&q=85&s=3721cc48a6f44aef50ea7a0151e369f2" theme={null}
  try {
      OneS1ght.initialize(context = context.applicationContext, sdkKey = key)
  } catch (e: SdkError) {
      Log.w("OneS1ght", e.code.code)                     // "E1003"
  } catch (e: ApiError) {
      Log.w("OneS1ght", "${e.code.code} ${e.message}")   // "E5005 …"
  }
  ```

  ```java Java icon="java" theme={null}
  OneS1ght.initialize(context, key, new Callback<Void>() {
      @Override public void onSuccess(Void result) { }
      @Override public void onError(Throwable error) {
          if (error instanceof SdkError) {
              Log.w("OneS1ght", ((SdkError) error).getCode().getCode());   // "E1003"
          } else if (error instanceof ApiError) {
              Log.w("OneS1ght", ((ApiError) error).getCode().getCode() + " " + error.getMessage());
          }
      }
  });
  ```
</CodeGroup>

## モデル

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

### Coordinates

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

### Building · Floor

| 型 | フィールド | 説明 |
| - | - | - |
| `Building` | `id`・`name` | 建物 ID・名前 |
| | `floorCount: Int?` | フロア数 |
| `Floor` | `id`・`name` | フロア ID・名前 |
| | `image: ByteArray?` | デコード済みの図面 PNG バイト — 一覧取得では `null` |
| | `hasPlan: Boolean` | 図面登録の有無 |
| | `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: Boolean` | ロケーターとセッションの両方があるか |

### 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`）はマイナーバージョンで値が増えることがあります — `when` に `else` を置いてください。

## 制約

* `suspend` API はどのコルーチンからでも呼べます。`identify`・`discardPendingPositions`・`pause`・`resume` はメインスレッドで使用します。
* UWB 測位はフォアグラウンド専用です。バックグラウンドに入ると測位が止まり、滞在中のゾーンは退出（`onZoneExit`）として扱われ、リアルタイム受信が切れます。復帰すると測位が再開し、`ResyncNeeded` が届きます。
* 座標バッファはアプリのメモリ上に一時保存され、強制終了すると未送信の座標は失われます。
* エミュレーターでは測位できません。


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