App First Run Detection with Xamarin.Essentials

James Montemagno

One common scenario that developers often need to integrate into an app, is showing a prompt when an app is launched for the first time. This could be to display a disclaimer or to walk users through the functionality of the app. This can be done on first launch of the app. Even after install or for a specific version. Using Xamarin.Essentials helps integrate this functionality with a just few lines of code.

First Run Preferences

A way to determine the first run is to leverage the built-in preferences API. This stores a boolean value that can be checked at runtime. For example, create a Settings class with a FirstRun property set the default value to true:

public static class Settings
  public static bool FirstRun
      get => Preferences.Get(nameof(FirstRun), true);
      set => Preferences.Set(nameof(FirstRun), value);

Next, check the value at startup to confirm if the value is true. Then perform an action and set the value to false:

   // Perform an action such as a "Pop-Up".
   Settings.FirstRun = false;

This is a great approach. That preference will persist for as long as the app continues to install. The downside is the “one-and-done” approach and would be difficult to check for specific versions. There are many things that you can do with preferences! Be sure to checkout the full documentation and short video on it:

Version Tracking

The built-in version tracking API offers rich functionality to detect first run. As well as for specific versions that the user is running. With this API, it is important to initialize VersionTracking early-on in your application. Version Tracking such as the AppDelegate, MainActivity, or the App constructor.


After this is initialized, we can perform multiple checks to display different information:

  // Display pop-up alert for first launch
else if(VersionTracking.IsFirstLaunchForCurrentVersion)
  // Display update notification for current version (1.0.0)
else if(VersionTracking.IsFirstLaunchForCurrentBuild)
  // Display update notification for current build number (2)

As you can see, there is a lot of powerful functionality built into this class. And this is just the beginning. It can also be used to check the current build, version number, history, and more! Check out the full documentation to learn more about Xamarin.Essentials or watch the quick overview video:

There you have it. Several great approaches to check if your app is being booted-up. For the very first run, or for a specific version. All using Xamarin.Essentials!


Discussion is closed. Login to edit/delete existing comments.

  • Takudzwa Kain Mawarire 0

    You might need to change your article’s title, it reads “first run dedection… “

    • James MontemagnoMicrosoft employee 0


  • Vadim Palagin 0

    Thanks James!

  • Emmanuel Adebiyi 0

    So nice! Didn’t know this existed

  • VahidShir 0

    When there’s a foreground service, the IsFirstLaunchForCurrentBuild or IsFirstLaunchForCurrentVersion don’t behave correctly.

Feedback usabilla icon