[Proposal] Add an API to Track App Versions (#124)

* Add an API to track app versions

* Using the new Preferences model

* Made a few changes and updated the sample

* Added docs

Caboodle/VersionTracking/VersionTracking.shared.cs

@@ -0,0 +1,118 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace Microsoft.Caboodle
+{
+    public static class VersionTracking
+    {
+        const string versionTrailKey = "VersionTracking.Trail";
+        const string versionsKey = "VersionTracking.Versions";
+        const string buildsKey = "VersionTracking.Builds";
+
+        static readonly string sharedName = $"{AppInfo.PackageName}.caboodle";
+
+        static Dictionary<string, List<string>> versionTrail;
+
+        static VersionTracking()
+        {
+            IsFirstLaunchEver = !Preferences.ContainsKey(versionsKey, sharedName) || !Preferences.ContainsKey(buildsKey, sharedName);
+            if (IsFirstLaunchEver)
+            {
+                versionTrail = new Dictionary<string, List<string>>
+                {
+                    { versionsKey, new List<string>() },
+                    { buildsKey, new List<string>() }
+                };
+            }
+            else
+            {
+                versionTrail = new Dictionary<string, List<string>>
+                {
+                    { versionsKey, ReadHistory(versionsKey).ToList() },
+                    { buildsKey, ReadHistory(buildsKey).ToList() }
+                };
+            }
+
+            IsFirstLaunchForCurrentVersion = !versionTrail[versionsKey].Contains(CurrentVersion);
+            if (IsFirstLaunchForCurrentVersion)
+            {
+                versionTrail[versionsKey].Add(CurrentVersion);
+            }
+
+            IsFirstLaunchForCurrentBuild = !versionTrail[buildsKey].Contains(CurrentBuild);
+            if (IsFirstLaunchForCurrentBuild)
+            {
+                versionTrail[buildsKey].Add(CurrentBuild);
+            }
+
+            if (IsFirstLaunchForCurrentVersion || IsFirstLaunchForCurrentBuild)
+            {
+                WriteHistory(versionsKey, versionTrail[versionsKey]);
+                WriteHistory(buildsKey, versionTrail[buildsKey]);
+            }
+        }
+
+        public static bool IsFirstLaunchEver { get; private set; }
+
+        public static bool IsFirstLaunchForCurrentVersion { get; private set; }
+
+        public static bool IsFirstLaunchForCurrentBuild { get; private set; }
+
+        public static string CurrentVersion => AppInfo.VersionString;
+
+        public static string CurrentBuild => AppInfo.BuildString;
+
+        public static string PreviousVersion => GetPrevious(versionsKey);
+
+        public static string PreviousBuild => GetPrevious(buildsKey);
+
+        public static string FirstInstalledVersion => versionTrail[versionsKey].FirstOrDefault();
+
+        public static string FirstInstalledBuild => versionTrail[buildsKey].FirstOrDefault();
+
+        public static IEnumerable<string> VersionHistory => versionTrail[versionsKey].ToArray();
+
+        public static IEnumerable<string> BuildHistory => versionTrail[buildsKey].ToArray();
+
+        public static bool IsFirstLaunchForVersion(string version)
+            => CurrentVersion == version && IsFirstLaunchForCurrentVersion;
+
+        public static bool IsFirstLaunchForBuild(string build)
+            => CurrentBuild == build && IsFirstLaunchForCurrentBuild;
+
+        internal static string GetStatus()
+        {
+            var sb = new StringBuilder();
+            sb.AppendLine();
+            sb.AppendLine("VersionTracking");
+            sb.AppendLine($"  IsFirstLaunchEver:              {IsFirstLaunchEver}");
+            sb.AppendLine($"  IsFirstLaunchForCurrentVersion: {IsFirstLaunchForCurrentVersion}");
+            sb.AppendLine($"  IsFirstLaunchForCurrentBuild:   {IsFirstLaunchForCurrentBuild}");
+            sb.AppendLine();
+            sb.AppendLine($"  CurrentVersion:                 {CurrentVersion}");
+            sb.AppendLine($"  PreviousVersion:                {PreviousVersion}");
+            sb.AppendLine($"  FirstInstalledVersion:          {FirstInstalledVersion}");
+            sb.AppendLine($"  VersionHistory:                 [{string.Join(", ", VersionHistory)}]");
+            sb.AppendLine();
+            sb.AppendLine($"  CurrentBuild:                   {CurrentBuild}");
+            sb.AppendLine($"  PreviousBuild:                  {PreviousBuild}");
+            sb.AppendLine($"  FirstInstalledBuild:            {FirstInstalledBuild}");
+            sb.AppendLine($"  BuildHistory:                   [{string.Join(", ", BuildHistory)}]");
+            return sb.ToString();
+        }
+
+        static string[] ReadHistory(string key)
+            => Preferences.Get(key, null, sharedName)?.Split(new[] { '|' }, StringSplitOptions.RemoveEmptyEntries) ?? new string[0];
+
+        static void WriteHistory(string key, IEnumerable<string> history)
+            => Preferences.Set(key, string.Join("|", history), sharedName);
+
+        static string GetPrevious(string key)
+        {
+            var trail = versionTrail[key];
+            return (trail.Count >= 2) ? trail[trail.Count - 2] : null;
+        }
+    }
+}

README.md

@@ -45,6 +45,7 @@ The following cross-platform APIs are planned for our first release:
  - [x] Secure Storage
  - [x] SMS
  - [ ] Text-to-Speech
+ - [x] Version Tracking
  - [x] Vibrate
 
 ## Contributing

Samples/Caboodle.Samples/ViewModel/HomeViewModel.cs

@@ -1,11 +1,15 @@
 using System.Collections.ObjectModel;
+using System.Linq;
 using Caboodle.Samples.Model;
 using Caboodle.Samples.View;
+using Microsoft.Caboodle;
 
 namespace Caboodle.Samples.ViewModel
 {
     public class HomeViewModel : BaseViewModel
     {
+        private bool alreadyAppeared;
+
         public HomeViewModel()
         {
             Items = new ObservableCollection<SampleItem>
@@ -35,5 +39,25 @@ public HomeViewModel()
         }
 
         public ObservableCollection<SampleItem> Items { get; }
+
+        public override void OnAppearing()
+        {
+            base.OnAppearing();
+
+            if (!alreadyAppeared)
+            {
+                alreadyAppeared = true;
+
+                if (VersionTracking.IsFirstLaunchEver)
+                {
+                    DisplayAlert("Welcome to the Caboodle samples!");
+                }
+                else if (VersionTracking.IsFirstLaunchForCurrentVersion)
+                {
+                    var count = VersionTracking.VersionHistory.Count();
+                    DisplayAlert($"Welcome to the NEW Caboodle samples! You have tried {count} versions.");
+                }
+            }
+        }
     }
 }