Package com.geouniq.android

Class GeoUniq

java.lang.Object
com.geouniq.android.GeoUniq
public final class GeoUniq extends 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).

  • Field Details

  • Method Details

    • 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 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(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 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(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 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

    • setPowerProfile

      public void setPowerProfile(GeoUniq.PowerProfile powerProfile)
      Allows to set a GeoUniq.PowerProfile to control the trade-off between the precision/accuracy of the tracking and the impact on battery.
      Parameters:
      powerProfile - the GeoUniq.PowerProfile to 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:

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

    • getLocation

      public void getLocation(float spaceAccuracy, GeoUniq.ILocationListener locationListener, GeoUniq.IErrorListener errorListener)
      Allows to access the location of the device with the provided space accuracy.

      This method return immediately. The response will be returned asynchronously to the locationListener parameter through GeoUniq.ILocationListener.onLocationListened(android.location.Location) and GeoUniq.ILocationListener.onFinalLocationListened(android.location.Location) callback methods.

      Specifically, if the location can be detected, native Android Location objects will be returned. Otherwise, the GeoUniq.IErrorListener.onError(GeoUniq.RequestResult) callback will be invoked providing a GeoUniq.RequestResult object indicating the error.

      Parameters:
      locationListener - an object implementing the ILocationListener interface which will receive the response through a callback
      spaceAccuracy - a float value indicating the the desired accuracy in meters. Values lower than 30 are likely to require using GPS thus increasing battery consumption.
      errorListener - a GeoUniq.IErrorListener object which will receive a callback if the location cannot be detected.
      See Also:

    • getLocationHistory

      public boolean getLocationHistory(@NonNull Date from, @NonNull 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(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(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 Set<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

    • removeAllTrackingRegistrations

      public void removeAllTrackingRegistrations()
      Removes all tracking listeners.
      (see registerTrackingListener(Class)).

    • registerMotionActivityListener

      public void registerMotionActivityListener(@NonNull 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.

    • deregisterMotionActivityListener

      public void deregisterMotionActivityListener(Class<? extends GeoUniq.IMotionActivityListener> listenerClass, GeoUniq.MotionActivity.Type[] motionTypes)
      Removes motion activity registrations for a listener.

      Calling this method providing in motionTypes a GeoUniq.MotionActivity.Type for which the listener specified by listenerClass is not registered has no effect. Otherwise, the registration is removed regardless of how many times the listener had been registered (see registerMotionActivityListener(Class, MotionActivity.Type[])).

      Parameters:
      motionTypes - The motion type.
      listenerClass - Listener class

    • getCurrentMotionActivity

      public GeoUniq.MotionActivity getCurrentMotionActivity()
      Returns the last detected motion activity.
      Returns:
      a GeoUniq.MotionActivity object representing the last detected motion activity.

    • getMotionActivityRegistrations

      public Map<Class<? extends GeoUniq.IMotionActivityListener>,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.

    • deregisterAllMotionActivityListeners

      public void deregisterAllMotionActivityListeners()
      Removes all motion activity registrations, for any GeoUniq.MotionActivity.Type and receiver class.
      See Also:

    • getPushNotificationsToken

      @Nullable public 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(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 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 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

    • setCustomEndpoint

      public void setCustomEndpoint(GeoUniq.CustomEndpoint endpoint)
      Set a GeoUniq.CustomEndpoint that will receive all the location updates sent to GeoUniq Analytics platform.

      Use the GeoUniq.CustomEndpoint.Builder to obtain a instance CustomEndpointof object

      Parameters:
      endpoint - the GeoUniq.CustomEndpoint to be set

    • getCustomEndpoint

      public GeoUniq.CustomEndpoint getCustomEndpoint()
      Returns the GeoUniq.CustomEndpoint set if any, otherwise returns null.

      Use setCustomEndpoint(CustomEndpoint) to set a CustomEndpoint

      Returns:
      the current GeoUniq.CustomEndpoint

    • 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().

    • setGeoFence

      public String setGeoFence(@NonNull GeoUniq.GeoFence geoFence)
      Allows to start monitoring a GeoFence.
      A unique ID will be generated and assigned to the provided GeoFence (see GeoUniq.GeoFence.getId()), provided that an area and callback class has been set for this GeoFence (see GeoUniq.GeoFence.Builder.setArea(GeoUniq.CircularArea) and GeoUniq.GeoFence.Builder.setCallbackClass(Class)), otherwise null will be returned indicating that the GeoFence is invalid.

      The GeoFence will be monitored until it expires (see GeoUniq.GeoFence.Builder.setExpirationDate(Date)). Whenever its status changes, a new instance of the callback class set for the GeoFence will be automatically created (see GeoUniq.GeoFence.Builder.setCallbackClass(Class)) and the callback method GeoUniq.GeoFenceListener.onStatusChanged(Context, GeoUniq.GeoFence) will be called.

      Parameters:
      geoFence - The GeoFence to monitor
      Returns:
      the ID of the GeoFence or null if an invalid GeoFence has been provided

    • removeGeoFence

      public boolean removeGeoFence(@NonNull 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

    • getGeoFences

      public List<GeoUniq.GeoFence> getGeoFences()
      Returns the List of monitored GeoUniq.GeoFence
      Returns:
      the List of monitored GeoFence

    • getGeoFence

      public GeoUniq.GeoFence getGeoFence(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

    • getConsentStatus

      @Deprecated public boolean getConsentStatus()
      Deprecated.
      This method is no longer used.

      Use setPrivacyConsent(ConsentItem, boolean) instead.

      Return the status of privacy consent set by setConsentStatus(boolean)
      Returns:
      Status of privacy consent

    • 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

    • getPrivacyConsentsMap

      public GeoUniq.IConsentsMap getPrivacyConsentsMap()
      Use this method to obtain a list of all consents
      Returns:
      A GeoUniq.IConsentsMap with the status of all consents

    • registerHomeLocationListener

      public void registerHomeLocationListener(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(Class<? extends GeoUniq.IHomeLocationListener> callbackClass)
      Remove home location updates for the listener.
      Parameters:
      callbackClass - A class implementing GeoUniq.IHomeLocationListener interface.

    • registerWorkLocationListener

      public void registerWorkLocationListener(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(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.