Android SDK - OneS1ght

Import

import co.onecheck.ones1ght.android.*           // OneS1ght · FloorSession · SdkError · listeners
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

import co.onecheck.ones1ght.android.*;          // OneS1ght · FloorSession · SdkError · Callback · listeners
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;

Initialization

.initialize

Initializes the positioning engine with your OneS1ght API key. Pass baseUrl only if you run your own server (default OneS1ght.DEFAULT_BASE_URL).

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

Requests the app permissions needed to use the positioning engine.

Result	Meaning
`AUTHORIZED`	Positioning available
`DENIED`	Permission denied
`UNSUPPORTED`	Device without positioning support

val status = OneS1ght.requestPermission(activity)

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

.setLanguage

Sets the language of SDK log messages.
ko: Korean, ja: Japanese, en: English, null: system language

OneS1ght.setLanguage("en")

OneS1ght.setLanguage("en");

.onDebugLog

Receives SDK logs.
level: log level, message: log message

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

.reset

Discards the session, stops positioning, and clears the stored key and building context. Call initialize again afterwards (until then, NotInitialized, E1001).

OneS1ght.reset()

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

State

.isInitialized

Returns whether initialization succeeded.

val ready = OneS1ght.isInitialized

boolean ready = OneS1ght.isInitialized();

.deviceAvailability

Tells whether the device supports positioning and, if not, why. Read it after initialize() — before that it is DEVICE_NOT_SUPPORTED (OS_VERSION_TOO_LOW below Android 17).

Value	Meaning
`AVAILABLE`	Positioning available
`OS_VERSION_TOO_LOW`	Below Android 17 (API 37)
`DEVICE_NOT_SUPPORTED`	Device without UWB

when (OneS1ght.deviceAvailability) {   // initialize() after
    DeviceAvailability.AVAILABLE            -> Unit
    DeviceAvailability.OS_VERSION_TOO_LOW   -> Unit
    DeviceAvailability.DEVICE_NOT_SUPPORTED -> Unit
    else                                    -> Unit
}

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

.googleMapKey

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

val mapKey = OneS1ght.googleMapKey   // String?

String mapKey = OneS1ght.getGoogleMapKey();

.SDK_VERSION

Returns the SDK version in use.

val version = OneS1ght.SDK_VERSION   // "0.0.9"

String version = OneS1ght.SDK_VERSION;

Profiles

.createProfile

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

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

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

OneS1ght.identify(profileId)

OneS1ght.identify(profileId);

.fetchProfile

Fetches the profile’s attributes.

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

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

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

Permanently deletes the profile.

OneS1ght.deleteProfile(profileId)

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

Space lookup

.buildings

Fetches every building that belongs to the tenant.

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

Fetches the floors of a building.

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

Fetches the details of the selected floor.

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

Fetches every zone on the selected floor.

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

Fetches the locators on the selected floor.

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

Setting the floor

.setFloorMap

Sets the floor used for zone events (optional). Coordinates arrive without it, but zone events and campaigns need it.

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

Fetches the latest zone data.

val zones = OneS1ght.refreshZones()

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

Positioning session

.floorSession

Returns the positioning session. It is a single app-wide instance not tied to a floor, and throws NotInitialized before initialize.

val session = OneS1ght.floorSession()

FloorSession session = OneS1ght.floorSession();

.begin

Starts positioning the user.

session.begin()

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

.end

Stops positioning the user.

session.end()

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

.pause · .resume

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

session.pause()
session.resume()

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

.isRunning · .isPaused

Returns whether positioning is running and whether it is paused.

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

Session events

.onPosition

Delivers the user’s coordinates in real time, at the rate the engine produces them; only server uploads are downsampled to the console setting (4 per second by default).

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

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

.onZoneEnter · .onZoneExit

Fires when the user enters or exits a zone.

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

Fires when the dwell time in a zone exceeds the threshold (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

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

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

.onFloorDetected

Called with the floor ID when the engine finds a floor from locator BLE signals, and with null when the floor is lost.

session.onFloorDetected = SessionFloorListener { floorId ->
    if (floorId == null) return@SessionFloorListener
    lifecycleScope.launch {
        val floor = OneS1ght.floor(buildingId, floorId)
        OneS1ght.setFloorMap(floor, buildingId)
    }
}

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

.onStopped

Fires when positioning stops.

Reason	Meaning
`ENDED`	`end()` · `reset` · key change
`ENGINE_FAILED`	The positioning engine failed to run

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

.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

session.onConfigChanged = ConfigChangeListener { change ->
    when (change) {
        is ConfigChange.ZonesChanged, is ConfigChange.ResyncNeeded -> lifecycleScope.launch { OneS1ght.refreshZones() }
        is ConfigChange.PlanChanged -> redrawFloor()
        else -> Unit
    }
}

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

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.

OneS1ght.uploadPendingPositions()

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

.discardPendingPositions

Discards buffered coordinates.

OneS1ght.discardPendingPositions()

OneS1ght.discardPendingPositions();

Error handling

Failures arrive as SdkError (SDK state) and ApiError (communication, co.onecheck.ones1ght.android.network.ApiError). See Error codes for details.

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

Models

Lists are List<T>, bytes are ByteArray.

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: ByteArray?`	Decoded floor plan PNG bytes — `null` in list results
	`hasPlan: Boolean`	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: Boolean`	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 an else branch in when.

Limitations

suspend APIs can be called from any coroutine. Call identify · discardPendingPositions · pause · resume on the main thread.
UWB positioning is foreground only. In the background positioning stops, the zone the user was in is treated as exited (onZoneExit), and the live stream is cut. On return positioning restarts and ResyncNeeded arrives.
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.

​Import

​Initialization

​.initialize

​.requestPermission

​.setLanguage

​.onDebugLog

​.reset

​State

​.isInitialized

​.deviceAvailability

​.googleMapKey

​.SDK_VERSION

​Profiles

​.createProfile

​.identify

​.fetchProfile

​.replaceProfile

​.deleteProfile

​Space lookup

​.buildings

​.floors

​.floor

​.zones

​.locators

​Setting the floor

​.setFloorMap

​.refreshZones

​Positioning session

​.floorSession

​.begin

​.end

​.pause · .resume

​.isRunning · .isPaused

​Session events

​.onPosition

​.onZoneEnter · .onZoneExit

​.onZoneDwell

​.onTriggers

​.onFloorDetected

​.onStopped

​.onConfigChanged

​Data upload

​.uploadPendingPositions

​.discardPendingPositions

​Error handling

​Models

​Coordinates

​Building · Floor

​Locator · FloorLocators

​Zone

​Trigger

​Limitations