BeaconDetectBackground (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

This content has been translated automatically. Click here to view the French version.

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

// Dans un musée, on souhaite déclencher la lecture (resp. l'arrêt) d'un audio-guide 
// lorsque le visiteur entre (resp. sort) d'une salle. 
// On associe à chaque balise Beacon le même UUID correspondant au musée et 
// un numéro Major correspondant à la salle dans laquelle la balise sera positionnée. 
// On dispose une balise Beacon à chaque entrée de chaque salle du musée. 
// L'application doit appeler la fonction BeaconDétecteEnArrièrePlan 
// avec un tableau de variables BeaconGroupe correspondant à chacune des salles du musée. 

// La procédure callback passée en paramètre à la fonction sera appelée
// à chaque entrée ou sortie d'une pièce et fournira les informations 
// du groupe de beacons détecté permettant ainsi
// de piloter l'audio-guide pour lire la piste audio correspondante.

// UUID du musée
sUUID is string = "f4231ab6-5ef2-6c99-4229-af6c72e0446e"
// Création d'une variable beaconGroupe par salle
groupeSalle1 is beaconGroup
groupeSalle1.UUID = sUUID
groupeSalle1.Major = 1
groupeSalle2 is beaconGroup
groupeSalle2.UUID = sUUID
groupeSalle2.Major = 2
groupeSalle3 is beaconGroup
groupeSalle3.UUID = sUUID
groupeSalle3.Major = 3
groupeSalle4 is beaconGroup
groupeSalle4.UUID = sUUID
groupeSalle4.Major = 4
// Lancement de la détection
tabGroupeBeacon is array of beaconGroup = [groupeSalle1, ...
    groupeSalle2, groupeSalle3, groupeSalle4]
// La procédure ProcDétection sera exécuté chaque fois que le mobile entrera 
// ou sortira de la zone définie par chaque groupe de beacons. 
BeaconDetectBackground(tabGroupeBeacon, ProcDétection)

PROCEDURE ProcDétection(Groupe is beaconGroup, nType is int)

IF nType = bdbLeave THEN 
	// Arrêt de la piste en cours
	RETURN
END

IF nType = bdbEnter THEN
	SWITCH Groupe.Major
		CASE 1
		// Lecture de la piste de la salle 1
		CASE 2
		// Lecture de la piste de la salle 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.

Attention To save battery power, the device periodically searches for nearby tags at intervals of 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-executing the application has no effect on the operation of the mobile detection service.

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 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 functions are only available on iOS11 or later.

Bluetooth Low Energy

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

Required permissions

This function changes the permissions required by the application.
Permission required: ACCESS_COARSE_LOCATION: Allows the application to obtain the approximate position of the device.

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 PROCEDURE Callback(p is Permission)
	IF p.Accordé THEN
		// Utilisation possible des fonctions nécessitant la localisation en arrière-plan
	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.
This function changes 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: wd300android.aar