Adding the dependency

1. 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);

Start the library whenever the app starts, regardless of runtime permissions. Then call the new restart() method whenever permissions are granted, to signal the library to try starting location callbacks and Bluetooth scanning again.

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. It 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

For library versions prior to 1.2.0: Make sure you never start the library without first having the required runtime permissions - always location permission, and Bluetooth permissions on SDK 31 and above). On every app start, check for permissions, and start the library only if they been granted. And then whenever requesting permissions, start the library when they have successfully been granted.

For version 1.2.0 and above, there are two options. You can either follow the same process above for older libraries, or alternatively you can start the library (regardless of runtime permissions) every time the app starts. And then additionally call the restart() method when the user grants location or Bluetooth permissions.

Note that when the library starts or the app gains user focus, a foreground service is started. When the app loses foreground focus, the service will terminate or remain running, dependent on configuration.

Configuration configuration = new ConfigurationBuilder()
             .withAppKey(appKey) // Your Crowd Connected App Key
             .withToken(token) // Your Crowd Connected Token
             .withSecret(secret) // Your Crowd Connected Secret
             .withServiceNotificationInfo("Service Notification Text", R.drawable.service_icon);
             .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);

The library uses a foreground service and therefore requires a persistent notification. Please provide an appropriate notification icon and notification text using the withServiceNotificationInfo method of the ConfigurationBuilder. Without this the library cannot gather background data.

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

If the app requires real-time position updates then register a position callback. Don't register the position callback until onStartUpSuccess() has been called.

CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
    crowdConnected.registerPositionCallback(location-> {
        //Do something with the location
    });
}

The Location object has the following fields:

From library version 1.2.0 a further field is added to the location object:

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();
}

Sending an Alias

The use cases for background data collection (analytics, and message targeting) often require that the location data is matched to a user id. You can set these alternative IDs as aliases.

Crowd Connected has built-in support for a number of common push notification providers. To make use of the built-in support, you must use the correct alias key. These are documented in the Device Alias guide.

Aliases must not include commas, semicolons, or quotation marks.

Don't send the alias until onStartUpSuccess() has been called.

CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
    crowdConnected.setAlias("aliasKey", "aliasValue");
}

Stopping the library

CrowdConnected crowdConnected = CrowdConnected.getInstance();
if (crowdConnected != null) {
    crowdConnected.stop();
}