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 switchingbetween background/foreground. To have it effect on an already running scan (when the nextcycle 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 switchingbetween background/foreground. To have it effect on an already running scan (when the nextcycle 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 switchingbetween background/foreground. To have it effect on an already running scan (when the nextcycle 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.

      • replaceSettings

         void replaceSettings(Settings settingsDelta)

        Applies new library settings as a single transaction and restart scanning if needed.Any settings field snot specified in the passed settings object will revert to defaults.

        Parameters:
        settingsDelta - the settings to be applied

      • adjustSettings

         void adjustSettings(Settings settingsDelta)

        Applies a delta of library settings as a single transaction and restart scanning if needed.Any settings field snot specified in the passed settings object are unchanged.

        Parameters:
        settingsDelta - the settings to be applied

      • revertSettings

         void revertSettings()

        Resets library settings to defaults as a single transaction and restarts scanning if needed.

      • getActiveSettings

         AppliedSettings getActiveSettings()

        Returns a copy of the active settings in use by the library. The object returned is a copyand making changes on it will have no effect without a new call to set the settings.

      • 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-Activityor 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 thathosts the user interface. This is normally true unless the scanning service or another servideis running in a separate process.

      • isScannerInDifferentProcess

         boolean isScannerInDifferentProcess()

        Determines if this BeaconManager instance is not part of the process hosting the beacon scanningservice. 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 beknown 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. TheActivity or Service must implement the beaconConsumer interface sothat 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:a) the intent scan strategy to jobs or a foreground serviceb) the job scheduler (running on fallback) to the foreground service

      • unbind

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

        Unbinds an Android Activity or Service to the BeaconService. This shouldtypically 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 backgroundmode or foreground mode. When in background mode, BluetoothLE scans to look for beacons areexecuted less frequently in order to save battery life. The specific scan rates forbackground 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 inthe foreground. Updates will come every time interval equal to the sum total of theBackgroundScanPeriod 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 along-running `BeaconService` to do so.Calling with true on devices older than Android L (5.0) will not apply the changeas 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 becauseotherwise beacon scans may be run only once every 15 minutes in the background, and no lowpower scans may be performed between scanning cycles.Setting this value to false will disable ScanJobs when the app is run on Android 8+, whichcan prohibit delivery of callbacks when the app is in the background unless the scanningprocess 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 rangingdata, which is nominally once per second when beacons are detected.

        IMPORTANT: Only one RangeNotifier may be active for a given application. If two differentactivities or services set different RangeNotifier instances, the last one set will receiveall 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 rangingdata, 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 seesor stops seeing a Region of beacons.

        IMPORTANT: Only one MonitorNotifier may be active for a given application. If two differentactivities or services set different MonitorNotifier instances, the last one set will receiveall 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 overapp restarts. Defaults to enabled. When enabled, there will not be an "extra" region entryevent when the app starts up and a beacon for a monitored region was previously visiblewithin the past 15 minutes. Note that there is a limit to 50 monitored regions that may bepersisted. 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 passedRegion object, and providing updates on the estimated mDistance every seconds whilebeacons in the Region are visible. Note that the Region's unique identifier must be retained tolater call the stopRangingBeaconsInRegion method.

      • startRangingBeacons

         void startRangingBeacons(@NonNull() Region region)

        Tells the BeaconService tteo start looking for beacons that match the passedRegion object, and providing updates on the estimated mDistance every seconds whilebeacons in the Region are visible. Note that the Region's unique identifier must be retained tolater call the stopRangingBeaconsInRegion method.This is an auto-binding variant of the call that relies on a single beacon consumer. Do notcombine 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 passedRegion object and providing distance information for them.

      • applySettings

         void applySettings()

        Call this method in order to apply your settings changes to the already running scanning process

      • startMonitoringBeaconsInRegion

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

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

      • startMonitoring

         void startMonitoring(@NonNull() Region region)

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

      • stopMonitoringBeaconsInRegion

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

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

      • stopMonitoring

         void stopMonitoring(@NonNull() Region region)

        Tells the library to stop looking for beacons that match the passedRegion object. Note that the Region's unique identifier is used to match it toan 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 newmeasurements

        Parameters:
        maxTrackingAge - in milliseconds

      • isAndroidLScanningDisabled

         static boolean isAndroidLScanningDisabled()

        Determines if Android L Scanning is disabled by user selection

      • setAndroidLScanningDisabled

        @Deprecated() 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 toscan for beacons

      • setManifestCheckingDisabled

         static void setManifestCheckingDisabled(boolean disabled)

        Allows disabling check of manifest for proper configuration of service. Useful for unittesting

      • enableForegroundServiceScanning

         void enableForegroundServiceScanning(Notification notification, int notificationId)

        Configures the library to use a foreground service for bacon scanning. This allows nearlyconstant scanning on most Android versions to get around background limits, and displays anicon to the user to indicate that the app is doing something in the background, even onAndroid 8+. This will disable the user of the JobScheduler on Android 8 to do scans. Notethat this method does not by itself enable constant scanning. The scan intervals will workas 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.

      • retryForegroundServiceScanning

         void retryForegroundServiceScanning()

        Because Android 12 blocks starting foreground services under some conditions, the librarymay fall back to using the Job Scheduler to schedule scans in these cases. When thishappens, it may be possible to start a foreground service at a later time once aqualifying event happens. The library will automatically do this if the app comes tothe foreground (one example of a qualifying event.) But the app itself may detect otherqualifying events defined here:https://developer.android.com/guide/components/foreground-services#background-start-restrictionsIf the app detects one of these events and wants to retry starting foreground servicescanning, call this method.Calling this method does not guarantee that the retry will succeed, and if it does not,the Job Scheduler will continue to be used.

      • foregroundServiceStartFailed

         boolean foregroundServiceStartFailed()

        Returns whether Android has blocked using a requsted foreground service to do scans.

      • shutdownIfIdle

         boolean shutdownIfIdle()

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