Xamarin.Essentials: The Version Tracking Guide
Version tracking in mobile and UWP apps is incredibly easy with Xamarin.Essentials. The Nuget package even lets us get information such as whether the app is running for the first time.
You might use this information to collect anonymous usage statistics, display it to the user or alter the logic flow of your app somehow. I'm not here to judge, just to provide you with a guide on how to collect this information using Xamarin.Essentials.
Add Xamarin.Essentials
Start by making sure that the Xamarin.Essentials Nuget package has been added to your project.
Then add a reference to the Xamarin.Essentials namespace at the top of the file where the code will be located.
using Xamarin.Essentials;
Get the Current Build Number
We can get the current build number as a string by calling the following code. Note that the build "number" is whatever you have configured in the build step, and it's possible for this to be a string. Unless you know that the value will always be an integer, think about whether you should convert it to an Integer.
private static string GetCurrentBuild()
{
return VersionTracking.CurrentBuild;
}
Get the Current Version
Pulling the current version number that is installed is almost exactly the same as how you get the build number.
private static string GetCurrentVersion()
{
return VersionTracking.CurrentVersion;
}
Get the First Installed Build on this Device
End users may have updated the application at some point. We can find out which build of our application was first installed by the user.
private static string GetFirstInstalledBuild()
{
return VersionTracking.FirstInstalledBuild;
}
Get the First Installed Version on this Device
Again, getting the first installed version is very similar to getting the first installed build.
private static string GetFirstInstalledVersion()
{
return VersionTracking.FirstInstalledVersion;
}
Check if this is the First Launch on this Device
You can check if this is the first launch of your application on this device with the following code.
private static bool GetIsFirstLaunchEver()
{
return VersionTracking.IsFirstLaunchEver;
}
Check if this is the First Launch for the Current Build
If the user has updated the application, you can check if this is the first launch for this build. If this is true, then you may need to perform some kind of validation or migration on the saved data to make sure that it's compatible with the current version
private static bool GetIsFirstLaunchForCurrentBuild()
{
return VersionTracking.IsFirstLaunchForCurrentBuild;
}
Check if this is the First Launch for the Current Version
Checking if this is the first launch of the current version is almost the same as checking the build number.
private static bool GetIsFirstLaunchForCurrentVersion()
{
return VersionTracking.IsFirstLaunchForCurrentVersion;
}
Get the Previous Build Number
We can get the previous build number.
private static string GetPreviousBuild()
{
return VersionTracking.PreviousBuild;
}
Get the Previous Version Number
We can get the previous version number.
private static string GetPreviousVersion()
{
return VersionTracking.PreviousVersion;
}
Get the Version History from Your App on this Device
The following code lets us get a full version history of the application on this device.
private static IEnumerable<string> GetVersionHistory()
{
return VersionTracking.VersionHistory;
}
How to use this information
Build information is anonymous so under most laws its perfectly fine to collect and store this data from your users, once they have agreed to provide anonymous usage data. Collecting this data alongside other personally identifiable data may require additional approval from your users, depending on the location of your business and users.
If in doubt, ask the user for approval.
Also remember that the methods that get the first installed build & version may be inaccurate if the user has cleared the application data at some point. The same thing goes for the version history.