Troubleshooting Mobile SDK issues¶

The purpose of this document is help you troubleshoot the issues you have with Mobile SDK, to avoid having to contact our support unecessarily.

During the standard offering of Pointr SDK Integration Program, each client is alloted 2 Developer Hours from Pointr, per platform, to help with integration, and one further hour later for polishing. These 3 hours can be used for debugging, troubleshooting, questions and answers and so on, but are limited so Pointr’s clients don’t unfairly cause problems for other clients by using all resources.

As such we strongly recommend you to use this document, and read carefully the rest of the documentation, so you can have a wiser use of the resources Pointr provides in the standard offering.

If you have any questions with no solution on this document or elsewhere in the documentation, please let us know so we can update the documentation.

Table of Contents¶

• No blue dot visible on the map
• Position Coordinates are -99999
• Map did not load in Map Widget
• Bluedot jumps around erratically from one position to another
• AR button not visible in the Pointr Map widget
• Cannot download Pointr SDK from artifactory / cocoapods
• Error Messages related to Licence Validation
• Wrong license key or environment
• Cannot Start Pointr SDK successfully
• Error: Pointr Library has not started. Cannot access “Pointr function/manager”
• Xcode showing build errors
• App crashes on Pointr start
• MapBox module/pod not found
• Program crash when running on Mac
• Bluetooth stack corrupted or failed
• Bluedot failure after multiple reinstalls
• Geofencing

No blue dot visible on the map¶

After integrating the Pointr Mobile SDK successfully, application is not able to receive valid position updates from Position Manager, due to which there is no bluedot visible in the application UI.

Solutions¶

Location Permissions¶

Make sure you have granted Location permissions in the app that is using the Pointr Mobile SDK. There is more information on page Operating System Permissions

Bluetooth Permissions¶

Make sure you have granted Bluetooth permissions in the app that is using the Pointr Mobile SDK.

On iOS devices, bluetooth needs to be enabled in 2 locations for the Pointr SDK to work properly -

Settings → Bluetooth → Bluetooth toggle needs to be switched on.

Control Centre - This is accessed via a swipe down from the top right corner of an iOS device. It is where we enable/disable WiFi, Mobile Data etc.

Beacon Coverage¶

For indoor positioning, it is essential to have at least one beacon around the location of the user to acquire the bluetooth. This could be an actually installed beacon or even a beacon being simulated using a beacon simulator app. For more information on simulating position outside of site, check the tutorial.

Level Change¶

In Pointr Demo apps, there is an option to control the Map View Mode, which has Location Tracking and No Tracking Mode. When the map mode is No tracking the user has the ability to browse around the map, and the camera will NOT track the blue dot location. So, if the user physically changes level, map level will stay at the browsed level. If the mode is Location Tracking, the map camera will follow the user blue dot. So the map level will change when the user physically changes level. Check this tutorial for more information on Map Modes.

Position Coordinates are -99999¶

This is the “Invalid Position” in Pointr scope. When lat/lon cannot be calculated, it gives invalid position.

This can also happens because there are errors in the content stored in Pointr Cloud, or Pointr Cloud instance is using the wrong version of the API.

Map did not load in Map Widget¶

Displaying the Pointr maps uses the map widget in Android and iOS. Not implementing it correctly on the v6 SDK can cause the maps fail to load/display. The Getting Started guide teaches how to display a map.

Bluedot jumps around erratically from one position to another¶

We do not recommend using another Location provider like Apple Maps along with Pointr in the same application as this leads to unexpected and undesired behavior. Pointr uses its own algorithm which is highly accurate for indoor positioning, using another makes the bluedot “teleport” between the Pointr’s calculated position and the other position.

AR button not visible in the Pointr Map widget¶

The flag used to enable AR in the Map Widget needs to be set to true in the Map Widget Configuration. AR is enabled in the default Map Widget configuration. Please check the tutorial about map widgets for more information on this subject.

Cannot download Pointr SDK from artifactory / cocoapods¶

The Pointr is distributed on Android and iOS using Artifactory and Cocoapods. There is a unique token/pass provided which authenticates the download when requested. Check the Getting Started guide for the appropriate OS:

• Android Guide
• iOS Guide

Error Messages related to Licence Validation¶

The PointrContent.zip doesn’t work if it was modified either its contents or filename as it is digitally bound by a signature. It should be placed in the correct location in the application for Pointr Mobile SDK to work properly.

Downloading PointrContent.zip¶

While you are integrating the Pointr SDK, you also need PointrContent.zip to be added. To do so, you need to download it.

After downloading this .zip, you can put it inside the app project. Whenever a user starts the app, all the content that is necessary for the application operation will be downloaded from Pointr Cloud, so there is no need to keep updating too frequently this file, neither there is the need to ship your application with everything enabled.

Installing PointrContent.zip¶

Remember that the suffix signifies the environment the content is connected to. The SDK will check the zip with the associated environment given to the Pointr.with method as an argument. Then place the content depending on the Operating System: * Android: Put the PointrContent zip under the “assets” directory of their project. * iOS: They can put PointrContent zip anywhere inside the Xcode project, as long as it is included in the application’s bundle.

Wrong license key or environment¶

The Pointr Mobile SDK needs to be initialized using a license key that is used to validate and register against a specific Pointr Cloud instance. Each Pointr Cloud instance has its own licence key. A wrong license key would result in a failed validation and the SDK would not start. The correct environment (PROD, QA, Dev, etc…) is also needed to be chosen in the Pointr parameters while starting it.

These license keys are created when the environments are set up. You can ask your designated project manager for this information once the environments are set up.

The license key map on the SDK guides and examples are there to facilitate switching between environments when developing with the SDK, which eliminates fetching the license key each time a different environment needs to be run. However, it is not necessary for the functionality of the SDK. It will be enough to just provide the license key and PointrContent.zip for the environment you want to build with.

Cannot Start Pointr SDK successfully¶

If the SDK still doesn’t start with PointrContent.zip and license key being correct, the correct environment, and the location of the PointrContent.zip file is correct, then the most likely reason it is still not working if you are on Android is the lack of a valid “cacert.pem” file, that is needed for the SSL handshake with Pointr Cloud. Other possible reason is network issues.

Error: Pointr Library has not started. Cannot access “Pointr function/manager”¶

To start using Pointr methods, it is mandatory that the SDK is in the running state. This state is achieved only after calling pointr.start() method, and SDK is able to start successfully.

This can be checked using SDK States, either directly by checking the state field of Pointr instance, or observing the state changes via adding a PointrListener to Pointr instance.

More information on SDK states.

Xcode showing build errors¶

Make sure you setup the project with all the necessary linked frameworks and linker flags. Please check the Getting Started guide.

App crashes on Pointr start¶

If the application crashed on iOS and there is an error message about missing plist Keys, then please make sure all the privacy descriptions are setup correctly, there is an explanation on how to do that on the Getting Started guide.

MapBox (Maplibre) module/pod not found¶

The Pointr Mobile SDK uses 3d maps for which Maplibre v5.12.1 (named Mapbox.xcframework) is needed as an additional library. If Pointr is used using Cocoapods, then Maplibre would be automatically served by Pointr. If the .xcframework is used for manually adding Pointr into a project, Mapbox needs to be either added manually or through Cocoapods for the v7 SDK to work properly.

Program crash when running on Mac¶

Pointr uses OpenGL to render its maps, Mac has poor compatibility with OpenGL and might crash, specially when “re-opening” the map.

Bluetooth stack corrupted or failed¶

Sometimes the Bluetooth stack of the device, usually on Android, fails in some manner or gets corrupted, it is neccessary to powercycle it to fix it.

Pointr Android Mobile SDK periodically checks the health of the bluetooth stack on the device by running two kinds of tests: scanning and transmitting. If the Bluetooth stack is in a bad state, the application cannot communicate with the BLE beacons and therefore location data cannot be retrieved by the app. Our SDK looks for specific failure codes from these tests to determine if the bluetooth stack is in a bad state and if so, SDK can optionally cycle power to bluetooth to try and fix the problem. This is known to work well on some Android devices. SDK behavior can be defined by setting the configuration value.

positionManagerConfiguration_shouldRestartBleWhenCorrupted on Pointr Cloud/Configure/Configuration/Global. If nothing is set, the default value for the configuration is false.

• If positionManagerConfiguration_shouldRestartBleWhenCorrupted is set to true, when the bluetooth stack is in a bad state, we power cycle bluetooth to recover. We turn bluetooth off and as soon as it goes to off state, we turn it back on to recover the failure.

• If positionManagerConfiguration_shouldRestartBleWhenCorrupted is set to false on startup, the SDK does not intervene. Clients can handle bluetooth corruptions (take an action, show a message to the user etc.) via registering a BroadcastReceiver to detect any changes on bluetooth state. An example code snippet can be found below to register a BluetoothStateChangedReceiver listener.

private fun createBluetoothStateChecker() {
    BluetoothStateChangeReceiver.getInstance().addListener(this, bluetoothStateChangeReceiverListener)
}

private val bluetoothStateChangeReceiverListener = object : BluetoothStateChangeReceiver.Listener {
    override fun onBluetoothStateChanged(bluetoothState: Int) {}
    override fun onBluetoothCorrupted() {
        runOnUiThread {
            AlertDialog.Builder(this@YourActivity)
                .setTitle("Bluetooth corrupted.")
                .setMessage("Positioning may not work properly. Consider restarting bluetooth!")
                .setPositiveButton("OK") { dialog, id -> dialog.cancel() }
                .show()
        }
    }
    override fun onBluetoothRestored() {}
}

Bluedot failure after multiple reinstalls¶

Bluedot is not working properly after the demo app, or an app made with Pointr was removed and installed again repeteadly, specially if using side-loading for testing purposes, while it was working at first.

The reason this happens is because sometimes the operating system gets confused about permissions with all the repeated installations, specially when side-loading is used instead of installs coming from the official store. The issue could be related both to bluetooth, and location permissions.

Solution¶

Uninstall the application completely, turn off the device completely, then turn it on again and re-install, and if needed an extra check of the permission configurations could help.

Geofencing¶

If you are having problems with Geofencing, this guide will explain how to troubleshoot it.

Are you using Pointr GeofenceManager?¶

While implementing your geofence solution, are you using the GeofenceManager provided by the Pointr SDK ? Or have you implemented another Geofencing solution? If you are using another Geofencing solution using the positions from Pointr SDK, please verify that you can see the bluedot in the correct locations, then check your Geofence Implementation. If you are using the Pointr Geofence manager, make sure that you are adding the create GeofenceManager.Listener implementation to GeofenceManager after Pointr state has become RUNNING. If you do it before, the listener will not be added.

Have you added the geofences through your Pointr Cloud instance?¶

You need to add the Geofence regions through the MapDesigner tab from your Pointr Cloud instance for Indoor Geofences. For outdoor geofences, please use GeofenceDesigner tab to add the Geofence regions. After saving your changes, please remember to publish using the publish button on top left of the screen for the changes to be reflected in the app. The SDK takes 15 minutes maximum to update the data from Pointr Cloud. However, on a fresh installation the changes are reflected immediately. So, in order to make sure the latest content you have added to Pointr Cloud is fetched by the SDK, it is safest to do a fresh install.

Are you seeing the bluedot in the correct place while conducting your tests? (i.e. inside the geofence regions)¶

Please make sure you can see the bluedot in the correct places while conducting the tests. For example, if you have a geofence in a meeting room, are you experiencing problems with the Geofence Enter triggers whilst the bluedot is actually shown inside the meeting room ? If yes, please check the guide for our geofences here: ​​https://docs.pointr.tech/docs/6.x/Developer%20Portal/Pointr%20Mobile%20SDK/Guides/Geofence%20Triggers/ to make sure you are not experiencing an expected scenario. If you are not able to see bluedot at the correct location or at all, please check again that you have given all the required permissions. For this,

Are you using the device in foreground or background while conducting your tests¶

Both Android and iOS Operating Systems allows apps to use certain features/services of the device according to user permissions. The most important one is the LocationPermission. There are two allowance options for this permission, to allow while the app is in use (foreground) and to allow always (foreground and background). If the tests are being conducted on the background, and appropriate permissions (“Always Allow”) are not set for the app, Pointr SDK will not be able to calculate positions, hence Pointr Geofencing will not function properly. Furthermore, even if you have given the correct permissions for background, Pointr SDK works significantly less accurately when the device is not kept at the user’s hand while walking. For example, if you are conducting the tests with the device in your pocket, this will have an adverse effect on the accuracy, hence the geofencing may work poorly.

If you are keeping the application that has integrated the Pointr SDK in the foreground, and still experiencing issues, please note that the best use for Pointr SDK positioning is to hold the device in your hand while walking.

Provide logs of the experience¶

If you have checked each of the steps above, and are continuing having problems with the Pointr Geofencing, please provide your project manager with the following logs that are recorded while conducting your tests. These logs should include;

• Pointr position + timestamp —> This would come directly from the PositionManager.Listener onPositionManagerCalculatedLocation callback.
• Geofence trigger events + timestamp —-> This would come directly from Geofence
• In order to generate the logs, you can either conduct the tests connected to a laptop and see the logs, or do realtime logging with the logcat application and get the logs from there.

Along with these logs, please provide the real times where you entered/exited the geofence with its name.