Merge pull request #221 from Microsoft/mandatory

mandatoryInstallMode

Author: lostintangent

CodePush.js

@@ -227,21 +227,21 @@ const sync = (() => {
 
 /*
  * The syncInternal method provides a simple, one-line experience for
- * incorporating the check, download and application of an update.
+ * incorporating the check, download and installation of an update.
  * 
  * It simply composes the existing API methods together and adds additional
  * support for respecting mandatory updates, ignoring previously failed
  * releases, and displaying a standard confirmation UI to the end-user
  * when an update is available.
  */
-async function syncInternal(options = {}, syncStatusChangeCallback, downloadProgressCallback) {  
+async function syncInternal(options = {}, syncStatusChangeCallback, downloadProgressCallback) {
+  let resolvedInstallMode;
   const syncOptions = {
-    
     deploymentKey: null,
     ignoreFailedUpdates: true,
     installMode: CodePush.InstallMode.ON_NEXT_RESTART,
+    mandatoryInstallMode: CodePush.InstallMode.IMMEDIATE,
     updateDialog: null,
-    
     ...options 
   };
 
@@ -272,7 +272,7 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
              * If the install mode is IMMEDIATE, this will not get returned as the
              * app will be restarted to a new Javascript context.
              */
-            if (syncOptions.installMode == CodePush.InstallMode.ON_NEXT_RESTART) {
+            if (resolvedInstallMode == CodePush.InstallMode.ON_NEXT_RESTART) {
               log("Update is installed and will be run on the next app restart.");
             } else {
               log("Update is installed and will be run when the app next resumes.");
@@ -300,8 +300,11 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
       syncStatusChangeCallback(CodePush.SyncStatus.DOWNLOADING_PACKAGE);
       const localPackage = await remotePackage.download(downloadProgressCallback);
 
+      // Determine the correct install mode based on whether the update is mandatory or not.
+      resolvedInstallMode = localPackage.isMandatory ? syncOptions.mandatoryInstallMode : syncOptions.installMode;
+      
       syncStatusChangeCallback(CodePush.SyncStatus.INSTALLING_UPDATE);
-      await localPackage.install(syncOptions.installMode, () => {
+      await localPackage.install(resolvedInstallMode, () => {
         syncStatusChangeCallback(CodePush.SyncStatus.UPDATE_INSTALLED);
       });
 

README.md

@@ -316,7 +316,7 @@ The simplest way to do this is to perform the following in your app's root compo
     codePush.sync();
     ```
 
-If an update is available, it will be silently downloaded, and installed the next time the app is restarted (either explicitly by the end user or by the OS), which ensures the least invasive experience for your end users. If you would like to display a confirmation dialog (an "active install"), or customize the update experience in any way, refer to the `sync` method's [API reference](#codepushsync) for information on how to tweak this default behavior.
+If an update is available, it will be silently downloaded, and installed the next time the app is restarted (either explicitly by the end user or by the OS), which ensures the least invasive experience for your end users. If an available update is mandatory, then it will be installed immediately, ensuring that the end user gets it as soon as possible. Additionally, if you would like to display a confirmation dialog (an "active install"), or customize the update experience in any way, refer to the `sync` method's [API reference](#codepushsync) for information on how to tweak this default behavior.
 
 <a id="apple-note">*NOTE: While [Apple's developer agreement](https://developer.apple.com/programs/ios/information/iOS_Program_Information_4_3_15.pdf) fully allows performing over-the-air updates of JavaScript and assets (which is what enables CodePush!), it is against their policy for an app to display an update prompt. Because of this, we recommend that App Store-distributed apps don't enable the `updateDialog` option when calling `sync`, whereas Google Play and internally distributed apps (e.g. Enterprise, Fabric, HockeyApp) can choose to enable/customize it.*</a>
 
@@ -517,7 +517,9 @@ While the `sync` method tries to make it easy to perform silent and active updat
 
 * __deploymentKey__ *(String)* - Specifies the deployment key you want to query for an update against. By default, this value is derived from the `Info.plist` file (iOS) and `MainActivity.java` file (Android), but this option allows you to override it from the script-side if you need to dynamically use a different deployment for a specific call to `sync`.
 
-* __installMode__ *(codePush.InstallMode)* - Indicates when you would like to "install" the update after downloading it, which includes reloading the JS bundle in order for any changes to take affect. Defaults to `codePush.InstallMode.ON_NEXT_RESTART`. Refer to the [`InstallMode`](#installmode) enum reference for a description of the available options and what they do.
+* __installMode__ *(codePush.InstallMode)* - Specifies when you would like to install optional updates (i.e. those that aren't marked as mandatory). Defaults to `codePush.InstallMode.ON_NEXT_RESTART`. Refer to the [`InstallMode`](#installmode) enum reference for a description of the available options and what they do.
+
+* __mandatoryInstallMode__ *(codePush.InstallMode)* - Specifies when you would like to install updates which are marked as mandatory. Defaults to `codePush.InstallMode.IMMEDIATE`. Refer to the [`InstallMode`](#installmode) enum reference for a description of the available options and what they do.
 
 * __updateDialog__ *(UpdateDialogOptions)* - An "options" object used to determine whether a confirmation dialog should be displayed to the end user when an update is available, and if so, what strings to use. Defaults to `null`, which has the effect of disabling the dialog completely. Setting this to any truthy value will enable the dialog with the default strings, and passing an object to this parameter allows enabling the dialog as well as overriding one or more of the default strings. Before enabling this option within an App Store-distributed app, please refer to [this note](#user-content-apple-note).
 
@@ -552,6 +554,10 @@ codePush.sync({ deploymentKey: "KEY" });
 // instead of waiting until the app is restarted
 codePush.sync({ installMode: codePush.InstallMode.ON_NEXT_RESUME });
 
+// Download the update silently, and install optional updates
+// on the next restart, but install mandatory updates on the next resume.
+codePush.sync({ mandatoryInstallMode: codePush.InstallMode.ON_NEXT_RESUME });
+
 // Changing the title displayed in the
 // confirmation dialog of an "active" update
 codePush.sync({ updateDialog: { title: "An update is available!" } });
@@ -651,7 +657,8 @@ The CodePush API includes the following enums which can be used to customize the
 ##### InstallMode
 
 This enum specified when you would like an installed update to actually be applied, and can be passed to either the `sync` or `LocalPackage.install` methods. It includes the following values:
-* __codePush.InstallMode.IMMEDIATE__ *(0)* - Indicates that you want to install the update and restart the app immediately. This value is appropriate for debugging scenarios as well as when displaying an update prompt to the user, since they would expect to see the changes immediately after accepting the installation.
+
+* __codePush.InstallMode.IMMEDIATE__ *(0)* - Indicates that you want to install the update and restart the app immediately. This value is appropriate for debugging scenarios as well as when displaying an update prompt to the user, since they would expect to see the changes immediately after accepting the installation. Additionally, this mode can be used to enforce mandatory updates, since it removes the potentially undesired latency between the update installation and the next time the end user restarts or resumes the app.
 
 * __codePush.InstallMode.ON_NEXT_RESTART__ *(1)* - Indicates that you want to install the update, but not forcibly restart the app. When the app is "naturally" restarted (due the OS or end user killing it), the update will be seamlessly picked up. This value is appropriate when performing silent updates, since it would likely be disruptive to the end user if the app suddenly restarted out of nowhere, since they wouldn't have realized an update was even downloaded. This is the default mode used for both the `sync` and `LocalPackage.install` methods.