Package com.indooratlas.android.sdk

Class IALocationManager

  • public abstract class IALocationManager
extends Object

    This class provides access to IndoorAtlas location services. The methods of this class must be called from the application main thread only.

    Any conditions that prevent the manager from running are logged with Log using log tag IASDK.

    Basic usage: 

    
     protected void onCreate(Bundle bundle) {
         super.onCreate(bundle)
         mLocationManager = IALocationManager.create(context);
     }

     protected void onDestroy() {
         mLocationManager.destroy();
         super.onDestroy();
     }

     protected void onResume() {
         super.onResume();
         mLocationManager.requestLocationUpdates(IALocationRequest.create(), this);
     }

     protected void onPause() {
         mLocationManager.removeLocationUpdates(this);
         super.onPause();
     }

     public void onLocationChanged(IALocation location) {
         // do something interesting with the new update
     }

     public void onStatusChanged(String provider, int status, Bundle extras) {
         // do something with the new status
     }

    Monitor geofences: 

         protected void onCreate(Bundle bundle) {
         super.onCreate(bundle)
         mLocationManager = IALocationManager.create(context);
         mLocationManager.requestLocationUpdates(IALocationRequest.create(), this);

         // Create edges with unique clockwise (lat, lon) points
         List<double[]> edges = Arrays.asList(new double[][]{{59.8, 20.3}, {64.3, 20.7},
                                                   {63.7, 32.1}, {59.2, 29.8}});
         // Create the geofence for 10 seconds in floor number 1
         IAGeofence geofence = new IAGeofence.Builder()
                                  .withEdges(edges)
                                  .withFloor(1)
                                  .withId("This is a geofence for testing")
                                  .withExpirationDuration(10000)
                                  .withTransitionType(IAGeofence.GEOFENCE_TRANSITION_ENTER |
                                                      IAGeofence.GEOFENCE_TRANSITION_EXIT)


         mLocationManager.addGeofences(new IAGeofenceRequest.Builder()
                                  .withGeofence(geofence)
                                  .withInitialTrigger(IAGeofenceRequest.INITIAL_TRIGGER_ENTER)
                                  .build(), this);

     }

     public void onGeofencesTriggered(IAGeofenceEvent geofenceEvent) {
         // Do something with the triggered geofences in geofenceEvent
     }

    Monitor wayfinding route changes: 

         protected void onCreate(Bundle bundle) {
         super.onCreate(bundle)
         mLocationManager = IALocationManager.create(context);
         mLocationManager.requestLocationUpdates(IALocationRequest.create(), this);
         IAWayfindingRequest request = new IAWayfindingRequest.Builder()
                                          .withLatitude(60.1692229)
                                          .withLongitude(24.9326988)
                                          .withFloor(1)
                                          .build();
         mLocationManager.requestWayfindingUpdates(request, this);
     }

     public void onWayfindingUpdate(IARoute route) {
         // Do something with wayfinding route
     }

    • Field Detail

      • STATUS_OUT_OF_SERVICE

        public static final int STATUS_OUT_OF_SERVICE
        Location service is not available and the condition is not expected to resolve itself soon.
        See Also:
        Constant Field Values

      • STATUS_TEMPORARILY_UNAVAILABLE

        public static final int STATUS_TEMPORARILY_UNAVAILABLE
        Location service temporarily unavailable due to the lack of network connectivity. This mostly happens in the beginning of a positioning session when the SDK need to authenticate itself in the IndoorAtlas cloud and download map data, if it has not been cached yet.
        See Also:
        Constant Field Values

      • STATUS_AVAILABLE

        public static final int STATUS_AVAILABLE
        Location service running normally.
        See Also:
        Constant Field Values

      • STATUS_LIMITED

        public static final int STATUS_LIMITED
        Location service is running but with limited accuracy and functionality. This may be, e.g., if WiFi information is not available because the user has disabled WiFi scanning or the relevant permissions have not been granted (Android 6.0+).

        If running on Android 6.0 or above, make sure you have checked that at least Manifest.permission.ACCESS_COARSE_LOCATION has been granted.

        See Also:
        Constant Field Values

      • EXTRA_API_KEY

        public static final String EXTRA_API_KEY
        Extra attribute key to configure IndoorAtlas API key at run time. This is an optional way of configuring API credentials. If key and secret are not defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml. See the Getting Started guide for more info.
        See Also:
        create(Context, Bundle), Constant Field Values

      • EXTRA_API_SECRET

        public static final String EXTRA_API_SECRET
        Extra attribute key to configure IndoorAtlas API secret at run time. This is an optional way of configuring API credentials. If key and secret are not defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml. See the Getting Started guide for more info.
        See Also:
        create(Context, Bundle), Constant Field Values

    • Constructor Detail

      • IALocationManager

        public IALocationManager()

    • Method Detail

      • create

        public static IALocationManager create​(@NonNull
                                       Context context)
        Recommended constructor. Creates a new instance of IALocationManager.
        Parameters:
        context -

      • create

        public static IALocationManager create​(@NonNull
                                       Context context,
                                       @Nullable
                                       Bundle extras)
        Creates a new instance of IALocationManager.
        Parameters:
        context -
        extras - extra arguments to service. See EXTRA_ constant fields for this class.

      • destroy

        public abstract void destroy()
        Release all resources allocated by this class. Remember to pair a call to create(Context) with a corresponding call to this method. Calling any method after calling destroy will throw an IllegalStateException.

      • requestLocationUpdates

        public abstract void requestLocationUpdates​(@NonNull
                                            IALocationRequest request,
                                            @NonNull
                                            PendingIntent pendingIntent)

        Request location and status updates updates that are delivered to an application component specified by a PendingIntent. The location and status updates are in the extras of the Intent. Use IALocation.from(Intent) to obtain the location update.

        Please see in the Android documentation how to configure the PendingIntent.

        Requesting location updates with this method leaves the IndoorAtlas location service running in the background until removeLocationUpdates(PendingIntent) is called with a matching PendingIntent. Alternatively, it can be killed manually by the user or the entire process killed by Android to save resources.

        Parameters:
        request - contains parameters for location manager to choose how updates are delivered to the listener
        pendingIntent - specifies what component is notified with location updates
        Throws:
        IllegalArgumentException - if request is null
        IllegalArgumentException - if pendingIntent is null
        IllegalStateException - if called after destroy() has been called
        See Also:
        EXTRA_LOCATION

      • removeLocationUpdates

        public abstract boolean removeLocationUpdates​(@NonNull
                                              IALocationListener listener)
        Removes all updates for the specific listener. After calling this method, updates will no longer be delivered to the listener.
        Parameters:
        listener - a listener object that will no longer need location updates
        Returns:
        true if listener was registered and is now removed, otherwise false.
        Throws:
        IllegalArgumentException - if listener is null.
        IllegalStateException - if called after destroy() has been called

      • removeLocationUpdates

        public abstract void removeLocationUpdates​(@NonNull
                                           PendingIntent pendingIntent)
        Removes all updates for the specific pendingIntent. After calling this method, updates will no longer be delivered to the application component.
        Parameters:
        pendingIntent - a PendingIntent that will no longer need location updates false.
        Throws:
        IllegalArgumentException - if pendingIntent is null.
        IllegalStateException - if called after destroy() has been called

      • setLocation

        public abstract void setLocation​(@NonNull
                                 IALocation location)

        Indicate current location to the positioning service. This method can be used to set the explicit location (latitude, longitude, accuracy, floor level).

        See lockFloor(int) for restricting the positioning to a certain floor level.

        Explicit location is used as a hint in the system. This means that the inputted location is used only to determine the initial position. Example use cases:

        1.) Set user location to WGS84 coordinates 60.01 latitude and 24.123 longitude with approximate accuracy of 5 meters and floor level 3. 

             IALocationManager.setLocation(new IALocation.Builder()
                                   .withLatitude(60.01)
                                   .withLongitude(24.123)
                                   .withAccuracy(5.0)
                                   .withFloorLevel(3)
                                   .build());
        Value of accuracy determines how strongly the horizontal position information is used. For example, if there is no good knowledge about horizontal position, but floor level is known, set accuracy to some large value (e.g. 75 meters).

        2.) Set user location to WGS84 coordinates 60.01 latitude and 24.123 longitude with approximate accuracy of 5 meters and no information about floor level. In this case, IA floor detection is used to infer the floor level. 

             IALocationManager.setLocation(new IALocation.Builder()
                                   .withLatitude(60.01)
                                   .withLongitude(24.123)
                                   .withAccuracy(5.0)
                                   .build());

        Parameters:
        location - location indicating current position
        Throws:
        IllegalArgumentException - is location is null
        IllegalStateException - if called after destroy() has been called
        See Also:
        lockFloor(int), lockIndoors(boolean)

      • getExtraInfo

        @NonNull
public abstract IAExtraInfo getExtraInfo()
        Returns additional information not vital for the functionality of the SDK.
        Returns:
        Extraneous information.
        Throws:
        IllegalStateException - if called after destroy() has been called

      • removeGeofences

        public abstract void removeGeofences​(List<String> geofenceRequestIds)
        Remove geofences from monitoring.
        Parameters:
        geofenceRequestIds - List of geofence IDs we no longer wish to monitor.
        Throws:
        IllegalStateException - if called after destroy() has been called

      • removeGeofenceUpdates

        public abstract boolean removeGeofenceUpdates​(@NonNull
                                              IAGeofenceListener listener)
        Removes all updates for the specific listener. After calling this method, updates will no longer be delivered to the listener.
        Parameters:
        listener - a listener object that will no longer need location updates
        Returns:
        true if listener was registered and is now removed, otherwise false.
        Throws:
        IllegalArgumentException - if listener is null.
        IllegalStateException - if called after destroy() has been called

      • removeGeofenceUpdates

        public abstract void removeGeofenceUpdates​(@NonNull
                                           PendingIntent pendingIntent)
        Removes all updates for the specific pendingIntent. After calling this method, geofence events will no longer be delivered to the application component.
        Parameters:
        pendingIntent - a PendingIntent that will no longer need geofence events.
        Throws:
        IllegalArgumentException - if pendingIntent is null.
        IllegalStateException - if called after destroy() has been called

      • lockFloor

        public abstract void lockFloor​(int floorNumber)
        Locks positioning to the specified floor level. Locked floor level also enables indoor-only mode, but not vice versa, i.e., lockIndoors(boolean) has no effect on floor level lock.
        Parameters:
        floorNumber - Floor level where the positioning is restricted
        See Also:
        unlockFloor(), lockIndoors(boolean)

      • unlockFloor

        public abstract void unlockFloor()
        Unlocks positioning from the locked floor. If lockFloor(int) has not been called before this is a no-op.

      • lockIndoors

        public abstract void lockIndoors​(boolean locked)
        Engage or release indoor-only lock (a.k.a. indoor-only mode). If locked, automatic indoor-outdoor detection is disabled. Indoor-only lock is enabled by default. Notice that lockFloor(int) also enables the indoor-only lock (and it then cannot be disabled with this method as long as the floor level is locked)
        Parameters:
        locked - boolean value indicating whether to enable or disable the indoor-only lock.
        See Also:
        lockFloor(int)

      • requestWayfindingUpdates

        public abstract void requestWayfindingUpdates​(@NonNull
                                              IALatLngFloorCompatible to,
                                              @NonNull
                                              PendingIntent pendingIntent)
        Start requesting wayfinding updates.

        Parameters:
        to - Wayfinding destination
        pendingIntent - a IAWayfindingListener object to register Request wayfinding updates that are delivered to an application component specified by a PendingIntent. The wayfinding update is in the extras of the Intent. Use IARoute.from(Intent) to obtain the update.

        Please see the Android documentation how to configure the PendingIntent.

      • removeWayfindingUpdates

        public abstract void removeWayfindingUpdates()
        Removes wayfinding request.

      • removeWayfindingUpdates

        public abstract void removeWayfindingUpdates​(@NonNull
                                             PendingIntent pendingIntent)
        Removes all updates for the specific pendingIntent. After call to this method, wayfinding events will no longer be delivered to the application component.
        Parameters:
        pendingIntent - a PendingIntent that will no longer need wayfinding events.
        Throws:
        IllegalArgumentException - if pendingIntent is null.
        IllegalStateException - if called after destroy() has been called

      • requestArUpdates

        @Restricted
@Beta
public abstract IAARSession requestArUpdates()
        Start AR fusion updates. NOTE! To enable AR features, please contact IndoorAtlas sales.
        Returns:
        AR API object. Should be cleaned up by calling its destroy method when it is no longer used

      • requestRadioScanUpdates

        @Restricted
@Beta
public abstract void requestRadioScanUpdates​(@NonNull
                                             IARadioScanRequest request,
                                             @NonNull
                                             IARadioScanListener listener)
        Request radio scan updates. Whenever IA SDK internally scans beacons or wifis, you can register a listener via with to receive the scan results. Only one listener can be active at same time and a new request will override any old one. The callback is delivered via main thread by default. NOTE! To enable the callback, please contact IndoorAtlas support.
        Parameters:
        request - configuration for which callbacks to enable
        listener - via with to provide scan callbacks

      • requestRadioScanUpdates

        @Restricted
@Beta
public abstract void requestRadioScanUpdates​(@NonNull
                                             IARadioScanRequest request,
                                             @NonNull
                                             IARadioScanListener listener,
                                             Looper looper)
        Request radio scan updates. Whenever IA SDK internally scans beacons or wifis, you can register a listener via with to receive the scan results. Only one listener can be active at same time and a new request will override any old one. NOTE! To enable the callback, please contact IndoorAtlas support.
        Parameters:
        request - configuration for which callbacks to enable
        listener - via with to provide scan callbacks
        looper - a looper via with to deliver callbacks or null to use the main thread.

      • removeRadioScanUpdates

        @Restricted
@Beta
public abstract void removeRadioScanUpdates()
        Stop listening to radio scans.

      • finishRecordingBinaryLog

        @Beta
public abstract void finishRecordingBinaryLog​(IALocationManager.Consumer<byte[]> consumer)
        Finish recording binary log data. This method is meant for enterprise users to share debug data with IndoorAtlas support. If your API key already has data storage enabled, there is no need to use this method.