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);}
[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)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
Question Comments
Added By:
Roman Max at:
8/22/2017 2:27:38 PM Hi, do you mind posting Project ZIP file here? Somehow having difficulty running it.Added By:
Uriah (DevExpress Support) at:
8/22/2017 11:11:51 PM Hi Roman,
I've created a separate ticket on your behalf (T548156: Provide project ZIP file for T540129 example). It has been placed in our processing queue and will be answered shortly.
Added By:
Scott Gross at:
11/2/2017 1:21:38 PM heading and altitude needs to be changed to double instead of int. I was getting that exception on the HttpHandler.Added By:
Uriah (DevExpress Support) at:
11/14/2017 2:18:18 AM Thank you, Scott! We have updated the example accordingly.