Adding the dependency
- Add the Crowd Connected repository to your Gradle build file
repositories {
maven { url "https://maven2.crowdconnected.net/" }
}
2. Add the latest Core library and either IPS (Indoor Positioning) Geo (Outdoor Positioning), or both. NB for library versions prior to 1.2.0 you must use either IPS or Geo, but not both.
implementation 'net.crowdconnected.android.core:android-core:1.3.4'
implementation 'net.crowdconnected.android.ips:android-ips:1.3.4' (if required)
implementation 'net.crowdconnected.android.geo:android-geo:1.3.4' (if required)
Getting Permission - version 1.2
Version 1.2 and above target Android SDK version 31.
For all positioning (IPS and Geo), the manifests contain ACCESS_FINE_LOCATION permission which requires user runtime permission. It also contains ACCESS_COARSE_LOCATION permission which is now required whenever fine permission is included. You only need ask the user for FINE permission.
ActivityCompat.requestPermissions(this,
new String[]{ Manifest.permission.ACCESS_FINE_LOCATION }, 0);
To support SDK < 31 Indoor positioning the manifests additionally contain BLUETOOTH and BLUETOOTH_ADMIN permissions (marked as legacy). These do not require user runtime permission.
To support SDK >=31 Indoor positioningthe manifests include BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions. These do require runtime permission.
ActivityCompat.requestPermissions(this,
new String[]{ Manifest.permission.BLUETOOTH_SCAN, BLUETOOTH_CONNECT }, 0);
Location permission can be requested within your app onboarding process or as the user navigates to the map. If the library has been started before permission is granted, then you will need to also call the restart() method once permission is granted. If the library is only started after permission has been granted, there is no need to call restart().
Getting Permission - version 1.1 and lower
Version 1.1 and below target Android SDK version 30. Only location permission is required from the user at runtime. As it targets SDK 30, the library will run on Android 12 with location permission only.
Location permission can be requested within your app onboarding process or as the user navigates to the map. It should be granted before starting the library. The library will not function unless location permission has already been granted before it is started.
ActivityCompat.requestPermissions(this,
new String[]{ Manifest.permission.ACCESS_FINE_LOCATION }, 0);
Starting the library
Start the library when the user navigates to the map.
Configuration configuration = new ConfigurationBuilder()
.withAppKey(appKey) // Your Crowd Connected App Key
.withToken(token) // Your Crowd Connected Token
.withSecret(secret) // Your Crowd Connected Secret
.withStatusCallback(new StatusCallback() {
@Override
public void onStartUpFailure(String reason) {
Log.i(LOG_TAG, "Start up failure: " + reason);
}
@Override
public void onStartUpSuccess() {
// The library has started successfully, you can now set aliases and register position callbacks
}
})
.addModule(new IPSModule() or new GeoModule()) // Add relevant module
.build();
CrowdConnected.start(getApplicationContext(), configuration);
App Credentials
When you start the library, you will need an app key, a token and a secret. If you don't have an app key, you can register for a new account here.
Once you have an account, you can follow the Tokens guide to generate the token and secret.
Register the Position Callback
Don't register the position callback until onStartUpSuccess() has been called.
CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
crowdConnected.registerPositionCallback(position -> {
//Do something with the position
});
}
The position object has the following fields:
Name | Type | Required? | Notes |
xMetres | double | Yes | |
yMetres | double | Yes | |
latitude | double | No | Only present if the map is geo-referenced |
longitude | double | No | Only present if the map is geo-referenced |
timestamp | long | Yes | |
surfaceId | String | Yes | |
floor | Integer | No | Only present if the map has a floor assigned |
xPixels | double | No | Only present for some mapping providers |
yPixels | double | No | Only present for some mapping providers |
From library version 1.2.0 a further field is added to the location object:
type | enum | Yes | IPS, GEO |
Remove the Position Callback
CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
crowdConnected.deregisterPositionCallback();
}
Starting and Stopping Navigation
If you are using the Geo Module for navigation you call methods to notify the library. This increases the frequency of Geo location updates.
When the user navigates to the map call:
CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
crowdConnected.startNavigation();
}
When the user navigates away from the map call:
CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
crowdConnected.stopNavigation();
}
Stopping the library
Stop the library when the user navigates away from the map
CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
crowdConnected.stop();
}