Package com.geouniq.android

Class GeoUniq

  • public final class GeoUniq
extends java.lang.Object
    Basic class for using GeoUniq handler and accessing GeoUniq SDK's API.
    This Class is implemented according to the Singleton design pattern. The singleton instance of this class can be obtained through getInstance(Context).

    • Method Detail

      • getInstance

        @NonNull
public static GeoUniq getInstance​(android.content.Context context)
        Allows to obtain the singleton instance of this class
        It throws a RuntimeException if a null object is provided for context parameter.
        Parameters:
        context - the application Context
        Returns:
        the singleton GeoUniq instance

      • disable

        public void disable()
        Allows to disable the SDK.
        Call enable() to enable it again.

      • enable

        public void enable()
        Allows to enable the SDK.
        Call disable() to disable it.

      • isEnabled

        public boolean isEnabled()
        Allows to known if the SDK is enabled
        Returns:
        true if the SDK is enabled, false otherwise

      • setErrorListener

        public void setErrorListener​(GeoUniq.IErrorListener listener)
        Sets a GeoUniq.IErrorListener to receive a callback if an error occurs when starting a basic functionality, such as the background tracking and the motion activity detection.
        Parameters:
        listener - the IErrorListener that will receive callback methods.

      • setDeviceIdListener

        public void setDeviceIdListener​(GeoUniq.IDeviceIdListener listener)
        Sets a GeoUniq.IDeviceIdListener to receive a callback as soon as the Device ID is available.
        The callback is returned even if the Device ID was already been assigned when this method is called.
        Parameters:
        listener - the IDeviceIdListener that will receive callback methods.

      • isDeviceIdAvailable

        public boolean isDeviceIdAvailable()
        Allows to know whether the Device ID is available or not; false otherwise.
        Returns:
        true if the Device ID is available

      • getDeviceId

        @Nullable
public java.lang.String getDeviceId()
        Allows to get the Device ID assigned by GeoUniq Analytics cloud platform to this device.
        Returns:
        the Device ID if available or null otherwise.

      • setCustomId

        public boolean setCustomId​(java.lang.String customId)
        Allows to set a custom ID to the device that will be shown when accessing Resources related to this device from GeoUniq Analytics Web API.

        The maximum allowed length is indicated in MAX_CUSTOM_ID_LENGTH

        Parameters:
        customId - a String representing the desired ID. Its length must be at most
        Returns:
        true if the custom ID is correctly set

      • getCustomId

        public java.lang.String getCustomId()
        Allows to get the custom ID currently set for the device.
        Returns:
        the custom ID or null if it has never been set

      • resetDeviceId

        public void resetDeviceId()

      • setLabel

        public void setLabel​(java.lang.String label)
        Sets a label that will be attached to each location uploaded on GeoUniq cloud platform.
        To change label, call this method with a different value for the label parameter.
        To remove any label, call this method passing the null value for the label parameter.
        Parameters:
        label - a String representing the desired label.
        The maximum allowed length is equal to MAX_LABEL_LENGTH.

      • getLabel

        public java.lang.String getLabel()
        Returns the label that is currently set for this device. It may return null if no label is set.
        Returns:
        the label currently set

      • setTrackingProfile

        public void setTrackingProfile​(GeoUniq.TrackingProfile trackingProfile)
        Sets the desired profile for the tracking functionality.

        Calling this method has effect immediately and permanently. If never called, a tracking profile with all attributes set to their default values will be used.

        Parameters:
        trackingProfile - a GeoUniq.TrackingProfile object indicating the kind of tracking profile
        See Also:
        GeoUniq.TrackingProfile

      • getTrackingProfile

        public GeoUniq.TrackingProfile getTrackingProfile()
        Returns the profile that is currently used for the tracking functionality.
        Returns:
        a GeoUniq.TrackingProfile object indicating the kind of tracking profile

      • setWakeUpsReduction

        public void setWakeUpsReduction​(boolean wakeUpsReduction)
        Allows you to set the SDK in wake-ups reduction mode. By setting this mode, the wake-ups limits defined by the Android Vitals section of the Google console will not be exceeded, but the tracking will worsen considerably.
        Parameters:
        wakeUpsReduction - , true to set the SDK in wake ups reduction mode, false otherwise.

      • isWakeUpsReduction

        public boolean isWakeUpsReduction()
        Returns:
        true if wake-ups reduction mode is enabled, false otherwise.

      • setBalancedPowerAccuracy

        public void setBalancedPowerAccuracy​(boolean balancedPowerAccuracy)
        Allows you to set the SDK in balanced power accuracy mode. By setting this mode, it is possible to save battery use, but the positions obtained will be less accurate and the tracking may deteriorate.
        Parameters:
        balancedPowerAccuracy - , true to set the SDK in balanced power mode, false otherwise.

      • isBalancedPowerAccuracy

        public boolean isBalancedPowerAccuracy()
        Returns:
        true if balanced power accuracy mode is enabled, false otherwise.

      • getLastKnownLocation

        @Nullable
public GeoUniq.Location getLastKnownLocation()
        Allows to get the last location known by the SDK. It never leads to a location detection.
        Returns:
        The last known location if any. Otherwise null.

      • getLocationHistory

        public boolean getLocationHistory​(@NonNull
                                  java.util.Date from,
                                  @NonNull
                                  java.util.Date to,
                                  boolean newestFirst,
                                  @NonNull
                                  GeoUniq.ILocationsReceiver locationsReceiver)
        Returns all the positions stored on GeoUniq Analytics platform that were detected during a specified time interval If no location is found in the specified interval, the last location before the interval start time is retrieved.

        This method returns a boolean indicating whther the operation can be performed or not. This method shouldn't be called if the Device ID is not yet available (see isDeviceIdAvailable()). In that case, the method will return false

        The location history will be returned asynchronously to the locationsReceiver parameter through the GeoUniq.ILocationsReceiver.onSuccess(LinkedList) callback.
        If an error occurs such that locations cannot be retrieved from GeoUniq server, a callback to GeoUniq.ILocationsReceiver.onError() will be returned.

        The time interval of interest is specified through two Date objects.

        Parameters:
        from - a Date object indicating the beginning of the time frame
        to - a Date object indicating the end of the time frame
        newestFirst - whether the returned positions must be ordered from the newest to the oldest or vice-versa
        locationsReceiver - the GeoUniq.ILocationsReceiver object that will receive the callback.
        Returns:
        true if the operation can be performed, otherwise false

      • registerTrackingListener

        public void registerTrackingListener​(java.lang.Class<? extends GeoUniq.ITrackingListener> callbackClass)
        Registers a listener Class to receive position updates generated by the tracking functionality.

        Once this method is called, each time a new significant position update is detected a new instance of the class indicated by the parameter callbackClass will be automatically created and the related callback method will be invoked (see GeoUniq.ITrackingListener).

        Callback methods are invoked regardless of the state of the application, i.e. they are called even after the application has been killed.

        A registration remains valid until the same class is unregistered by calling the method removeTrackingListener(java.lang.Class). Note that a registration remains valid even after the application gets updated

        Calling this method more than once with the same callbackClass has no effect.

        Parameters:
        callbackClass - a Class object representing the listener's class, which must implement the interface GeoUniq.ITrackingListener.
        The Java class represented by this Class object must have the public no-argument constructor.

      • removeTrackingListener

        public void removeTrackingListener​(java.lang.Class<? extends GeoUniq.ITrackingListener> callbackClass)
        Removes a Class set as listener for position updates generated by the tracking functionality.

        Calling this method providing in callbackClass a Class that was not registered has no effect. Otherwise, the registration is removed regardless of how many times the listener had been registered (see registerTrackingListener(Class)).

        Parameters:
        callbackClass - a Class object representing the listener's class, which must implement the interface GeoUniq.IMotionActivityListener.

      • getTrackingRegistrations

        public java.util.Set<java.lang.Class<? extends GeoUniq.ITrackingListener>> getTrackingRegistrations()
        Returns the set of Class that are set as listener for position updates generated by the tracking functionality.

        (see registerTrackingListener(Class)).

        Returns:
        a Set of Class objects representing the listeners' class

      • registerMotionActivityListener

        public void registerMotionActivityListener​(@NonNull
                                           java.lang.Class<? extends GeoUniq.IMotionActivityListener> receiverClass,
                                           @NonNull
                                           GeoUniq.MotionActivity.Type[] motionTypes)
        Registers a listener class for receiving a callback when specific types of motion activity start and finish.

        Once this method is called, each time one of the GeoUniq.MotionActivity.Type within the motionTypes array begins or finishes, a new instance of the class indicated by the parameter receiverClass will be automatically created and the related callback method will be invoked (see GeoUniq.IMotionActivityListener).

        Callback methods are invoked regardless of the state of the application, i.e. they are called even if the application is not running.

        A registration remains valid until the same class is unregistered by calling the method deregisterMotionActivityListener(Class, MotionActivity.Type[]). Note that a registration remains valid even after the application gets updated

        Registrations and de-registrations work independently. Specifically, once a class has been registered for a particular set of motion activity types, the same class can be unregistered for any subset of those motion activity types.

        Calling this method more than once with the same receiverClass does not replace previous registrations of the same class but has the only effect of adding the new set of motion activities (provided by the parameter motionTypes) to the set of motion activities for which the receiverClass is already registered. This means that calling this method with exactly the same parameters more than once has no effect.

        Parameters:
        receiverClass - a Class object representing the listener's class, which must implement the interface GeoUniq.IMotionActivityListener.
        The Java class represented by this Class object must have the public no-argument constructor.
        motionTypes - The motion type.

      • getMotionActivityRegistrations

        public java.util.Map<java.lang.Class<? extends GeoUniq.IMotionActivityListener>,​java.util.Set<GeoUniq.MotionActivity.Type>> getMotionActivityRegistrations()
        Returns all the motion activity registrations currently active.
        Returns:
        a Map where each key is the Classobject representing the receiver class and each value is a Set of GeoUniq.MotionActivity.Type objects which represent all the motion activities which the callback class is registered for.

      • getPushNotificationsToken

        @Nullable
public java.lang.String getPushNotificationsToken()
        Returns the String set as push notifications token through setPushNotificationToken(String). It returns null if no String has ever been set.
        Returns:
        the token

      • setPushNotificationToken

        public void setPushNotificationToken​(java.lang.String token)
        Allows to set a token for push notifications that will be visible when accessing this device's resources from the WEB API.

        Such token will be stored by GeoUniq SDK and uploaded on GeoUniq Analytics platform. This token will be obtained when requesting any information that is related to this device through the WEB API or when receiving Alerts for a Trigger.

        Note that no check is performed on the correctness of the token. The token parameter is considered just a String.

        Parameters:
        token - the token to store and upload

      • registerToGroupsWithName

        public void registerToGroupsWithName​(@NonNull
                                     java.lang.String name)
        Allows to register this Device to all the Groups whose name is equal to the parameter name.
        Parameters:
        name - String indicating the name of the Group(s) of interest

      • registerToGroup

        public void registerToGroup​(@NonNull
                            java.lang.String groupId)
        Allows to register this Device to the Group whose ID is equal to the parameter groupID.
        Parameters:
        groupId - String indicating the ID of the Group of interest

      • removeCustomEndpoint

        public void removeCustomEndpoint()
        Removes the GeoUniq.CustomEndpoint.

        If no CustomEndpoint was set, calling this method has no effect.

      • enableCustomEndpoint

        public void enableCustomEndpoint()
        Enables the GeoUniq.CustomEndpoint.

        If no CustomEndpoint was set, or the one set was already enabled, calling this method has no effect. The CustomEndpoint can be successively disabled by calling disableCustomEndpoint().

      • disableCustomEndpoint

        public void disableCustomEndpoint()
        Disables the GeoUniq.CustomEndpoint.

        If no CustomEndpoint was set, or the one set was already disabled, calling this method has no effect. The CustomEndpoint can be successively enabled by calling enableCustomEndpoint().

      • removeGeoFence

        public boolean removeGeoFence​(@NonNull
                              java.lang.String id)
        Removes the GeoFence with the provided ID from the set of monitored GeoFence.
        Parameters:
        id - The ID of the GeoFence to remove
        Returns:
        true if a GeoFence with the provided ID is found or false otherwise

      • getGeoFence

        public GeoUniq.GeoFence getGeoFence​(java.lang.String id)
        Returns the GeoUniq.GeoFence with the provided ID if found among the set of monitored GeoFence. If no monitored GeoFence exists with the provided ID, it returns null.
        Parameters:
        id - The id of geofence
        Returns:
        the GeoFence with the provided ID if any. null otherwise

      • showConsentDialogAndSet

        @Deprecated
public void showConsentDialogAndSet​(@NonNull
                                    android.app.Activity activity,
                                    GeoUniq.IConsentAlertResponseListener consentAlertResponseListener)
        Deprecated.
        This method is no longer used.

        Use showPrivacyPolicyAndSet(Activity, IPrivacyPolicyListener) instead.

        Show a dialog that ask for privacy consent permission
        Parameters:
        activity - The activity that owns this dialog
        consentAlertResponseListener - Callback called when dialog is closed

      • setConsentStatus

        @Deprecated
public void setConsentStatus​(boolean isGranted)
        Deprecated.
        This method is no longer used.

        Use setPrivacyConsent(ConsentItem, boolean) instead.

        Set the status of privacy consent
        Parameters:
        isGranted - The status that will be set

      • showPrivacyPolicyAndSet

        public void showPrivacyPolicyAndSet​(@NonNull
                                    android.app.Activity activity,
                                    GeoUniq.IPrivacyPolicyListener newPrivacyFlowListenerListener)
        Show a dialog that ask for privacy consents permission
        Parameters:
        activity - The activity that owns this view
        newPrivacyFlowListenerListener - Callback called when dialog is closed

      • showPrivacyPolicyAndSet

        public void showPrivacyPolicyAndSet​(@NonNull
                                    android.content.Context context,
                                    GeoUniq.IPrivacyPolicyListener newPrivacyFlowListenerListener)
        Show a dialog that ask for privacy consents permission
        Parameters:
        context - The context that owns this view
        newPrivacyFlowListenerListener - Callback called when dialog is closed

      • showPrivacyPolicySwitchesAndSet

        public void showPrivacyPolicySwitchesAndSet​(@NonNull
                                            android.app.Activity activity,
                                            GeoUniq.IPrivacyPolicyListener newPrivacyFlowListenerListener)
        Show a dialog that ask for privacy consents permission
        Parameters:
        activity - The activity that owns this view
        newPrivacyFlowListenerListener - Callback called when dialog is closed

      • showPrivacyPolicySwitchesAndSet

        public void showPrivacyPolicySwitchesAndSet​(@NonNull
                                            android.content.Context context,
                                            GeoUniq.IPrivacyPolicyListener newPrivacyFlowListenerListener)
        Show a dialog that ask for privacy consents permission
        Parameters:
        context - The context that owns this view
        newPrivacyFlowListenerListener - Callback called when dialog is closed

      • setPrivacyConsent

        public void setPrivacyConsent​(GeoUniq.ConsentItem consentItem,
                              boolean value)
        Set the status of a privacy consent
        Parameters:
        consentItem - The consent that will be set
        value - The status that will be set

      • getPrivacyConsent

        public boolean getPrivacyConsent​(GeoUniq.ConsentItem consentItem)
        Return the status of privacy consent
        Parameters:
        consentItem - The consent that will be read
        Returns:
        The status of the consent

      • registerHomeLocationListener

        public void registerHomeLocationListener​(java.lang.Class<? extends GeoUniq.IHomeLocationListener> callbackClass)
        Sets the callback class that will receive updates when the home location changes.
        Parameters:
        callbackClass - A class implementing GeoUniq.IHomeLocationListener interface.

      • unregisterHomeLocationListener

        public void unregisterHomeLocationListener​(java.lang.Class<? extends GeoUniq.IHomeLocationListener> callbackClass)
        Remove home location updates for the listener.
        Parameters:
        callbackClass - A class implementing GeoUniq.IHomeLocationListener interface.

      • registerWorkLocationListener

        public void registerWorkLocationListener​(java.lang.Class<? extends GeoUniq.IWorkLocationListener> callbackClass)
        Sets the callback class that will receive updates when the work location changes.
        Parameters:
        callbackClass - A class implementing GeoUniq.IWorkLocationListener interface.

      • unregisterWorkLocationListener

        public void unregisterWorkLocationListener​(java.lang.Class<? extends GeoUniq.IWorkLocationListener> callbackClass)
        Remove work location updates for the listener.
        Parameters:
        callbackClass - A class implementing GeoUniq.IWorkLocationListener interface.

      • getHomeLocation

        public GeoUniq.HomeLocation getHomeLocation()
        Allows to get the home location calculated for this device.
        Returns:
        The home location if available or null otherwise.

      • getWorkLocation

        public GeoUniq.WorkLocation getWorkLocation()
        Allows to get the work location calculated for this device.
        Returns:
        The work location if available or null otherwise.