Recently, James Montemagno published a blog post about the detection of first app run with Xamarin.Essentials. I thought it would be interesting to write a post about how the same would be accomplished with Uno Platform and UWP.
First Run Setting
The simplest way to detect the first run of your application is via a boolean setting flag. Uno Platform and UWP provide ApplicationData.Current.LocalSettings to allow storing local settings for our application. To make things simple, we wrap the setting access in a class:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| public static class Settings | |
| { | |
| private static ApplicationDataContainer _settings = ApplicationData.Current.LocalSettings; | |
| public static bool IsFirstRun | |
| { | |
| get | |
| { | |
| if (_settings.Values.TryGetValue(nameof(IsFirstRun), out var isFirstRun)) | |
| { | |
| return (bool)isFirstRun; | |
| } | |
| return true; | |
| } | |
| set => _settings.Values[nameof(IsFirstRun)] = value; | |
| } | |
| } |
The boolean flag defaults to true if no value is found in settings. Now we can easily use it to check if the application is running for the first time:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| if (Settings.IsFirstRun) | |
| { | |
| // Do something. | |
| Settings.IsFirstRun = false; | |
| } |
Version Tracking with Xamarin.Essentials
To get more flexibility for version tracking, there Xamarin.Essentials offers the version tracking API. Luckily, thanks to the magic of Uno Platform, we can use this API not only on mobile and desktop platforms, but on WebAssembly as well! You can install the preview Uno.Xamarin.Essentials NuGet package, and use the Xamarin.Essentials API for version tracking the same way as mentioned in James’ blog post without skipping a beat.
Launch Tracking with Uno.UI.Toolkit
If you prefer a more UWP-like API, you are in luck, as I created a pull request to add LaunchTracker helper to the Uno.UI.Toolkit package. Version tracking in the API is based on the Xamarin.Essentials VersionTracking, with UWP-like semantics:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| if (LaunchTracker.Current.IsFirstLaunch) | |
| { | |
| // Display pop-up alert for first launch | |
| } | |
| if (LaunchTracker.Current.IsFirstLaunchForCurrentVersion) | |
| { | |
| // Display update notification for current version (1.0.0) | |
| } | |
| if (LaunchTracker.Current.IsFirstLaunchForCurrentBuild) | |
| { | |
| // Display update notification for current build number (2) | |
| } |
I also added additional properties to track launch dates and launch count. These can be used to display recurring messages or prompts, for example for app rating.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| // Get number of times the app has been launched | |
| LaunchTracker.Current.LaunchCount | |
| // Get the time when the current instance of app has been launched | |
| LaunchTracker.Current.CurrentLaunchDate | |
| // Get the time the app has been launched last time | |
| LaunchTracker.Current.PreviousLaunchDate |
Note that if you have a UWP-only app, you can still use this API by installing the Uno.UI NuGet package, which provides the toolkit functionality for UWP.
Nice! Thank you for this contribution!
A question: in which case should we use the Uno.Xamarin.Essentials and Uno.UI?
I’m not yet very familiar with Uno Platform, but why having two solutions if both are usable in our projects?
Unless there are some limitations in using one rather than he other?
Great question! Uno Platform tries to give you many “system APIs” out of the box – like sensors, device info, etc. This specific launch tracking functionality is not part of the UWP API surface, but it seemed to me like a good fit for the Uno.UI.Toolkit, which contains additional APIs which are not covered by UWP API. The toolkit is automatically included when you install Uno.UI NuGet, so you don’t need anything additional to use it. Plus the LaunchTracker API offers the additional properties which are not directly related to versioning. But if you don’t use these, it is mostly about preference.
It is similar to if you were to use Accelerometer – you can either use the UWP API directly (Windows.Devices.Accelerometer), which is provided by Uno, or use (Uno.)Xamarin.Essentials, which will use XE implementation of this sensor on Android, iOS, UWP and use Uno Accelerometer under the covers for WASM.
I tend to prefer using the Uno.Xamarin.Essentials nuget package. It’s easier to add and maintain functionalities in smaller and dedicated packages. But that’s my personal opinion.
Thanks Martin for the clarification and the hard work !