BeaconDetectBackground (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / WLanguage functions / Communication / Beacon functions

Using a service for mobile detection
How to identify nearby Beacons?
Miscellaneous
Necessary version
Bluetooth Low Energy
Required permissions
Specific features

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

BeaconDetectBackground (Function)

In french: BeaconDétecteEnArrièrePlan

Notifies the application when the device enters or leaves the transmission range of a set of Beacons.

Example

// In a museum, we want to trigger the reading (resp. the stop) of an audio guide
// when the visitor enters into (resp. exits from) a room.
// Each Beacon is associated with the same UUID corresponding to the museum and
// a Major number corresponding to the room in which the beacon will be positioned.
// A Beacon is placed at each entrance to each room of the museum..
// The application must call the BeaconDetectBackground function
// with an array of BeaconGroup variables corresponding to each museum room.

// The callback procedure passed as parameter to the function will be called
// whenever entering into or exiting from a room and it will give information
// about the detected groupe of beacons in order to
// emulate the audio-guide to play the corresponding track.

// Museum UUID
sUUID is string = "f4231ab6-5ef2-6c99-4229-af6c72e0446e"
// Create a beaconGroup variable for each room
groupRoom1 is beaconGroup
groupRoom1.UUID = sUUID
groupRoom1.Major = 1
groupRoom2 is beaconGroup
groupRoom2.UUID = sUUID
groupRoom2.Major = 2
groupRoom3 is beaconGroup
groupRoom3.UUID = sUUID
groupRoom3.Major = 3
groupRoom4 is beaconGroup
groupRoom4.UUID = sUUID
groupRoom4.Major = 4
// Start the detection
arrBeaconGroup is array of beaconGroup = [groupRoom1, ...
groupRoom2, groupRoom3, groupRoom4)
// The ProcDetection procedure will be run whenever the mobile enters into
// or exits from the area defined by each group of beacons.
BeaconDetectBackground(arrBeaconGroup, ProcDetection)

PROCEDURE ProcDetection(Group is beaconGroup, nType is int)

IF nType = bdbLeave THEN
// Stop the current track
RETURN
END

IF nType = bdbEnter THEN
SWITCH Group.Major
CASE 1
// Read the track for room 1
CASE 2
// Read the track for room 2
...
END
END

Syntax

Starting a detection on several groups of Beacons in the background Hide the details

<Result> = BeaconDetectBackground(<Array> , <WLanguage procedure>)

<Result>: Boolean

True if the detection was started,
False otherwise. To get more details on the error, use ErrorInfo.

<Array>: Array of beaconGroup

Name of the array of beaconGroup variables that describe the group of Beacons to detect.

<WLanguage procedure>: Procedure name

Name of the WLanguage procedure ("callback") called when the device enters or leaves the transmission range of a group of Beacons.
This procedure has the following format:
PROCEDURE <Procedure name>(<Group>, <Type>)
The <Group> parameter is a beaconGroup variable that describes the group of beacons for which the device has just entered or left the transmission range.
The <Type> parameter is an integer constant corresponding to one of the following values:
bdbEnter The device entered the transmission range of a group of Beacons.
bdbLeave The device left the transmission range of a group of Beacons.
Caution:
This procedure must be a global procedure of project. Otherwise, a fatal error will occur during the call to the function.
This procedure must not access the application interface. Indeed, as the procedure can be called in background, the windows are not necessarily opened.

Starting a detection on a group of Beacons in the background Hide the details

<Result> = BeaconDetectBackground(<Group of Beacons> , <WLanguage procedure>)

<Result>: Boolean

True if the detection was started,
False otherwise. To get more details on the error, use ErrorInfo.

<Group of Beacons>: beaconGroup variable

Name of the beaconGroup variable that describes the group of Beacons to detect.

<WLanguage procedure>: Procedure name

Name of the WLanguage procedure ("callback") called when the device enters or leaves the transmission range of a group of Beacons.
This procedure has the following format:
PROCEDURE <Procedure name>(<Group>, <Type>)
The <Group> parameter is a beaconGroup variable that describes the group of beacons for which the device has just entered or left the transmission range.
The <Type> parameter is an integer constant corresponding to one of the following values:
bdbEnter The device entered the transmission range of a group of Beacons.
bdbLeave The device left the transmission range of a group of Beacons.
Caution:
This procedure must be a global procedure of project. Otherwise, a fatal error will occur during the call to the function.
This procedure must not access the application interface. Indeed, as the procedure can be called in background, the windows are not necessarily opened.

Remarks

Using a service for mobile detection

BeaconDetectBackground enables a service for mobile detection that is not linked to WINDEV Mobile. When this service is enabled, it is paused and it only detects the entries and exits into/from ranges.

Caution: To reduce battery consumption, the device searches for nearby Beacons in time intervals up to several minutes. Therefore, there may be some time between the moment the device enters (or or leaves) the transmission range of a group of Beacons, and the moment the notification appears in the application.

To stop the service for mobile detection, you must:

use the BeaconStopBackgroundDetection function.
uninstall the application.

Caution: Closing and re-running the application has no effect on the operating mode of service for mobile detection.

How to identify nearby Beacons?

The Beacon detection via BeaconDetectBackground is independent of the application lifespan (this detection is performed by a service of mobile device that is not linked to WINDEV Mobile).

If the application is in background, it will continue to receive the entry and exit notifications.
If the application is stopped then restarted in the same range, there will be no notification. It is necessary to leave the transmission range to receive an exit notification. Likewise, it is necessary to enter the range to receive an entry notification.
If the application is stopped, it will be automatically started when a group of Beacons is detected. In this case, the following processes are run:
- project initialization code,
- WLanguage procedure ("callback" procedure) passed as parameter to BeaconDetectBackground.
The first application window will not be opened.

There are several solutions to get the exact list of Beacons near the device, and to determine how far they are:

Call BeaconDetectPrecise. This function consumes a lot of energy and to save the device battery, we advise you to call it:
- in the WLanguage procedure (callback procedure) of BeaconDetectBackground.
- when starting the application.
- in the process for moving the application in the foreground.
Save the transmission range where the device is via the WLanguage procedure of BeaconDetectBackground. This storage can be performed in a file.

Miscellaneous

The active detections can be listed by BeaconListBackgroundDetection.
If a group of Beacons with the same information (UUID, major, minor) is added several times into the list of active detections, only the last addition will be taken into account.

Necessary version

Beacon management functions are only available on Android 4.3 or later (API level 18).
A fatal error occurs if the function is used with an earlier system version.
To determine the version of Android the application is running on, use SysAndroidVersion.

Beacon management functions are only available on devices with an iOS version greater than or equal to iOS 11.

Bluetooth Low Energy

The device must support the Bluetooth Low Energy technology (Bluetooth LE).

Required permissions

The call to this function modifies the permissions required by the application.
Required permission: ACCESS_COARSE_LOCATION: Allows the application to get the approximate device position.

Android 11 specific case: This function requires the ACCESS_BACKGROUND_LOCATION permission to access the device's location.
This permission allows using the function when the application is in the background.

If the application needs to use background location:

Manually add the "ACCESS_BACKGROUND_LOCATION" permission in the Android application generation wizard.
Explicitly request background location permission with PermissionRequest. For example:
PermissionRequest(permBackgroundLocation, Callback)
INTERNAL PROCÉDURE Callback(p is Permission)
IF p.Granted THEN
// Functions that require background location access can be used
END
END

A window allows users to:

allow access to the device location while the application is in the background,
allow access to the location only while the application is in use,
deny access to the location. The user can also change these permissions at any time in the Android settings.

Remarks:

Follow Google's guidelines for applications that require background location access. For more details, see https://support.google.com/googleplay/android-developer/answer/9799150. If these conditions are not met (especially user information requirements), applications may not be accepted for publication on Google Play.
The background location permission should only be requested if the location permission has been granted. Otherwise, PermissionRequest will fail.
If the option chosen by the user for the background location access request is more restrictive than the option chosen for the location access request, the application will be automatically restarted.
On devices running Android 10 or earlier, if location permission has been granted to the application, the background location permission will be granted without displaying a window.

Specific features

You have the ability to detect up to 20 groups. An error will occur if the total number of groups to detect exceeds this number.
A network access is required in order for the detection to operate properly.
If the application was started in background, it is important not to perform long processes in the WLanguage procedure (callback procedure). Indeed, the iOS system automatically ends the execution of application after ten seconds.
The call to this function modifies the permissions required by the application.
Required permissions:
- Location Always Usage Description.
- Location when in use usage description.
- Location Always And When In Use Usage Description.

Component: wd280android.aar