Android SDK - OneS1ght

OneS1ght Android SDK 의 모든 공개 API 를 메서드 단위로 정리한 문서입니다. 메서드마다 Kotlin · Java 탭에서 예시를 고를 수 있고, 한 번 고른 언어는 페이지 전체에 유지됩니다.

이 문서는 Android SDK 0.0.9 기준입니다. API 이름과 동작은 iOS · Flutter 와 같습니다.

언어	호출 형태
Kotlin	`suspend fun`. 코루틴 안에서 호출합니다
Java	같은 이름의 메서드에 마지막 인자로 `Callback<T>` 를 넘깁니다. 결과는 메인 스레드로 옵니다

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.*;          // OneS1ght · FloorSession · SdkError · Callback · 리스너
import co.onecheck.ones1ght.android.model.*;    // Building · Floor · Zone · Coordinates · Trigger · ConfigChange

설치와 권한 설정은 Android 시작하기를 먼저 따라 주세요.

초기화

앱 시작 시 한 번 SDK 를 준비합니다. onDebugLog 는 initialize 보다 먼저 등록해야 초기화 로그를 놓치지 않습니다.

.initialize

콘솔에서 발급한 SDK 키(ock_sdk_…)로 SDK 를 초기화합니다. 키 검증과 설정 수신을 함께 하며, 앱이 넘기는 키는 이것 하나뿐입니다.

성공 후 다시 부르면 무시되고, 실패 후 다시 부르면 재시도합니다. 다른 키로 부르면 세션을 새로 구성합니다.
건물·층은 조회하지 않습니다. 기기 지원 여부도 여기서 막지 않습니다 — 미지원 기기도 초기화는 통과하며 측위 시작(begin)에서만 거절됩니다.
자체 서버를 쓰는 고객만 baseUrl 을 넘깁니다. 기본값은 https://console.ones1ght.com/api/sdk/v1 입니다.

OneS1ght.initialize(context = context.applicationContext, sdkKey = "YOUR_SDK_KEY")

OneS1ght.initialize(context, "YOUR_SDK_KEY", new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.requestPermission

측위 권한을 확인하고 필요하면 시스템 권한 창을 띄웁니다. 이미 답한 권한이면 창 없이 바로 돌아오며, initialize 전에도 부를 수 있습니다.

결과	뜻
`authorized`	측위를 시작할 수 있습니다
`denied`	거부됨 — 앱에서 다시 물을 수 없으니 설정 앱으로 안내하세요
`unsupported`	이 기기·OS 에서는 측위 자체가 불가 — 창 없이 바로 돌아옵니다

RANGING·정밀 위치·BLUETOOTH_SCAN 을 한 번에 묻습니다. ComponentActivity 를 넘깁니다.

val status = OneS1ght.requestPermission(activity)   // AUTHORIZED · DENIED · UNSUPPORTED

OneS1ght.requestPermission(activity, new Callback<PermissionStatus>() {
    @Override public void onSuccess(PermissionStatus status) { }
    @Override public void onError(Throwable error) { }
});

.setLanguage

SDK 로그와 안내 문구의 언어를 정합니다 — "ko" · "ja" · "en". nil(null)이면 기기 언어를 따릅니다(기본값).

OneS1ght.setLanguage("ko")

OneS1ght.setLanguage("ko");

.onDebugLog

SDK 내부 활동 로그를 등급과 함께 받습니다. 등급은 log < info < warn < error 이며, 코드가 붙은 줄([E3007] …)은 에러 코드로 찾아볼 수 있습니다. 수집 방법은 디버그 로그를 참고하세요.

OneS1ght.onDebugLog = DebugLogListener { level, message ->
    if (level >= LogLevel.WARN) Log.w("OneS1ght", message)
}

OneS1ght.setOnDebugLog((level, message) -> {
    if (level.compareTo(LogLevel.WARN) >= 0) Log.w("OneS1ght", message);
});

LogLevel 은 Android 에서 co.onecheck.ones1ght.android.runtime.LogLevel 입니다.

.reset

세션을 버립니다. 이후 다른 키로 initialize 할 수 있습니다 — 런타임에 키를 바꿀 때 씁니다.

OneS1ght.reset()

OneS1ght.reset(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

상태 조회

네트워크를 쓰지 않고 SDK 상태를 읽습니다. Java 는 getter(OneS1ght.isInitialized(), OneS1ght.getDeviceAvailability())로 읽습니다.

.isInitialized

초기화가 성공했는지 — 키가 유효하고 설정을 받았는지 — 를 돌려줍니다.

val ready = OneS1ght.isInitialized

boolean ready = OneS1ght.isInitialized();

.deviceAvailability

이 기기에서 측위가 되는지와 안 되는 이유를 돌려줍니다. isDeviceAvailable 은 그 요약(== available)입니다.

값	뜻	안내 예
`available`	측위 가능	—
`osVersionTooLow`	Android 17(API 37) 미만	”OS 업데이트 후 사용할 수 있습니다”
`deviceNotSupported`	UWB(DL-TDoA) 미지원 기기	”이 기기는 실내 측위를 지원하지 않습니다”

Kotlin·Java 는 AVAILABLE · OS_VERSION_TOO_LOW · DEVICE_NOT_SUPPORTED 입니다.

when (OneS1ght.deviceAvailability) {
    DeviceAvailability.AVAILABLE            -> Unit
    DeviceAvailability.OS_VERSION_TOO_LOW   -> Unit   // OS 업데이트 안내
    DeviceAvailability.DEVICE_NOT_SUPPORTED -> Unit   // 미지원 기기 안내
    else                                    -> Unit
}

DeviceAvailability availability = OneS1ght.getDeviceAvailability();
boolean available = OneS1ght.isDeviceAvailable();

initialize 다음에 읽으세요. 그 전에는 UWB 칩을 확인할 수 없어 deviceNotSupported 가 오고 디버그 로그에 경고가 남습니다.

.googleMapKey

콘솔이 내려준 Google Maps 키입니다. 앱이 자체 지도를 그릴 때 씁니다. initialize 가 성공하기 전에는 비어 있습니다.

val mapKey = OneS1ght.googleMapKey   // String?

String mapKey = OneS1ght.getGoogleMapKey();   // null 가능

.sdkVersion

SDK 버전 문자열입니다.

val version = OneS1ght.SDK_VERSION   // "0.0.9"

String version = OneS1ght.SDK_VERSION;

프로필

측위 데이터는 프로필 ID 로 묶입니다. 고객사 회원 ID 는 서버로 오지 않습니다 — 회원과 프로필의 매핑은 고객사만 보관합니다.

.createProfile

속성을 담아 프로필을 만들고 서버가 발급한 profileId 를 돌려받습니다. 앱이 보관해 두고 다음 실행에도 재사용하세요. 속성은 자유롭게 정할 수 있으며, 나이는 정확한 값 대신 연령대("20s")를 권장합니다.

val profileId = OneS1ght.createProfile(mapOf("gender" to "F", "ageBand" to "20s"))

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

.identify

이 기기의 측위를 프로필에 연결합니다. 측위를 시작하기 전에 반드시 호출하세요 — 없으면 begin 이 E1004 로 거절됩니다. 로그아웃할 때는 nil(null)을 넘깁니다. initialize 앞뒤 어디서 불러도 되고, reset·키 교체 뒤에도 이어집니다.

OneS1ght.identify(profileId)

OneS1ght.identify(profileId);

.fetchProfile

프로필 속성을 조회합니다.

val attributes = OneS1ght.fetchProfile(profileId)

OneS1ght.fetchProfile(profileId, new Callback<Map<String, String>>() {
    @Override public void onSuccess(Map<String, String> attributes) { }
    @Override public void onError(Throwable error) { }
});

.replaceProfile

프로필 속성을 통째로 교체합니다. 넘기지 않은 속성은 지워집니다 — 부분 갱신이 아닙니다.

OneS1ght.replaceProfile(profileId, mapOf("gender" to "F", "ageBand" to "30s"))

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

.deleteProfile

프로필을 삭제합니다. 이미 쌓인 좌표·이벤트는 보존 정책을 따릅니다.

OneS1ght.deleteProfile(profileId)

OneS1ght.deleteProfile(profileId, new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

공간 조회

콘솔에 등록된 건물·층·구역을 읽습니다. 서버 엔드포인트 하나당 메서드 하나이며, 목록과 단건이 짝을 이룹니다.

.buildings

건물 목록을 돌려줍니다. 콘솔에 연결된 공간이 없으면 빈 목록입니다. building(id:) 는 건물 하나를 돌려줍니다.

val buildings = OneS1ght.buildings()
val building = OneS1ght.building(id = buildingId)

OneS1ght.buildings(new Callback<List<Building>>() {
    @Override public void onSuccess(List<Building> buildings) { }
    @Override public void onError(Throwable error) { }
});

.floors

건물의 층 목록입니다. 목록을 가볍게 유지하려고 도면 이미지는 비워서 줍니다(image == nil).

val floors = OneS1ght.floors(buildingId)

OneS1ght.floors(buildingId, new Callback<List<Floor>>() {
    @Override public void onSuccess(List<Floor> floors) { }
    @Override public void onError(Throwable error) { }
});

.floor

층 하나를 도면 이미지와 함께 돌려줍니다. 캐시에서 나오므로 요청이 늘지 않고, 콘솔이 도면을 바꾸면 캐시를 버립니다. 좌표는 도면 로컬 미터이며 originX · originY · widthM · heightM 으로 화면 좌표로 바꿉니다.

val floor = OneS1ght.floor(buildingId, floorId)
val png = floor.image   // ByteArray?

OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
    @Override public void onSuccess(Floor floor) { byte[] png = floor.getImage(); }
    @Override public void onError(Throwable error) { }
});

.zones

층의 구역 목록입니다. zone(buildingId:floorId:zoneId:) 는 구역 하나를 돌려줍니다.

val zones = OneS1ght.zones(buildingId, floorId)
val zone = OneS1ght.zone(buildingId, floorId, zoneId)

OneS1ght.zones(buildingId, floorId, new Callback<List<Zone>>() {
    @Override public void onSuccess(List<Zone> zones) { }
    @Override public void onError(Throwable error) { }
});

.locators

층에 설치된 로케이터 배치와 UWB 세션 ID 입니다. 설치·점검 화면처럼 로케이터를 직접 그릴 때 씁니다.

val floorLocators = OneS1ght.locators(buildingId, floorId)
val ready = floorLocators.positioningReady

OneS1ght.locators(buildingId, floorId, new Callback<FloorLocators>() {
    @Override public void onSuccess(FloorLocators floorLocators) { }
    @Override public void onError(Throwable error) { }
});

층 지정

층 지정은 선택입니다 — 측위 엔진이 BLE 로 층을 스스로 찾고, 찾은 층은 onFloorDetected 로 알려 줍니다. 사람이 층을 고르거나 측위 전에 지도를 먼저 그릴 때 setFloorMap 을 씁니다.

.setFloorMap

층을 지정합니다. 로케이터·세션·구역을 측위 엔진에 넣고, 측위 중이면 세션을 유지한 채 즉시 층을 바꿉니다. nil(null)을 넘기면 지정을 비웁니다.

buildingId 를 생략하면 직전에 지정한 건물을 씁니다. 처음 지정할 때는 건물을 함께 넘기세요 — 건물 인자도 직전 건물도 없으면 E3001 로 거절되고 지금 층은 그대로 둡니다.
층을 지정하지 않아도 좌표는 나오지만, 구역 이벤트(진입·이탈·체류)를 받으려면 층을 지정해야 합니다.

val floor = OneS1ght.floor(buildingId, floorId)
OneS1ght.setFloorMap(floor, buildingId)

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

.refreshZones

현재 층의 구역만 다시 받아 판정에 바로 반영합니다. 도면은 다시 받지 않아 가볍습니다. 실패해도 던지지 않고 지금 가진 구역을 돌려줍니다. 콘솔에서 구역이 바뀌었다는 신호(onConfigChanged)를 받았을 때 씁니다.

val zones = OneS1ght.refreshZones()

OneS1ght.refreshZones(new Callback<List<Zone>>() {
    @Override public void onSuccess(List<Zone> zones) { }
    @Override public void onError(Throwable error) { }
});

측위 세션

측위는 FloorSession 하나로 다룹니다. UWB 라디오·판정 엔진·좌표 버퍼가 기기당 하나뿐이라 세션은 항상 같은 인스턴스입니다.

.floorSession

측위 세션을 가져옵니다. initialize 를 한 번도 부르지 않았으면 E1001 입니다.

val session = OneS1ght.floorSession()

FloorSession session = OneS1ght.floorSession();

.begin

측위를 시작합니다. 매장에 들어왔을 때 부르세요. 거절되면 오류를 던집니다 — E1001(초기화 안 함) · E1004(identify 안 함) · E2001(OS 낮음) · E2002(미지원 기기).

session.begin()

session.begin(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.end

측위를 멈추고 남은 좌표를 전송합니다. 초기화와 층 지정은 유지되므로 begin 으로 다시 시작할 수 있습니다.

session.end()

session.end(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.pause · .resume

일시정지 — 좌표 표시·전송·구역 판정만 멈추고 엔진은 계속 돌립니다. 층을 계속 잡고 있어서 resume 하면 바로 이어집니다. 일시정지는 백그라운드에 다녀와도 유지되고 resume · end · begin 에서만 풀립니다.

session.pause()
session.resume()

session.pause();
session.resume();

.isRunning · .isPaused

측위 가동 여부와 일시정지 여부입니다. 엔진을 다시 켜지 못해 SDK 가 세션을 닫으면 isRunning 이 false 가 됩니다. 지금 지정된 층은 session.floor 로 읽습니다.

val running = session.isRunning
val paused = session.isPaused
val current = session.floor   // Floor?

boolean running = session.isRunning();
boolean paused = session.isPaused();
Floor current = session.getFloor();   // null 가능

세션 이벤트

이벤트는 세션에 답니다. 모든 콜백은 메인 스레드에서 불리므로 UI 를 바로 고쳐도 됩니다.

.onPosition

실시간 좌표입니다 — 도면 로컬 미터(x · y · z), 최대 초당 4회.

session.onPosition = PositionListener { coordinates ->
    Log.d("OneS1ght", "${coordinates.x}, ${coordinates.y}")
}

session.setOnPosition(coordinates -> {
    Log.d("OneS1ght", coordinates.getX() + ", " + coordinates.getY());
});

.onZoneEnter · .onZoneExit

구역 진입·이탈입니다. 기기에서 바로 판정하므로 서버를 거치지 않고 즉시 옵니다. 앱이 백그라운드로 내려가면 안에 있던 구역의 이탈도 옵니다(일시정지 중 제외).

session.onZoneEnter = ZoneListener { zone -> Log.d("OneS1ght", "IN ${zone.name}") }
session.onZoneExit  = ZoneListener { zone -> Log.d("OneS1ght", "OUT ${zone.name}") }

session.setOnZoneEnter(zone -> Log.d("OneS1ght", "IN " + zone.getName()));
session.setOnZoneExit(zone -> Log.d("OneS1ght", "OUT " + zone.getName()));

.onZoneDwell

구역에 머문 시간이 그 구역의 dwellSeconds 에 닿으면 방문당 한 번 옵니다 — (구역, 체류 초). dwellSeconds 가 없는 구역은 오지 않습니다.

session.onZoneDwell = DwellListener { zone, seconds -> Log.d("OneS1ght", "DWELL ${zone.name} ${seconds}s") }

session.setOnZoneDwell((zone, seconds) -> Log.d("OneS1ght", "DWELL " + zone.getName() + " " + seconds));

.onTriggers

구역 이벤트에 대해 서버가 매칭한 개인화 액션입니다 — (구역 ID, 트리거 목록). type 은 signage · coupon · tracking · merch · generic 이며 값이 늘 수 있습니다.

session.onTriggers = TriggersListener { zoneId, triggers ->
    triggers.forEach { trigger -> Log.d("OneS1ght", "${trigger.type} ${trigger.payload}") }
}

session.setOnTriggers((zoneId, triggers) -> {
    for (Trigger trigger : triggers) Log.d("OneS1ght", trigger.getType());
});

onTriggers 만 서버 응답입니다 — 네트워크가 끊기면 진입 판정은 오지만 트리거는 오지 않습니다.

.onFloorDetected

측위 엔진이 층을 잡으면 층 ID(Floor.id 와 같은 값)를, 잃으면 nil(null)을 줍니다. 그 층으로 setFloorMap 하면 구역 이벤트까지 받을 수 있습니다.

session.onFloorDetected = SessionFloorListener { floorId ->
    if (floorId == null) return@SessionFloorListener   // 층을 잃음
    // 코루틴에서 OneS1ght.floor(buildingId, floorId) → OneS1ght.setFloorMap(floor, buildingId)
}

session.setOnFloorDetected(floorId -> {
    if (floorId == null) return;   // 층을 잃음
    // OneS1ght.floor(buildingId, floorId, …) → OneS1ght.setFloorMap(floor, buildingId, …)
});

.onStopped

세션이 닫혔을 때 이유와 함께 옵니다. 불릴 때 isRunning 은 이미 false 입니다.

이유	뜻
`ended`	앱이 `end()` 를 불렀습니다(또는 `reset`·키 교체)
`engineFailed`	엔진이 스스로 꺼졌고 다시 켜지지 않아 SDK 가 세션을 닫았습니다

엔진이 스스로 꺼지면 SDK 가 3·10·30초 뒤 다시 켜 봅니다(앱이 화면에 있을 때만). 그래도 안 되거나 권한·Bluetooth·라이선스처럼 사람이 풀어야 하는 원인이면 세션을 닫습니다 — 원인을 푼 뒤 begin 으로 다시 여세요. Kotlin·Java 는 ENDED · ENGINE_FAILED 입니다.

session.onStopped = SessionStoppedListener { reason ->
    when (reason) {
        FloorSession.StopReason.ENDED         -> Unit
        FloorSession.StopReason.ENGINE_FAILED -> Unit   // 「다시 찾기」
        else                                  -> Unit
    }
}

session.setOnStopped(reason -> {
    if (reason == FloorSession.StopReason.ENGINE_FAILED) {
        // 「다시 찾기」 — 원인을 풀고 begin 을 다시 부른다
    }
});

.onConfigChanged

콘솔에서 구역·도면·시책이 바뀌면 알려 줍니다. SDK 는 이 신호로 아무것도 하지 않습니다 — 무엇을 다시 받을지는 앱이 정합니다.

신호	의미	권장 대응
`zonesChanged(floorId)`	구역이 생기거나 바뀌거나 사라짐	`refreshZones()` — 연달아 오면 1초쯤 모아서 한 번
`planChanged(floorId)`	층 도면이 바뀜	`floor()` 로 다시 받아 지도 다시 그리기
`rulesChanged(zoneId)`	시책 상태가 바뀜	들어가 있는 구역의 이벤트를 다시 조회
`sdkConfigChanged`	원격 설정이 바뀜	—
`resyncNeeded`	연결이 다시 맺어졌거나 이벤트를 놓침	쓰고 있는 정보를 통째로 다시 조회

Kotlin·Java 는 ZonesChanged · PlanChanged · RulesChanged · SdkConfigChanged · ResyncNeeded 클래스입니다.

session.onConfigChanged = ConfigChangeListener { change ->
    when (change) {
        is ConfigChange.ZonesChanged, is ConfigChange.ResyncNeeded -> Unit   // refreshZones()
        is ConfigChange.PlanChanged -> Unit                                   // 도면 다시 그리기
        else -> Unit
    }
}

session.setOnConfigChanged(change -> {
    if (change instanceof ConfigChange.ZonesChanged) {
        // OneS1ght.refreshZones(…)
    }
});

데이터 전송

좌표는 300건 또는 60초 중 먼저 닿는 쪽에서 자동으로 전송됩니다. 백그라운드로 갈 때와 end() 때도 남은 좌표를 보냅니다. 전송에 실패한 좌표는 다음 주기 전송이 다시 보냅니다.

.uploadPendingPositions

쌓인 좌표를 지금 바로 전송합니다.

OneS1ght.uploadPendingPositions()

OneS1ght.uploadPendingPositions(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.discardPendingPositions

쌓인 좌표를 보내지 않고 버립니다. 전송 중에 불러도 안전합니다.

OneS1ght.discardPendingPositions()

OneS1ght.discardPendingPositions();

오류 처리

오류 받기

실패는 SDK 상태 오류(SdkError)와 통신 오류(ApiError) 둘로 옵니다. 어느 쪽이든 에러 코드 문자열(E1002 등)을 꺼낼 수 있고, 코드는 iOS·Android·Flutter 가 같습니다.

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

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

ApiError 는 Android 에서 co.onecheck.ones1ght.android.network.ApiError 입니다.

오류	코드	언제	조치
`SdkError.notInitialized`	`E1001`	`initialize` 없이 다른 API 호출	호출 순서 수정
`SdkError.positioningDisabled`	`E1003`	키는 유효하나 측위 기능이 꺼짐	콘솔 설정 확인 · 지원팀 문의
`SdkError.notIdentified`	`E1004`	`identify` 없이 측위 시작	측위 전에 `identify(profileId)`
`SdkError.osVersionTooLow`	`E2001`	iOS 27 · Android 17 미만	OS 업데이트 안내
`SdkError.deviceNotSupported`	`E2002`	UWB 미지원 기기	`deviceAvailability` 로 미리 분기
`SdkError.floorNotSet`	`E3001`	건물 없이 `setFloorMap(floor)` 호출	처음엔 `buildingId` 를 함께
`ApiError.invalidKey`	`E1002`	키가 잘못됐거나 폐기됨(401)	콘솔에서 키 상태 확인
`ApiError.network`	`E5001`	오프라인·타임아웃	자동 재시도
`ApiError.server`	`E5002`	서버 5xx	통합 관리자 확인
`ApiError.notFound` · `.unprocessable`	`E5003`	대상 없음(404) · 페이로드 문제(422)	SDK·서버 버전 확인
`ApiError.forbidden`	`E5004`	다른 고객사 자원(403)	키 범위 확인
`ApiError.decoding`	`E5005`	응답 형태 불일치	메시지의 사유 확인

표의 이름은 Swift 기준입니다. Kotlin·Java 는 첫 글자가 대문자입니다(SdkError.NotInitialized, E3001 은 SdkError.BuildingNotSet). 측위 중 문제(E4001~~E4004), 공간 설정 문제(E3002~~E3009), 권한·Bluetooth(E2003 · E2004)는 던지지 않고 로그로만 남습니다 — onDebugLog 나 콘솔 로그 분석기에서 확인하세요.

모델

필드 이름은 세 플랫폼이 같습니다. 목록은 List<T>, 바이트는 ByteArray 입니다.

Coordinates

필드	타입	설명
`x` · `y`	`Double`	도면 로컬 미터
`z`	`Double`	높이 — 2D 측위면 0

Building · Floor

타입	필드	설명
`Building`	`id` · `name`	건물 ID · 이름
	`floorCount: Int?`	층 수 — 서버가 주지 않으면 비어 있음
`Floor`	`id` · `name`	층 ID · 이름
	`image`	도면 PNG — `floors()` 로 받으면 비어 있고 `floor()` 로 받으면 채워짐
	`hasPlan: Bool`	도면 등록 여부
	`originX` · `originY`	도면 원점 오프셋(미터)
	`widthM` · `heightM`	도면 실제 크기(미터)
	`minX` · `minY` · `maxX` · `maxY`	배치 범위 — 원점과 크기에서 계산

Locator · FloorLocators

타입	필드	설명
`Locator`	`address: Int`	UWB MAC 뒤 2바이트(예: `0x9DD7`)
	`x` · `y` · `z`	도면 로컬 미터
`FloorLocators`	`locators`	이 층에 설치된 로케이터
	`sessionId: Int?`	UWB 세션 — 층마다 다름. 비어 있으면 측위를 시작할 수 없음
	`positioningReady: Bool`	로케이터와 세션이 모두 있는가

Zone

필드	타입	설명
`id` · `name`	`String`	구역 ID · 이름 — 측위 엔진이 알려 주는 영역 이름과 맞추는 키
`polygon`	`Position` 목록	꼭짓점(순서대로, 지도 표시용) — `Position` 은 도면 로컬 미터(`x`, `y`)
`dwellSeconds`	`Int?`	체류 이벤트 기준(초) — 닿으면 방문당 한 번. 비어 있거나 0 이면 체류 이벤트 없음
`inDist` · `inCount` · `inCountInterval` · `outPeriod` · `priority` · `callInout`	—	판정은 측위 엔진이 자체 지오펜스로 하므로 더 이상 쓰이지 않습니다. 콘솔에서 바꿔도 판정에 영향이 없습니다

콘솔 구역은 지도 표시·구역 ID 매핑·서버 전송에만 쓰입니다(설정 방법). 측위 엔진이 알려 주는 영역 이름과 콘솔 구역 이름이 같아야 이벤트가 이어지며, 같은 이름이 없으면 E3009(WARN)가 한 번 남고 그 영역의 이벤트는 서버로 가지 않습니다.

Trigger

필드	타입	설명
`triggerId`	`String`	트리거 ID — 서버가 빼면 빈 문자열
`type`	`String`	`signage` · `coupon` · `tracking` · `merch` · `generic` — 서버가 빼면 `"generic"`
`payload`	`[String: String]?`	타입별 부가 정보

SDK 의 열거형(ConfigChange · StopReason · PermissionStatus · DeviceAvailability · LogLevel · 오류 코드)은 마이너 버전에서 값이 늘 수 있습니다. Kotlin when 에는 else 를 두세요.

커스텀 측위 provider

session.begin(provider) 에 직접 만든 측위 provider 를 넣을 수 있습니다. 보통은 쓸 일이 없습니다 — 인자 없는 begin() 이 내장 provider 를 씁니다. 필수는 delegate · start() · stop() 셋이고 나머지는 기본 구현이 있습니다.

interface PositioningProvider {
    var delegate: PositioningProviderDelegate?
    fun start()
    fun stop()
    // 선택 (기본 구현 있음)
    fun apply(config: PositioningConfig) {}   // 층 전환·해제·구역 새로고침 때 불림
    fun pause() {}                            // FloorSession.pause() 가 부른다
    fun resume() {}
    val isPaused: Boolean get() = false
}

delegate 로 좌표·구역 이벤트를 넘기면 세션 콜백(onPosition · onZoneEnter/Exit/Dwell · onFloorDetected · onStopped)이 내장 provider 와 같은 길로 옵니다. co.onecheck.ones1ght.android.positioning 패키지에 있습니다. 테스트용 provider 가 필요하면 이 인터페이스를 직접 구현하세요.

UwbPositioningProvider

0.0.5 부터. 설치·점검 앱이나 직접 그리는 지도처럼 엔진 상태(엔진 단계 · 탐지한 층 · 좌표 수 · 로그)를 직접 봐야 할 때만 앱이 만들어 session.begin(provider) 에 넣습니다. 넣어도 begin() 과 똑같이 다뤄집니다 — 같은 기기 확인, 구역 이벤트는 세션 콜백으로, 엔진 로그는 OneS1ght.onDebugLog 로 갑니다.

if (UwbPositioningProvider.isSupported(context)) {
    val provider = UwbPositioningProvider(context)
    provider.onFloorDetected = FloorDetectedListener { floorId -> /* 층 자동 선택 */ }
    OneS1ght.floorSession().begin(provider)
    provider.latestPositionFlow.collect { position -> /* 내 위치 그리기 */ }
}

if (UwbPositioningProvider.isSupported(context)) {
    UwbPositioningProvider provider = new UwbPositioningProvider(context);
    provider.setOnFloorDetected(floorId -> { /* 층 자동 선택 */ });
    provider.setOnChange(p -> { /* p.getLatestPosition() 으로 내 위치 그리기 */ });
    OneS1ght.floorSession().begin(provider, new Callback<Void>() {
        @Override public void onSuccess(Void result) { }
        @Override public void onError(Throwable error) { }
    });
}

API	설명
`UwbPositioningProvider(context)`	내장 provider 를 만듭니다. 어느 OS 에서든 던지지 않습니다 — 미지원 기기에서는 시작할 때 `E2002` 로 끝나므로 먼저 `isSupported` 로 거르세요
`UwbPositioningProvider.isSupported(context)`	Android 17(API 37) 이상이고 UWB 칩이 있는가. `initialize` 전에도 쓸 수 있습니다
`startDetection()`	엔진만 띄워 층부터 찾습니다. 층이 잡히면 `onFloorDetected` 로 알리고, 측위는 그 뒤 `session.begin(provider)` 가 켭니다. `initialize` 뒤에 부르세요(전이면 `E1007`)
`stopDetection()`	엔진까지 완전히 멈춥니다. 측위 중이었으면 측위도 끝납니다
`note(message)` · `note(level, message)`	앱 로그를 엔진 로그 스트림(`log` · `onLog`)에 합칩니다

상태는 게터와 StateFlow(…Flow) 둘 다로 읽습니다. Kotlin 은 …Flow 를 모으고, Java 는 게터와 setOnChange(…) 를 씁니다.

상태	타입	설명
`phase`	`PositioningPhase`	`IDLE` · `STARTING` · `SEARCHING`(층 탐색) · `TRACKING`(층 추적) · `STOPPING`
`isDetecting`	`Boolean`	엔진이 도는 중인가(탐색이든 추적이든)
`isRunning` · `isPaused`	`Boolean`	측위 가동 · 일시정지 여부
`latestPosition`	`Coordinates?`	마지막 좌표. 측위 전·일시정지 중·층을 놓친 뒤에는 비어 있음
`detectedFloorId`	`Long?`	엔진이 추적 중인 층 번호. 비어 있으면 탐색 중
`measurementCount`	`Int`	이번 가동에서 받은 좌표 수
`log`	`List<String>`	화면 로그 — 최근 200줄
`diagnostic`	`AnchorDiagnostic`	로케이터 단위 진단 — `registered` · `received` · `matched` · `missing` · `hasFix` · `canPosition` · `summary`

훅	설명
`onZoneEvent`	콘솔 구역으로 옮긴 진입·이탈·체류 — 서버 전송과 무관하게 즉시
`onLog`	엔진 로그
`onFloorDetected`	층 추적 시작(층 번호) / 층을 놓침(`null`)
`onEngineError`	엔진 원본 오류 번호·문장. 같은 사실은 SDK 에러 코드로도 남습니다
`onRawAreaEvent`	콘솔 구역으로 옮기기 전 원본 영역 이벤트(`floorId` · `areaName` · `"IN"`/`"OUT"` · `atMs`)
`onChange`	상태 중 무엇이든 바뀜 — Java 용

측위 엔진은 로케이터별 수신 상태를 알려 주지 않습니다. 그래서 좌표가 있으면 received · matched 가 등록된 로케이터 전부, 없으면 빈 목록이고 missing 은 항상 비어 있습니다 — 로케이터 한 대가 꺼졌는지는 이 값으로 가릴 수 없습니다.

바뀐 이름

Android 0.0.7 에서 iOS 와 이름을 맞췄습니다. 옛 이름은 deprecated 로 남아 경고만 내고 그대로 동작하며, Android Studio 의 Replace with … 가 새 이름으로 바꿔 줍니다.

옛 이름	새 이름
`permissions()`	`requestPermission()`
`getProfile()`	`fetchProfile()`
`putProfile()`	`replaceProfile()`
`send()`	`uploadPendingPositions()`
`empty()`	`discardPendingPositions()`
`ApiClient.DEFAULT_BASE_URL`	`OneS1ght.DEFAULT_BASE_URL`
`building(buildingId = …)`	`building(id = …)` — 인자 이름만

자세한 내용은 릴리스 노트를 참고하세요.

스레딩

suspend API 는 어느 코루틴에서 불러도 됩니다. identify · discardPendingPositions · pause · resume 은 메인 스레드에서 부르세요.
콜백과 Java Callback 결과는 모두 메인 스레드로 옵니다 — UI 를 바로 고쳐도 됩니다.

알아둘 제약

UWB 측위는 포그라운드 전용입니다. 앱이 백그라운드로 가면 측위를 멈추고 남은 좌표를 보낸 뒤, 돌아오면 다시 시작합니다. 플랫폼 제약이라 SDK 가 우회할 수 없습니다.

좌표 버퍼는 메모리에 있습니다. 앱이 강제 종료되면 아직 보내지 못한 좌표는 사라집니다(E5006).

실제 측위는 시뮬레이터·에뮬레이터에서 확인할 수 없습니다. UWB 를 지원하는 실기기에서 테스트하세요.

​초기화

​.initialize

​.requestPermission

​.setLanguage

​.onDebugLog

​.reset

​상태 조회

​.isInitialized

​.deviceAvailability

​.googleMapKey

​.sdkVersion

​프로필

​.createProfile

​.identify

​.fetchProfile

​.replaceProfile

​.deleteProfile

​공간 조회

​.buildings

​.floors

​.floor

​.zones

​.locators

​층 지정

​.setFloorMap

​.refreshZones

​측위 세션

​.floorSession

​.begin

​.end

​.pause · .resume

​.isRunning · .isPaused

​세션 이벤트

​.onPosition

​.onZoneEnter · .onZoneExit

​.onZoneDwell

​.onTriggers

​.onFloorDetected

​.onStopped

​.onConfigChanged

​데이터 전송

​.uploadPendingPositions

​.discardPendingPositions

​오류 처리

​오류 받기

​모델

​Coordinates

​Building · Floor

​Locator · FloorLocators

​Zone

​Trigger

​커스텀 측위 provider

​UwbPositioningProvider

​바뀐 이름

​스레딩

​알아둘 제약

초기화

.initialize

.requestPermission

.setLanguage

.onDebugLog

.reset

상태 조회

.isInitialized

.deviceAvailability

.googleMapKey

.sdkVersion

프로필

.createProfile

.identify

.fetchProfile

.replaceProfile

.deleteProfile

공간 조회

.buildings

.floors

.floor

.zones

.locators

층 지정

.setFloorMap

.refreshZones

측위 세션

.floorSession

.begin

.end

.pause · .resume

.isRunning · .isPaused

세션 이벤트

.onPosition

.onZoneEnter · .onZoneExit

.onZoneDwell

.onTriggers

.onFloorDetected

.onStopped

.onConfigChanged

데이터 전송

.uploadPendingPositions

.discardPendingPositions

오류 처리

오류 받기

모델

Coordinates

Building · Floor

Locator · FloorLocators

Zone

Trigger

커스텀 측위 provider

UwbPositioningProvider

바뀐 이름

스레딩

알아둘 제약