Backspin Android SDK

When dealing with large amounts of data it is necessary to organize them in chunks so that only the currently necessary parts are loaded. Therefore the data is divided in scopes. For example, if the application you write is used for multiple shopping centers, every shopping center would be its own scope. When you have initialized the SDK correctly you have already chosen a certain scope (a root venue) which is now available locally. To change the scope simply call the BackspinSdk.Data.load() method with the new root venue. If you want to refresh the current scope’s data use the BackspinSdk.Data.reload() method. You can force loading by setting the force parameter to true.

After loading the right root venue you can start to obtain data belonging to it.

In this manner all scope bound Backspin entity types can be obtained: Beacon, Venue, VenueOffer, VenueCategory, Level and more.

The account bound types are discussed in the next chapter.

To save traffic and performance the SDK allows you to include only specific types you are interested in. You can do this with the help of the ConnectionConfig. Let’s say you want to receive beacon data and the navigation graph only.

You can also exclude specific properties from the incoming data. So if you want all root scope data but the venues should not have their VenueLocation information loaded you can use the excludePropertiesFromVenues() method.

Additionally you can use the overload of the include…​(propertiesToExclude) method to specify that you only want these objects but without a specific property. Therefore the following example requests only the levels from the backend but without their level plans.

Sometimes it makes sense to load or refresh only a specific model type. Especially when you work with includes or excludes. The following snippet requests all levels of the current root venue from the backend and puts the data into the local database.

Furthermore you can pass a RootVenue object as the first parameter if you want to load the data of a specific root venue.

Data like Venue, VenueOffer, VenueCategory or LevelPlan provide methods to build a URL which can be used to request the corresponding pictures from the Backspin backend. You can request JPG or PNG encoded images and logos in a specific size.

The Backspin SDK does not come with a build-in image loader. Instead you can choose whatever library you like. For example Glide or Picasso are a good choice. For most of the image loading libraries it will look similar to this:

To receive beacon scan results periodically you just have to call the start() method of the Scan module.

Similarly you have to call the stop() method to finish the beacon scan.

As the scanning for beacons is a very battery-intensive operation. You should think about stopping the process whenever you don’t need it. But be aware that calling stop() means that the dependent modules will also receive no scan results anymore.

To get updates of the scan process you can simply add a ScanUpdateListener. Whenever the Scan module is started you will receive beacon scan results periodically.

Note that adding a listener is only necessary if the scan results are of relevance to you - modules like Position or Proximity register their own ScanUpdateListener.

There are two different scan frequencies in the SDK. If ScanFrequeny is set to ScanFrequency.HIGH, the system scans for beacons continuously and the ScanUpdateListener is called every second. ScanFrequency.LOW represents a battery saving mode which scans only in an configurable interval (LowFrequencyScanInterval). ScanFrequency.HIGH is used by default. You can change the frequency at any time by calling:

In many use cases it makes sense to do high frequent scanning when the app is in the foreground and switch to low frequency mode when the app goes to the background. You can use ScanFrequency.AUTO to achieve this behavior. In order for the SDK to be able to monitor your app’s activities you need to add the following line to your custom Application class. This will also set the scan frequency to ScanFrequency.AUTO

There are several settings to adjust the beacon scanning for your specific environment.

The SDK also supports transmitting as a beacon. A device must have Android 5.0+, a Bluetooth LE chipset that supports peripheral mode, and a compatible hardware driver from the device manufacturer.

Use the following code snippet to check if your device is able to transmit as a beacon:

If this call returns true you are ready to use the startAdvertising method. Use any valid UUID, major and minor ID you want:

If advertising is not needed anymore you can simply call BackspinSdk.Scan.stopAdvertising().

Another feature of the SDK is the BLE scanning for beacon battery stats. This feature is only supported in Android SDK version 21 or higher. To save battery this feature is disabled as default. To enable the beacon battery scanning just set the config as follows:

If the beacon battery scanning is enabled it starts and stops together with the normal scanning for beacons. The default scan interval is 10 Minutes and the scanning duration is 6 Seconds. To change the interval and duration just change set the beacon battery scan interval or duration in millis as follows:

After the scan interval is reached the scanned beacon battery stats will be uploaded to the server. If the upload is successful the local stored stats will be deleted and a new scan will start for the duration that is set in the config. This process repeats till the beacon scanning stops. If the upload was not successful it will automatically retry when the next interval is reached.

To start the SDK’s position calculation call the start() method of the Position module.

Similarly you have to call the stop() method to end the calculation.

To receive the latest position periodically you have to add a PositionUpdateListener.

In many use cases it makes sense to snap the received position to the navigation graph before displaying it on a map. Look at Path Snapping for details.

There are several settings to adjust the position calculation for your specific environment. In many use cases the predefined defaults already provide a reasonable result.

The first step to perform a navigation is to create an instance of NavigationTask using NavigationTask.Builder. When building the task it is required to add at least one destination.

In addition to addDestination(latLng, floor) you can also use addDestination(venue) or addDestination(venueLocation). If a venue location has multiple entrances the most convenient one will be chosen automatically.

It is possible to add multiple destinations to a single NavigationTask. By setting forceSequence() the SDK will respect the order in which the destinations were added. Otherwise all destinations get sorted by their line of sight distance to the start point.

In order to get notified when one of the destination is reached, add a DestinationReachedListener when building the NavigationTask.

Use setDestinationReachedDistance(meters) to adjust the distance at which the SDK sees a destination as reached.

There is also an NavigationFinishedListener which gets called when the user reaches the final destination.

When the NavigationTask receives a position update the position gets snapped to the navigation route. Set the PositionSnappedListener to get a callback every time a snapped position is calculated. In most use cases, it makes sense to only display the snapped position on the map while a navigation is running.

If information about barrier freedom is included in the navigation graph data from the backend, you can use barrierFree() to build a NavigationTask that uses only barrier free paths.

Once the NavigationTask is built, you can start calculating navigation routes. This can be achieved by calling task.calculate(startLocation, listener). A NavigationRoute with the given start location will then be calculated in a background thread.

The resulting NavigationRoute contains a list of navigation steps that describe the found route.

Use getWaypoints() to retrieve a list of IndoorLocation objects that can be connected by a polyline to draw the calculated path on a map.

Use getTotalLength() to get the total path length in meters and getEstimatedTravelTimeMillis() to return the estimated time left in milliseconds.

A recommended workflow for the navigation task is:

To give the user accurate navigation instructions, there is a NavigationDirection class. You can obtain it by calling route.getNextDirection(). It contains information about the next turn. The turn type (e.g. left) is stored as a String constant; they are static constants within the NavigationDirection class.

It is also possible to get a list of all directions to reach the target by calling route.getDirections(). If you only want a specific amount of directions you can use the route.getNextDirections(amount) method.

If you want to snap an IndoorLocation to the navigation graph without the help of a NavigationTask, you can do this by calling the following method:

Instead of configuring every NavigationTask individually it is also possible to set the defaults for all NavigationTask instances by using the NavigationConfig.

To receive the notification callbacks while the module is started you have to add an NotificationListener.

The Notification class has the following properties:

The callback also gives you a NotificationTrigger object which contains information about the beacon or zone which is responsible for the notification. Use trigger.getProximityEvent().getBeacon() if you are interested in the beacon which triggered the notification or trigger.getZoneEvent().getZone() for the corresponding zone.

By creating a ProximityWatcher you can declare specific events that should trigger actions when the device moves to a certain distance to a specified beacon.

The ProximityEvent object gives you the necessary details about the beacons of your interest you passed earlier. Calling getBeacon() returns the affected beacon, getDistance() gives you the range (immediate, near, far) and getType() tells you if you leave or enter this range.

To connect the created ProximityWatcher to the current scanning of beacons you simply have to call its start() method. After that the corresponding OnProximityEventListener inside the ProximityWatcher called.

If you no longer need the information about the beacons you were interested in you should call it’s stop() method.

To specify the zones you are interested in and what should be done you need to create a ZoneWatcher object.

The ZoneEvent instance gives you the necessary details about the zones of your interest you passed earlier. Calling getZone() returns the affected zone and getType() tells you if you leave/enter it or if you are inside or outside this zone.

To connect the created ZoneWatcher to the SDK’s position calculation you simply have to call its start() method. After that the corresponding OnZoneEventListener gets called for each position update.

If you no longer need the zone events you should call the stop() method.

The altitude sensor uses the device’s pressure sensor (if available) to measure the ambient air pressure and deliver the relative change in height. To get absolute height one needs the base pressure on sea level which differs with weather and place. Since the pressure difference changes predictably it is possible to use a simple formula to deliver altitude changes in meters.
With the relative altitude change floor changes can be estimated by dividing the relative altitude with the floor height. The floor height can be set by the Altitude Sensor user.
Finally you can ask whether a floor change is possible by calling isFloorChangePossible(). This looks at the pressure history to determine if there has been a change large enough. That feature is used when activating UseSensorFloorDetection in PositionConfig.

The movement sensor is used to determine if the device’s user is currently walking or not. In recent Android versions there is a step sensor available but our own implementation has two advantages: First, each device manufacturer implements the step sensor on their own. Our tests showed that these implementations react differently (in terms of sensitivity and accuracy) which leads to unexpected behaviors on differing devices. Second, the step detectors were implemented with a health tracking use case in mind. They act rather unsensitive to small movements. Backspin’s movement sensor is made to determine if a movement, that has been registered by the bluetooth positioning, is possible. In this use case it is favorable that the sensor reacts rather earlier than later.

The orientation sensor relies either solely on the accelerometer and the magnetic compass or uses the gyroscope as well if it is available. The values returned are given as euler angles. There is also a smoothed yaw value which is very good for applications using a map that want to display the user’s orientation.

There are two ways of obtaining sensor data: Reading them whenever you need the most recently one or getting notified when new data is available. Let’s say you want to read user movement and get notified for orientation changes.

After finishing using the sensors simply unregister them. You do not have to worry about other observers: The sensor only stops working when no one is observing or reading them.

With BackspinSdk.Sensor.getConfig you can obtain the SensorConfig object to adjust certain parameters. The following table should help you doing so:

What to do if…​

The SDK offers a simple API to create and send events.

You can also adjust several settings and add additional content via a custom payload which is simply a collection of key-value-pairs.

With the help of the AnalyticsConfig you can define which types of events should be sent or not. Let’s say you want to enable analytics.

To disable them again you simply have to call:

If you want to enable or disable specific event types only, you can do that as well. For example, if analytics is enabled, the SDK already enqueues a new event of type AnalyticsEvent.TYPE_LOCATION_UPDATE on every position update. To disable it, simply call:

All enqueued events will be sent to the server after a certain time. By default this time is set to 20 minutes and it can be adjusted with the following method:

If you have enabled the module analytics the SDK automatically enqueues to following default event types.

If you want continuous updates about the status of your assets you can use the AssetWatcher class. Use the addAsset method to specify which assets should be observed. There is also a removeAsset method that can be called on the watcher if the asset is no longer of interest.

If you don’t add any assets the system will observe all of the users assets per default.

Calling the watchers start() method will start the actual observation process. Use the stop method if you are not interested in these updates anymore.

You can set an AssetPositionUpdateListener and an AssetAlertListener. The first one gets called whenever the position of an observed asset changes and the second whenever an asset enters or leaves a specific zone.

In addition there is a ConnectionListener that receives updates on the connection of the watcher to the backend.

A complete code example would look like this:

Subscriptions establish a two way connection to the Backspin backend to transfer the data. If you are interested in connection state changes on that underlying connection you can register for this event and see if the connection is active or not. The EventScope parameter is ignored for this event type. You should use subscribe overload which does not include the EventScope as its parameter and pass on the appropriate event type as depicted below. Upon successful connection establishment you should expect one instance of this event.

It provides the positioning information on a subject being tracked. This event could be categorised into the following subcategories with respect to the availability of the position of the subject, which could be an asset or another user.

Upon first subscription attempt, one of following three possible scenarios is expected.

In the reverse scenario, while receiving the the TRACKING_STATE_NOT_AVAILABLE events for the subscribed subject(s) if the permission to receive the positioning information is granted, application users would start receiving the TRACKING_STATE_ACTIVE events for the subject(s).

In case of any disruption in the WebSocket connectivity while consuming the service the events would stop coming in. Upon reconnection users should receive an incoming ConnectionStateEvent followed by one of the three possible scenarios described in the case of first subscription attempt as applicable.

This event contains the following general information:

The code snippet above depicts the basic use of Subscriptions API to get position updates for a subject. In this specific example, we are interested in position updates about a subject having the id 12345 and this represents our present scope. However, you could also use the EventScopes.all convenience method to receive the position updates for all of your visible subjects.