For the SDK to be able to accomplish its main task, that is tracking the device position, the following requirements must be met:

• The foreground location permission must be granted to the app

• The background location permission must be granted to the app, if it meets the Google Play Store policies for background location

• The location functionality must be enabled on the device

• Google Play Services must be installed on the device (almost always met)

The SDK provides a simple way for checking all the requirements and optionally solve the related issues. Solving an issue generally implies showing an alert to the User. Depending on the specific requirement, a different alert will be shown.

The example below shows hot to check for all requirements and solve them. In the example, the check is performed on the onStart() method of the main activity

public class MainActivity extends Activity {

    private GeoUniq geoUniq;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.geoUniq = GeoUniq.getInstance(this);
        this.geoUniq.enable();
    }

    @Override
    protected void onStart() {
        super.onStart();
        // This is to automatically handle location permission and other possible issues that would prevent GeoUniq to work correctly
        this.setErrorListener();
    }


    /**
     * Sets an Error listener to automatically handle those situations that would prevent the SDK to work properly
     */
    private void setErrorListener(){

        this.geoUniq.setErrorListener(new GeoUniq.IErrorListener() {
            @Override
            public void onError(GeoUniq.RequestResult requestResult) {
                if(requestResult.hasResolution()){
                    requestResult.startResolution(MainActivity.this);
                }
            }
        });
    }
}

The SDK can be enabled and disabled at runtime. To make GeoUniq SDK start, you need to enable it by calling the method GeoUniq.enable() at least once.

You might do that into the main activity of your app, as in the example below.

Once enabled, the SDK will not stop until you disable it by calling GeoUniq.disable(). That is, it will keep performing automatic operations, such as tracking the device position, even after a device reboot or an update of the app. Disabling the SDK at runtime is useful if you want the SDK to stop completely. For example, you could remotely control a configuration parameter of your app to stop the SDK for all or some of your installations.

If you simply don't want GeoUniq to keep collecting location data for a specific User, you can do that without completely disabling the SDK (see Handle user consent). This way you can still exploit the mobile-side functionalities that the SDK provides without having GeoUniq collecting data for the specific user

public class MainActivity extends Activity {

    private GeoUniq geoUniq;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.geoUniq = GeoUniq.getInstance(this);
        this.geoUniq.enable();
    }
}

The method GeoUniq.getInstance(context).resetDeviceId() reset the Device Id by invoking a new device registration.

As soon as the SDK starts for the first time, a Device ID is assigned to that specific installation of your app.

The Device ID assigned to an installation might change in case of rare events, for example if the local storage of the device gets erased.

The SDK provides two different ways to obtain the Device ID.

Getting the Device ID through a Device ID listener

The first method to obtain the Device ID is to set a IDeviceIdListener, as shown in the example below. When a listener is set, the SDK immediately returns the Device ID through the onDeviceIdAvailable() callback if the Device ID is already available. Otherwise, it will call the callback method as soon as the ID is obtained.

The best practice for an app that want to collect on a backend systems the Device ID assigned to each installation, is to set a IDeviceIdListener each time it starts. The mobile app would receive the Device ID each time and should always send it to the backend system. Then, the backend system should overwrite any previously stored value if the new received value is different.

Getting the Device ID by calling an explicit class method

The second way is to call the GeoUniq.getDeviceId() method. This method returns the value of the Device ID if it has already been obtained or null if the Device ID has not been obtained yet.

Get Home Location

Allows to get the home location calculated for this device. Return an HomeLocation object if home location is available or null otherwise.

GeoUniq.getInstance(context).getHomeLocation()

Register Home Location Listener

Sets the listener class that will receive updates when the home location changes. The listener must be impIement the IHomeLocationListener interface.

GeoUniq.getInstance(context).registerHomeLocationListener(listener)

Unregister Home Location listener

Remove home location updates for the listener.

GeoUniq.getInstance(context).unregisterHomeLocationListener(listener)

The locations of interest, such as home and work locations, are places identified based on the visits detected by the SDK.

Get Work Location

Allows to get the work location calculated for this device. Return a WorkLocation object if work location is available or null otherwise.

Register Work Location listener

Sets the listener class that will receive updates when the work location changes. The listener must be impIement the IWorkLocationListener interface.

Unregister Work Location listener

Remove work location updates for the listener.