System requirements
On devices that cannot receive positioning data, only SDK positioning stops working; the rest of your app keeps running.
Note that
initialize throws key and network errors, and session.begin() throws unsupported-device errors, so handle them with try/catch (onError in Java) as in the samples below.
Installing the SDK
1
Add the Maven Central repository to
settings.gradle(.kts).settings.gradle.kts
2
Add the OneS1ght SDK to your app module’s build file.
3
Check the JVM target version and the
BuildConfig option. JVM 1.8 or later is recommended.Android permissions
The permissions required for positioning are merged into your app automatically from the SDK manifest.
Runtime permissions are requested together with a single
requestPermission(activity) call. If they are already granted it returns immediately without a prompt, and it can be called before
initialize. If the user denies the request or does not answer within 30 seconds, the result is
DENIED. If the system no longer shows the prompt, guide the user to the Settings app.
Initializing the SDK
Runs the initialization needed to start the positioning engine.Profiles
Each user (account or device) is tracked as a profile.Profile IDs are unique and cannot be recovered once lost, so store them carefully.
Creating a profile
Creating a profile returns its profile ID. Attributes are used as segments in reports and metrics, and there are no restrictions on the key-value pairs.Store the returned ID in your app (or on your server) and link it with
identify before positioning on every launch.
Fetching a profile
Fetches the personalization attributes stored for a profile ID.Updating a profile
Personalization attributes are replaced as a whole. The previous values are deleted and cannot be restored.Deleting a profile
Deletes the profile’s personalization attributes. Deleted attributes cannot be restored.Selecting a building and floor
To receive position coordinates, select the building and floor where the locators are installed.Selecting from BLE
When the SDK’s positioning engine finds a floor from locator BLE signals, the floor ID arrives inonFloorDetected. null arrives when the floor is lost.
Selecting manually
Set the building and floor yourself when the user picks the floor, or when you want to draw the map before positioning starts.Receiving live positions
Get a positioning session withfloorSession(), start it with begin() and stop it with end(). Positions arrive in
onPosition as coordinates in meters, at the rate the engine produces them. Uploads to the server are downsampled to the console setting (4 per second by default).
Call
Calling
begin() after permissions are granted. Without permissions it starts without throwing, but no coordinates arrive and E2003 is logged. Calling
begin() again while positioning is running is ignored (WARN log), so once the user grants permissions, call end() and then begin() again.Zone events
Receive enter, exit and dwell events for the zones drawn in the console’s Space Management. Detection happens on the device, so events arrive immediately.Campaigns attached to a zone (coupons, signage, etc.) are matched by the server and delivered through
onTriggers.
Refreshing zone data
onConfigChanged is called when zone data changes in the console. If several arrive in a row, batch them for about a second and call refreshZones() once.
Displaying the floor plan
You can display the floor plan the locators are installed on, together with the user’s current position.If no floor plan is set, the background is shown as a grid.
Other options
Controlling data upload
Coordinates are uploaded automatically when 300 have been buffered, or 60 seconds after the last upload. If the app is force-quit, buffered coordinates are discarded.Resetting the session
Discards the session, stops positioning, and clears the stored SDK key and building context (the building fromsetFloorMap). It does not create a new session. After that, most APIs throw
SdkError.NotInitialized (E1001), so call initialize again. Use it to switch keys at runtime. The profile linked with
identify is kept.
Handling positioning shutdown
When the positioning engine shuts down,onStopped fires and you can bring the app back to a state where positioning can start again.
Checking device support
deviceAvailability can be read right away without a network (internet) connection. However, checking the chip needs the app
Context, so read it after initialize() (or requestPermission(activity)). If you read it earlier, even Android 17+ devices get
DEVICE_NOT_SUPPORTED and a WARN is logged to onDebugLog (below Android 17 it is always OS_VERSION_TOO_LOW).
Appendix
Using the SDK from Java
Every asynchronous API comes in two forms with the same name.- APIs with no return value take a
Callback<Void>. - Event listeners (
ZoneListener,PositionListener, etc.) arefun interfaces, so register them directly with Java lambdas —session.setOnZoneEnter(zone -> …). - Read state through getters —
OneS1ght.isInitialized(),OneS1ght.getDeviceAvailability(),session.isRunning(). - Register callback properties through setters —
session.setOnStopped(…),OneS1ght.setOnDebugLog(…). - Java apps only need
compileOptionsset to 1.8 or later; no Kotlin configuration is required.
Debug logs
To see debug logs, register the listener right before callinginitialize. View them in Android Studio’s Logcat (filter
tag:OneS1ght) or with adb.
adb
Troubleshooting
Error codes
Explains the errors you may run into during development.