메인 콘텐츠로 건너뛰기

패키지 선언

초기화

.initialize

OneS1ght API 키로 측위엔진을 초기화합니다. 자체 서버를 구축한 경우에만 baseUrl 을 넘깁니다(기본값 OneS1ght.DEFAULT_BASE_URL).

.requestPermission

측위엔진 사용을 위한 앱 권한을 요청합니다.

.setLanguage

SDK 로그 문구 언어를 설정합니다.
ko : 한국어, ja : 일본어, en : 영어, null : 시스템 설정 언어

.onDebugLog

SDK 로그를 수신합니다.
level : 로그 레벨, message : 로그 메세지

.reset

세션을 버리고 측위를 멈추며, 저장된 키와 건물 정보를 지웁니다. 이후 initialize 를 다시 불러야 합니다(그 전엔 NotInitialized, E1001).

상태 조회

.isInitialized

초기화 성공 확인 여부를 반환합니다.

.deviceAvailability

측위 가능 기기를 판별하고 미지원시 사유를 반환합니다. initialize() 뒤에 읽습니다 — 그 전엔 DEVICE_NOT_SUPPORTED(Android 17 미만은 OS_VERSION_TOO_LOW)입니다.

.googleMapKey

도면을 표시할 Google Maps API 키를 반환합니다.

.SDK_VERSION

사용중인 SDK 버전을 반환합니다.

프로필

.createProfile

새로운 개인화 프로필을 생성합니다. 성공적으로 생성하면 고유 프로필 ID를 반환합니다.

.identify

수집할 측위 데이터를 묶을 프로필을 연결합니다. 연결 해제시 null으로 설정하세요.

.fetchProfile

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

.replaceProfile

프로필 속성을 교체하며 이전 데이터는 삭제됩니다.

.deleteProfile

프로필 정보를 영구 삭제합니다.

공간 조회

.buildings

테넌트와 연관된 모든 건물 목록을 조회합니다.

.floors

건물의 층 목록을 조회합니다.

.floor

선택한 층의 상세 정보를 조회합니다.

.zones

선택한 층의 모든 구역을 조회합니다.

.locators

선택한 층의 로케이터 정보를 조회합니다.

층 지정

.setFloorMap

구역 이벤트에 쓸 층을 지정합니다(선택). 지정하지 않아도 좌표는 나오지만, 구역 이벤트 · 시책을 받으려면 필요합니다.

.refreshZones

최신화된 구역 정보를 조회합니다.

측위 세션

.floorSession

측위 세션을 반환합니다. 층과 무관한 앱 전체 단일 인스턴스이며, initialize 전에는 NotInitialized 를 던집니다.

.begin

사용자 측위를 시작합니다.

.end

사용자 측위를 종료합니다.

.pause · .resume

사용자 측위를 중지, 재개합니다. 종료와 달리 SDK 내 측위 엔진은 종료하지 않습니다.

.isRunning · .isPaused

측위 상태여부와 중지여부를 반환합니다.

세션 이벤트

.onPosition

실시간으로 사용자 좌표를 전달합니다. 엔진이 내는 속도 그대로 오며, 서버 전송만 콘솔 설정값(기본 초당 4회)으로 줄입니다.

.onZoneEnter · .onZoneExit

구역 진입, 이탈시 이벤트가 동작합니다.

.onZoneDwell

특정 구역의 체류 시간이 초과할 경우(dwellSeconds 기준) 이벤트가 발생합니다.

.onTriggers

공간 내 이벤트(또는 시책) 동작시 이벤트가 발생합니다.

.onFloorDetected

엔진이 로케이터 BLE 신호로 층을 찾으면 층 ID 로, 층을 잃으면 null 로 호출됩니다.

.onStopped

사용자 측위가 중지된 경우 이벤트가 발생합니다.

.onConfigChanged

콘솔 페이지에서 설정이 변경되었을 경우 이벤트가 발생합니다.

데이터 전송

좌표는 300건 또는 60초마다, 그리고 백그라운드 진입과 end() 때 자동 전송됩니다.

.uploadPendingPositions

쌓인 좌표 즉시 전송.

.discardPendingPositions

쌓인 좌표 폐기.

오류 처리

실패는 SdkError(SDK 상태) 와 ApiError(통신, co.onecheck.ones1ght.android.network.ApiError) 를 반환하며, 자세한 내용은 에러 코드를 참고하세요.

모델

목록은 List<T>, 바이트는 ByteArray 입니다.

Coordinates

Building · Floor

Locator · FloorLocators

Zone

Trigger

열거형(ConfigChange · StopReason · PermissionStatus · DeviceAvailability · LogLevel)은 마이너 버전에서 값이 늘 수 있습니다 — when 에 else 를 둡니다.

제약

  • suspend API 는 어느 코루틴에서든 호출 가능. identify · discardPendingPositions · pause · resume 은 메인 스레드에서 사용합니다.
  • UWB 측위는 포그라운드 전용입니다. 백그라운드로 가면 측위가 멈추고, 들어가 있던 구역은 이탈(onZoneExit)로 처리되며 실시간 수신이 끊깁니다. 돌아오면 측위가 다시 시작되고 ResyncNeeded 가 옵니다.
  • 좌표 버퍼는 앱상 메모리에 임시 저장되며 강제 종료 시 미전송 좌표는 사라집니다.
  • 에뮬레이터에서는 측위할 수 없습니다.