Package 

Class BeaconManager

  • 
public class BeaconManager

    A class used to set up interaction with beacons and start/stop beacon ranging/monitoring.

    • Method Detail

      • setForegroundScanPeriod

         void setForegroundScanPeriod(long p)

        Sets the duration in milliseconds of each Bluetooth LE scan cycle to look for beacons. This function is used to setup the period before calling bind or when switching between background/foreground. To have it effect on an already running scan (when the next cycle starts), call updateScanPeriods

      • setForegroundBetweenScanPeriod

         void setForegroundBetweenScanPeriod(long p)

        Sets the duration in milliseconds between each Bluetooth LE scan cycle to look for beacons. This function is used to setup the period before calling bind or when switching between background/foreground. To have it effect on an already running scan (when the next cycle starts), call updateScanPeriods

      • setBackgroundScanPeriod

         void setBackgroundScanPeriod(long p)

        Sets the duration in milliseconds of each Bluetooth LE scan cycle to look for beacons. This function is used to setup the period before calling bind or when switching between background/foreground. To have it effect on an already running scan (when the next cycle starts), call updateScanPeriods

      • setBackgroundBetweenScanPeriod

         void setBackgroundBetweenScanPeriod(long p)

        Sets the duration in milliseconds spent not scanning between each Bluetooth LE scan cycle when no ranging/monitoring clients are in the foreground

      • setDebug

         static void setDebug(boolean debug)

        Set to true if you want to show library debugging.

        Parameters:
        debug - True turn on all logs for this library to be printed out to logcat.

      • setRegionExitPeriod

         static void setRegionExitPeriod(long regionExitPeriod)

        Set region exit period in milliseconds

      • getInstanceForApplication

        @NonNull() static BeaconManager getInstanceForApplication(@NonNull() Context context)

        An accessor for the singleton instance of this class. A context must be provided, but if you need to use it from a non-Activity or non-Service class, you can attach it to another singleton or a subclass of the Android Application class.

      • isMainProcess

         boolean isMainProcess()

        * Determines if this BeaconManager instance is associated with the main application process that hosts the user interface. This is normally true unless the scanning service or another servide is running in a separate process.

      • isScannerInDifferentProcess

         boolean isScannerInDifferentProcess()

        Determines if this BeaconManager instance is not part of the process hosting the beacon scanning service. This is normally false, except when scanning is hosted in a different process. This will always return false until the scanning service starts up, at which time it will be known if it is in a different process.

      • setScannerInSameProcess

         void setScannerInSameProcess(boolean isScanner)

        Reserved for internal use by the library.

      • checkAvailability

         boolean checkAvailability()

        Check if Bluetooth LE is supported by this Android device, and if so, make sure it is enabled.

      • bind

        @Deprecated() void bind(@NonNull() BeaconConsumer consumer)

        Binds an Android Activity or Service to the BeaconService. The Activity or Service must implement the beaconConsumer interface so that it can get a callback when the service is ready to use.

        Parameters:
        consumer - the Activity or Service that will receive the callback when the service is ready.

      • handleStategyFailover

         void handleStategyFailover()

        Internal library use only. This will trigger a failover from the intent scan strategy to jobs or a foreground service

      • unbind

        @Deprecated() void unbind(@NonNull() BeaconConsumer consumer)

        Unbinds an Android Activity or Service to the BeaconService. This should typically be called in the onDestroy() method.

        Parameters:
        consumer - the Activity or Service that no longer needs to use the service.

      • isAnyConsumerBound

         boolean isAnyConsumerBound()

        Tells you if the any beacon consumer is bound to the service

      • setBackgroundMode

        @Deprecated() void setBackgroundMode(boolean backgroundMode)

        This method notifies the beacon service that the application is either moving to background mode or foreground mode. When in background mode, BluetoothLE scans to look for beacons are executed less frequently in order to save battery life. The specific scan rates for background and foreground operation are set by the defaults below, but may be customized. When ranging in the background, the time between updates will be much less frequent than in the foreground. Updates will come every time interval equal to the sum total of the BackgroundScanPeriod and the BackgroundBetweenScanPeriod.

        Parameters:
        backgroundMode - true indicates the app is in the background

      • setBackgroundModeInternal

         void setBackgroundModeInternal(boolean backgroundMode)

        Reserved for internal use by the library.

      • setEnableScheduledScanJobs

         void setEnableScheduledScanJobs(boolean enabled)

        Configures using a `ScanJob` run with the `JobScheduler` to perform scans rather than using a long-running `BeaconService` to do so. Calling with true on devices older than Android L (5.0) will not apply the change as the JobScheduler is not available. This value defaults to true on Android O+ and false on devices with older OS versions. Accepting the default value of false is recommended on Android N and earlier because otherwise beacon scans may be run only once every 15 minutes in the background, and no low power scans may be performed between scanning cycles. Setting this value to false will disable ScanJobs when the app is run on Android 8+, which can prohibit delivery of callbacks when the app is in the background unless the scanning process is running in a foreground service. This method may only be called if ranging or monitoring have not yet been started otherwise an `IllegalStateException` is thrown.

      • setRangeNotifier

        @Deprecated() void setRangeNotifier(@Nullable() RangeNotifier notifier)

        Specifies a class that should be called each time the BeaconService gets ranging data, which is nominally once per second when beacons are detected.

        IMPORTANT: Only one RangeNotifier may be active for a given application. If two different activities or services set different RangeNotifier instances, the last one set will receive all the notifications.
        Parameters:
        notifier - The RangeNotifier to register.

      • addRangeNotifier

         void addRangeNotifier(@NonNull() RangeNotifier notifier)

        Specifies a class that should be called each time the BeaconService gets ranging data, which is nominally once per second when beacons are detected.

        Permits to register several RangeNotifier objects. The notifier must be unregistered using (@link #removeRangeNotifier)
        Parameters:
        notifier - The RangeNotifier to register.

      • setMonitorNotifier

        @Deprecated() void setMonitorNotifier(@Nullable() MonitorNotifier notifier)

        Specifies a class that should be called each time the BeaconService sees or stops seeing a Region of beacons.

        IMPORTANT: Only one MonitorNotifier may be active for a given application. If two different activities or services set different MonitorNotifier instances, the last one set will receive all the notifications.
        Parameters:
        notifier - The MonitorNotifier to register.

      • setRegionStatePersistenceEnabled

         void setRegionStatePersistenceEnabled(boolean enabled)

        Turns off saving the state of monitored regions to persistent storage so it is retained over app restarts. Defaults to enabled. When enabled, there will not be an "extra" region entry event when the app starts up and a beacon for a monitored region was previously visible within the past 15 minutes. Note that there is a limit to 50 monitored regions that may be persisted. If more than 50 regions are monitored, state is not persisted for any.

        Parameters:
        enabled - true to enable the region state persistence, false to disable it.

      • requestStateForRegion

         void requestStateForRegion(@NonNull() Region region)

        Requests the current in/out state on the specified region. If the region is being monitored, this will cause an asynchronous callback on the `MonitorNotifier`'s `didDetermineStateForRegion` method. If it is not a monitored region, it will be ignored.

      • startRangingBeaconsInRegion

        @Deprecated() void startRangingBeaconsInRegion(@NonNull() Region region)

        Tells the BeaconService to start looking for beacons that match the passed Region object, and providing updates on the estimated mDistance every seconds while beacons in the Region are visible. Note that the Region's unique identifier must be retained to later call the stopRangingBeaconsInRegion method.

      • startRangingBeacons

         void startRangingBeacons(@NonNull() Region region)

        Tells the BeaconService tteo start looking for beacons that match the passed Region object, and providing updates on the estimated mDistance every seconds while beacons in the Region are visible. Note that the Region's unique identifier must be retained to later call the stopRangingBeaconsInRegion method. This is an auto-binding variant of the call that relies on a single beacon consumer. Do not combine calls to this method with manual calls to bind() and unbind().

      • stopRangingBeacons

         void stopRangingBeacons(@NonNull() Region region)

        Tells the library to stop looking for beacons that match the passed Region object and providing distance information for them.

      • applySettings

         void applySettings()

        Call this method if you are running the scanner service in a different process in order to synchronize any configuration settings, including BeaconParsers to the scanner

      • startMonitoringBeaconsInRegion

        @Deprecated() void startMonitoringBeaconsInRegion(@NonNull() Region region)

        Tells the BeaconService to start looking for beacons that match the passed Region object. Note that the Region's unique identifier must be retained to later call the stopMonitoringBeaconsInRegion method.

      • startMonitoring

         void startMonitoring(@NonNull() Region region)

        Tells the BeaconService to start looking for beacons that match the passed Region object. Note that the Region's unique identifier must be retained to later call the stopMonitoringBeaconsInRegion method.

      • stopMonitoringBeaconsInRegion

        @Deprecated() void stopMonitoringBeaconsInRegion(@NonNull() Region region)

        Tells the library to stop looking for beacons that match the passed Region object. Note that the Region's unique identifier is used to match it to an existing monitored Region.

      • stopMonitoring

         void stopMonitoring(@NonNull() Region region)

        Tells the library to stop looking for beacons that match the passed Region object. Note that the Region's unique identifier is used to match it to an existing monitored Region.

      • updateScanPeriods

         void updateScanPeriods()

        Updates an already running scan with scanPeriod/betweenScanPeriod according to Background/Foreground state. Change will take effect on the start of the next scan cycle.

      • setUseTrackingCache

         static void setUseTrackingCache(boolean useTrackingCache)

        Allow the library to use a tracking cache

      • setMaxTrackingAge

         void setMaxTrackingAge(int maxTrackingAge)

        Set the period of time, in which a beacon did not receive new measurements

        Parameters:
        maxTrackingAge - in milliseconds

      • isAndroidLScanningDisabled

         static boolean isAndroidLScanningDisabled()

        Determines if Android L Scanning is disabled by user selection

      • setAndroidLScanningDisabled

         static void setAndroidLScanningDisabled(boolean disabled)

        Allows disabling use of Android L BLE Scanning APIs on devices with API 21+ If set to false (default), devices with API 21+ will use the Android L APIs to scan for beacons

      • setManifestCheckingDisabled

         static void setManifestCheckingDisabled(boolean disabled)

        Allows disabling check of manifest for proper configuration of service. Useful for unit testing

      • enableForegroundServiceScanning

         void enableForegroundServiceScanning(Notification notification, int notificationId)

        Configures the library to use a foreground service for bacon scanning. This allows nearly constant scanning on most Android versions to get around background limits, and displays an icon to the user to indicate that the app is doing something in the background, even on Android 8+. This will disable the user of the JobScheduler on Android 8 to do scans. Note that this method does not by itself enable constant scanning. The scan intervals will work as normal and must be configurd to specific values depending on how often you wish to scan.

        Parameters:
        notification - - the notification that will be displayed when beacon scanning is active, along with the icon that shows up in the status bar.

      • shutdownIfIdle

         boolean shutdownIfIdle()

        When using auto-bind, this method will shut down the foreground service or scheduled jobs needed to keep scanning going if there are no longer any ranged or monitored regions.