How to use a Background Geolocation in XAF Mobile

This example demonstrates how to take advantage of a mobile device positioning system in your XAF mobile application using the Cordova Background Geolocation plugin and Cordova Device plugin . Additionally, you will learn how to access the PhoneGap config file (regular XML file) and add the plugin to your application.

Scenario:
You want to automatically track movements of an XAF mobile application user and display the user's route on the map, e.g., in a separate administrative XAF Web application:




Your feedback is needed!
This is not an official feature of our Mobile UI (CTP) and our API may change in future release cycles. We are publishing this article prior to the 17.2 release to collect early user feedback and improve overall functionality. We would appreciate your thoughts on this feature once you've had the opportunity to review it. Please report any issues, missing capabilities or suggestions in separate tickets in our Support Center. Thanks for your help in advance!

Prerequisites
Install any v17.1.5+ version.
The implementation steps below are given for a new application, though they can be applied to any other XAF mobile app.

Steps to implement
1. Create a new XAF solution with Web and Mobile platforms and enable the Maps Module in it.  Do not forget to specify the MapsAspNetModule > GoogleApiKey property in the Application Designer invoked for the YourSolutionName.Web/WebApplication.xx file.

2. In the YourSoltutionName.Mobile/MobileApplication.xx file, register the Cordova Background Geolocation plugin by adding required tags to the MobileApplication.AdditionalPhoneGapPlugins collection.

[C#]
usingDevExpress.ExpressApp.MobilepublicpartialclassBackgroundGeolocationMobileApplication:MobileApplication{publicBackgroundGeolocationMobileApplication(){AdditionalPhoneGapPlugins.Add(@"<plugin name=""cordova-background-geolocation-lt"" source=""npm"" spec=""2.7.3""><variable name=""LOCATION_ALWAYS_USAGE_DESCRIPTION"" value=""Background location-tracking is required"" /><variable name=""LOCATION_WHEN_IN_USE_USAGE_DESCRIPTION"" value=""Background location-tracking is required"" /><variable name=""MOTION_USAGE_DESCRIPTION"" value=""Using the accelerometer increases battery-efficiency by intelligently toggling location-tracking only when the device is detected to be moving"" /><variable name=""LICENSE"" value=""YOUR_LICENSE_KEY"" /></plugin>");AdditionalPhoneGapPlugins.Add(@"<plugin name=""cordova-plugin-device"" source=""npm"" spec=""1.1.6""></plugin>");// ...

[VB.NET]
Imports Microsoft.VisualBasicImports DevExpress.ExpressApp.MobilePartialPublicClass BackgroundGeolocationMobileApplicationInherits MobileApplicationPublicSubNew()
        AdditionalPhoneGapPlugins.Add("<plugin name=""cordova-background-geolocation-lt"" source=""npm"" spec=""2.7.3"">"& ControlChars.CrLf &"    <variable name=""LOCATION_ALWAYS_USAGE_DESCRIPTION"" value=""Background location-tracking is required"" />"& ControlChars.CrLf &"    <variable name=""LOCATION_WHEN_IN_USE_USAGE_DESCRIPTION"" value=""Background location-tracking is required"" />"& ControlChars.CrLf &"    <variable name=""MOTION_USAGE_DESCRIPTION"" value=""Using the accelerometer increases battery-efficiency by intelligently toggling location-tracking only when the device is detected to be moving"" />"& ControlChars.CrLf &"    <variable name=""LICENSE"" value=""YOUR_LICENSE_KEY"" />"& ControlChars.CrLf &"    </plugin>")
        AdditionalPhoneGapPlugins.Add("<plugin name=""cordova-plugin-device"" source=""npm"" spec=""1.1.6""></plugin>")' ...

Take note of the line which adds the "LICENSE" tag. If you have a license key (refer to the corresponding remark in the README file), uncomment this code and replace the YOUR_LICENSE_KEY placeholder with your own key .

3. In the YourSolutionName.Module project, copy the BackgroundGeolocation.Module\BusinessObjects\DeviceInfo.xx file to the BusinessObjects folder.
This file contains business classes used to store background geolocation data received from mobile clients. You may want to put these classes into separate files according to your code rules.

4. In the YourSolutionName.Mobile project, create a new Geolocation folder and copy the several code files below into it as per the instructions below.
4.1. Copy the BackgroundGeolocation.Mobile\Geolocation\GeolocationScript.js file and include it in the project. Change the Build Action property for this file to Embedded Resource. This code initializes the Cordova Background Geolocation plugin with default settings. Feel free to modify it according to your needs. More information about configuring options can be found in the project's github repository.

4.2. Copy the BackgroundGeolocation.Mobile\Geolocation\GeolocationJsonObject.xx file and include it in the project.
These classes are used to deserialize JSON data set by mobile applications to the Geolocation Service.

4.3. Copy the BackgroundGeolocation.Mobile\Geolocation\GeolocationHttpHandler.xx file and include it in the project. 
The Background Geolocation plugin will send data to this service. The service is intended to save the device information to the database. It uses the connection string from the application configuration file (Web.config).

To enable the HTTP handler added on the previous step, add the following line to the configuration/system.webServer/handlers section of the YourSolutionName.Mobile/Web.config file (you may need to change the type attribute value and specify the namespace qualified name of the GeolocationHttpHandler class declared in your project:

[XML]
<addname="Geolocation"verb="GET,POST"path="GeolocationProcessingService.svc"type="YourSolutionName.Mobile.GeolocationHttpHandler"/>

5.  In the YourSoltutionName.Mobile/MobileApplication.xx file, register the GeolocationScript.js code (copied on step #4.1) using the MobileApplication.RegisterClientScriptOnApplicationStart method so that this script executes when the mobile application starts up on the device. The code snippet below demonstrates how to implement the ReadResource and ReadResourceString methods required to load the code from the embedded resource into a String variable (you can find this code in the BackgroundGeolocation.Mobile/MobileApplication.xx file of the sample project): 

[C#]
publicBackgroundGeolocationMobileApplication(){// ...stringgeolocationScript=ReadResourceString("BackgroundGeolocation.Mobile.Geolocation.GeolocationScript.js");RegisterClientScriptOnApplicationStart("GeolocationScript",geolocationScript);}publicstaticbyte[]ReadResource(stringresourceName){byte[]buffer=null;using(Streamstream=Assembly.GetExecutingAssembly().GetManifestResourceStream(resourceName)){if(stream!=null){buffer=newbyte[stream.Length];stream.Read(buffer, 0,(int)stream.Length);}}returnbuffer;}publicstaticstringReadResourceString(stringresourceName){byte[]resourceBytes=ReadResource(resourceName);returnEncoding.UTF8.GetString(resourceBytes).Replace("\r\n","\\r\\n");}

[VB.NET]
PublicSubNew()' ...Dim geolocationScript AsString = ReadResourceString("GeolocationScript.js")
    RegisterClientScriptOnApplicationStart("GeolocationScript", geolocationScript)EndSubPublicSharedFunction ReadResource(ByVal resourceName AsString) AsByte()Dim buffer() AsByte = NothingUsing stream As Stream = System.Reflection.Assembly.GetExecutingAssembly().GetManifestResourceStream(resourceName)If stream IsNot NothingThen
            buffer = NewByte(stream.Length - 1){}
            stream.Read(buffer, 0, CInt(stream.Length))EndIfEndUsingReturn bufferEndFunctionPublicSharedFunction ReadResourceString(ByVal resourceName AsString) AsStringDim resourceBytes() AsByte = ReadResource(resourceName)Return Encoding.UTF8.GetString(resourceBytes).Replace(ControlChars.CrLf, "\r\n")EndFunction

The value passed to the ReadResourceString method consists of two parts in C# projects: the default assembly namespace ("BackgroundGeolocation.Mobile") and the path to the resource file ("Geolocation.GeolocationScript.js"). The first part may be different in your project. In VB.NET projects, the resource name will be much simpler: "GeolocationScript.js". 

6. In the YourSolutionName.Module.Web project, install the Newtonsoft.Json NuGet package and copy the BackgroundGeolocation.Module.Web\Controllers\DisplayGeolocationController.xx file to the Controllers folder.
This controller is intended to draw the client's route based on location points.

7. Build and deploy your mobile application following the steps described in the Install the Application to a Smartphone  help article, and ensure that the Geolocation services are enabled in the mobile device settings.
Once you get your mobile app running on your actual device, wait a few minutes and then run the Web version of your XAF application. Open the DeviceInfo List View, and you will see a record containing your mobile device information. If you click the ListView record, you will be navigated to the DetailView that contains the Map demonstrating the route tracked by the Background Geolocation module.

See Also:
eXpressApp Framework > Getting Started > XAF Mobile (CTP) Tutorial
How to: Use a Custom Plugin in a Mobile Application

XAF Mobile - Overview Video
FAQ: New XAF HTML5/JavaScript mobile UI (CTP)
Using Maps in a Mobile Application 
How to send push notifications to the XAF Mobile application using Azure Notifications Hub
How to use a Barcode Scanner in XAF Mobile