tps-location-sdk-android

TPS Location SDK (Android)

Platform

Prerequisites

Supported on all Android versions starting with 2.3.x (Gingerbread).

Contact support.tps@qti.qualcomm.com to request access to the SDK, obtain the API key or get additional information.

Installation

Add SDK to your project

Put the SDK library file under the libs/ subdirectory and add it to the dependencies section of your build.gradle:

dependencies {
    implementation files('libs/wpsapi.aar')
}

Permissions

Location SDK automatically adds the following permissions to your app’s manifest:

Android Permission Used For
android.permission.INTERNET Communication with Qualcomm’s location servers
android.permission.CHANGE_WIFI_STATE Initiation of Wi-Fi scans
android.permission.ACCESS_WIFI_STATE Obtaining information about the Wi-Fi environment
android.permission.ACCESS_COARSE_LOCATION Obtaining Wi-Fi or cellular based locations
android.permission.ACCESS_FINE_LOCATION Accessing GPS location for hybrid location functionality
android.permission.WAKE_LOCK Keeping processor awake when receiving background updates
android.permission.ACCESS_NETWORK_STATE Checking network connection type to optimize performance
android.permission.BLUETOOTH_SCAN Initiation of BLE scans on Android 12+
android.permission.BLUETOOTH Initiation of BLE scans on Android 11-
android.permission.BLUETOOTH_ADMIN Same as BLUETOOTH

If your app does not require BLE positioning, you can remove Bluetooth-related permissions in your AndroidManifest.xml as follows:

    <uses-permission android:name="android.permission.BLUETOOTH" tools:node="remove"/>
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" tools:node="remove"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" tools:node="remove"/>

Background Mode

Starting with Android 8, the system enforces significant limitations in location determination capabilities when the app is running in background, for power consumption and user privacy considerations.

In order to use the Location SDK in background mode, a regular app has to provide general means of background execution - e.g. by running a foreground service, or setting up a periodic alarm. A foreground service is required to achieve location update rates faster than once every 30 minutes.

Add the following service declaration in your manifest if you are planning to use the Location SDK in background without running a foreground service:

<service
    android:name="com.skyhookwireless.spi.network.NetworkJobService"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:exported="false"/>

The following receiver declaration is recommended (but not required) if your app’s minimum supported Android version is below API 24 (Nougat):

<receiver
    android:name="com.skyhookwireless.spi.power.AlarmReceiver"
    android:exported="false"/>

If your app is targeting API level 29 (Android 10) or higher and you are willing to determine location in background, add the following permission to your manifest file:

Android Permission Used For
android.permission.ACCESS_BACKGROUND_LOCATION Determine location in background

Using the Android Emulator

The Precision Location SDK will not be able to determine location using Wi-Fi or cellular beacons from the emulator because it is unable to scan for those signals. Because of that, its functionality will be limited on the emulator. In order to verify your integration of the SDK using the emulator, you may want to use the getIPLocation() method call. The full functionality will work only on an Android device.

Android System Settings

The Skyhook SDK will respect the system setting with regard to location. This includes the granular location settings for GPS and network based location. The SDK will return WPS_ERROR_LOCATION_SETTING_DISABLED if location cannot be determined because of the current location setting. XPS will continue to determine location when only the GPS location setting is enabled whereas WPS requires that network based location is enabled.

Initializing

Import the SDK

Import the Skyhook WPS package:

import com.skyhookwireless.wps;

Initialize API

Create an instance of XPS (or WPS) API object in the onCreate method of your activity or service:

private XPS xps;
...
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    xps = new XPS(this);
    ...
}

Call setKey() to initialize the API with your key:

xps.setKey("YOUR KEY");

If you use a key and a SKU label for authentication with TPS, call setAuthentication() instead as shown below:

xps.setAuthentication("YOUR KEY", "YOUR SKU");

Enable tiling mode

If you are planning to request location determination frequently, it is recommended to enable the tiling mode in the SDK. It downloads, from the server, a small portion of the database so the device can automonously determine its location, without further need to contact the server.

This mode is activated by calling setTiling():

File tileDir = new File(getFilesDir(), "tiles");

xps.setTiling(
    tileDir.getAbsolutePath(),  // directory where to store tiles
    9 * 50 * 1024,              // 3x3 tiles (~50KB each) for each session
    9 * 50 * 1024 * 10,         // total size is 10x times the session size
    null);

Request location permission

With the runtime permissions model introduced in Android M, the Precision Location SDK requires location permission to be granted before calling most of its methods. Depending on how the SDK is used in the application, developer can decide when to request the permission and if an explanation needs to be displayed for the user:

ActivityCompat.requestPermissions(
    this, new String[] { Manifest.permission.ACCESS_FINE_LOCATION }, 0);

In order to determine location in background on Android 10 or higher, make sure to check that the user has granted the “Allow all the time” (ACCESS_BACKGROUND_LOCATION) location permission.

Location API

One-time location request

The one-time location request provides a method to make a single request for location: getLocation().

The request will call the callback method. The handleWPSLocation() method is passed the WPSLocation object which will contain the location information.

A one-time location request call from your application would look like this:

xps.getLocation(null, WPSStreetAddressLookup.WPS_NO_STREET_ADDRESS_LOOKUP, false, new WPSLocationCallback() {
    @Override
    public void handleWPSLocation(WPSLocation location) {
        // Do something with location
    }

    @Override
    public WPSContinuation handleError(WPSReturnCode error) {
        // ...

        // To retry the location call on error use WPS_CONTINUE,
        // otherwise return WPS_STOP
        return WPSContinuation.WPS_CONTINUE;
    }

    @Override
    public void done() {
        // after done() returns, you can make more WPS calls
    }
});

You can also request a street address or time zone lookup with this method.

Periodic location

A request for periodic location updates can be made using the following method: getPeriodicLocation().

This method will continue running for the specified number of iterations or until the user stops the request by returning WPS_STOP from the callback.

It is highly recommended to enable tiling mode with this location method to eliminate frequent network requests to the server. Note that if street address or time zone lookup is requested, this call will not use the tiling cache to determine locations.

Starting with Android Pie the recommended minimum period for location updates is 30 seconds or longer.

Abort

When your app is terminating, it is recommended to cancel any ongoing operations by invoking the abort() method:

public void onDestroy() {
    super.onDestroy();
    xps.abort();
    ...
}

API reference

Check the full API reference for more information on APIs that are exposed by the SDK.

Logging

To enable logging on SDK 5.16+, add the following code in your application:

xps.setTunable("LogEnabled", true);

By default, the SDK will output log messages to Android logcat.

If you want the SDK to write log to a file, set additional tunables:

xps.setTunable("LogType", "BUILT_IN,FILE");  // log to a file in addition to logcat
xps.setTunable("LogFilePath", "/sdcard/wps.log");

Legacy method

To enable logging on SDK versions prior to 5.16, use the legacy method based on SharedPreferences.

Add the following code in the onCreate() method of your activity, service or application:

SharedPreferences.Editor skyhookPrefs = getSharedPreferences("skyhook", MODE_PRIVATE).edit();
skyhookPrefs.putBoolean("com.skyhook.wps.LogEnabled", true);
skyhookPrefs.putString("com.skyhook.wps.LogType", "BUILT_IN,FILE");  // log to a file in addition to logcat
skyhookPrefs.putString("com.skyhook.wps.LogFilePath", "/sdcard/wpslog.txt");
skyhookPrefs.apply();

If you want to write the log file to external storage, make sure to obtain the WRITE_EXTERNAL_STORAGE permission in your app.

Changelog

5.16.9

5.16.4

5.15.3

5.14.13

5.14.12

5.14.11

5.14.10

5.14.9

5.14.8

5.14.7

5.14.4

5.14.3

5.14.2

5.14.1

5.14.0

5.13

5.12

5.11

5.10

5.9

5.8

5.7

5.6

5.5.1

5.5.0

5.4

5.3

5.2

5.0.2

5.0.0

4.10.x

4.9.8

4.9.7

4.9.6

4.9.5

4.9.4

4.9.3

4.9.2

4.9.1

4.9.0

4.8

4.7.6

4.7.5

4.7

4.6

4.5

Version 4.5 was never released publicly.

4.4

4.3

4.2

4.1

4.0

License

License

Copyright (c) 2023 Qualcomm Innovation Center, Inc. All Rights Reserved.

This work is licensed under the CC BY-ND 4.0 License. See LICENSE for more details.

This site is open source. Improve this page.