Skip to main content

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.
Do not put sensitive data such as names, phone numbers or member IDs in profile attributes.
Use only non-identifying values such as an age band ("20s").

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 in onFloorDetected.
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 with floorSession(), 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 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 from setFloorMap). 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.) are fun 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 compileOptions set to 1.8 or later; no Kotlin configuration is required.

Debug logs

To see debug logs, register the listener right before calling initialize.
View them in Android Studio’s Logcat (filter tag:OneS1ght) or with adb.
Reading with adb

Troubleshooting

Error codes

Explains the errors you may run into during development.