Updating docs

Author: lostintangent

README.md

@@ -7,7 +7,7 @@ The CodePush React Native API provides two primary mechanisms for discovering up
 1. [**Sync mode**](#codepushsync), which allows you to call a single method--presumably as part of mounting your app's root component or in response to a button click--that will automatically check for an update, download and install it, while respecting the policies and metadata associated with each release (e.g. if the release is mandatory then it doesn't give the end-user the option to ignore it)
 2. [**Advanced mode**](#codepushcheckforupdate), which provides a handful of "low-level" methods which give you complete control over the update experience, at the cost of added complexity.
 
-When getting started using CodePush, we would recommended using the sync mode until you discover that it doesn't suit your needs. That said, if you have a user scenario
+When getting started using CodePush, we recommended using the sync method until you discover that it doesn't suit your needs. That said, if you have a user scenario
 that isn't currently covered well by sync, please [let us know](mailto:[email protected]) since that would be valuable feedback.
 
 *NOTE: We don't currently have support for an "automatic mode" which provides a "code-free" experience to adding in dynamic update discovery and acquisition. If that would be valuable to you, please [let us know](mailto:[email protected]).*
@@ -19,11 +19,9 @@ that isn't currently covered well by sync, please [let us know](mailto:codepushf
 
 ## How does it work?
 
-<img src="https://cloud.githubusercontent.com/assets/116461/10835297/20b7cdf0-7e5e-11e5-8e44-ea6144839e5f.png" align="right" />
-
 A React Native application's assets (JavaScript code and other resources) are traditionally bundled up as a ```.jsbundle``` file which is loaded from the application installation location on the target device during runtime. After you submit an update to the store, the user downloads the update, and those assets will be replaced with the new assets.
 
-CodePush is here to simplify this process by allowing you to instantly update your application's assets without having to submit a new update to the store. We do this by allowing you to upload and manage your React Native app bundles on our CodePush server. In the application, we check for the presence of updated bundles on the server. If they are available, we will install and persist them to the internal storage of the device. If a new bundle is installed, the application will reload from the updated package location.
+CodePush is here to simplify this process by allowing you to instantly update your application's assets without having to submit a new update to the store. We do this by allowing you to upload and manage your React Native app bundles on the CodePush server. In the application, we check for the presence of updated bundles on the server. If they are available, we will install and persist them to the internal storage of the device. If a new bundle is installed, the application will reload from the updated package location.
 
 ## Plugin Acquisition
 
@@ -62,24 +60,28 @@ Once your Xcode project has been setup to build/link the CodePush plugin, you ne
     #import "CodePush.h"
     ```
 
-2. Find the following line of code, which loads your JS Bundle from the packager's dev server:
+2. Find the following line of code, which loads your JS Bundle from the app binary:
 
     ```
-    jsCodeLocation = [NSURL URLWithString:@"http://localhost:8081/index.ios.bundle?platform=ios&dev=true"];
+    jsCodeLocation = [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
     ```
+    
 3. Replace it with this line:
 
     ```
-    jsCodeLocation = [CodePush getBundleUrl];
+    jsCodeLocation = [CodePush bundleURL];
     ```
 
 This change configures your app to always load the most recent version of your app's JS bundle. On the initial launch, this will correspond to the file that was compiled with the app. However, after an update has been pushed via CodePush, this will return the location of the most recently installed update.
 
+*NOTE: The `bundleURL` method assumes your app's JS bundle is named `main.jsbundle`. If you have configured your app to use a different file name, simply call the `bundleURLForResourceName:` method (which assumes you're using the `.jsbundle` extension) or `bundleURLForResourceName:withExtension:` method instead, in order to overwrite that default behavior*
+
 To let the CodePush runtime know which deployment it should query for updates against, perform the following steps:
 
 1. Open your app's `Info.plist` and add a new `CodePushDeploymentKey` entry, whose value is the key of the deployment you want to configure this app against (e.g. the Staging deployment for FooBar app)
 2. In your app's `Info.plist` make sure your `CFBundleShortVersionString` value is a valid [semver](http://semver.org/) version (e.g. 1.0.0 not 1.0)
 
+*NOTE: If you'd prefer, you can also set the deployment key in code by assigning the key to the `[CodePushConfig current].deploymentKey` property.*
 ## Plugin consumption
 
 With the CodePush plugin downloaded and linked, and your app asking CodePush where to get the right JS bundle from, the only thing left is to add the neccessary code to your app to control the following:
@@ -101,8 +103,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, a dialog will be displayed to the user asking them if they would like to install it. If the update was marked as mandatory, then the dialog will
-omit the option to decline installation. The `sync` method takes a handful of options to customize this experience, so refer to its [API reference](#codepushsync) if you'd like to tweak its default behavior.
+If an update is available, it will be silently download, and will be installed the next time the app is restarted. This experience ensures the least invasive experience for your end-users. If you would like to display a confirmation dialog, 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.
 
 ## Releasing code updates
 
@@ -124,6 +125,8 @@ When you require the `react-native-code-push` module, that object provides the f
 * [checkForUpdate](#codepushcheckforupdate): Queries the CodePush service for an update against the configured deployment. This method returns a promise which resolves to a `RemotePackage` that can be subsequently downloaded.
 * [getCurrentPackage](#codepushgetcurrentpackage): Gets information about the currently installed package (e.g. description, installation time)
 * [notifyApplicationReady](#codepushnotifyapplicationready): Notifies the CodePush runtime that an installed update is considered successful. This is an optional API, but is useful when you want to expicitly enable "rollback protection" in the event that an exception occurs in any code that you've deployed to production
+* [restartApp](#codepushrestartapp): Installs a pending update by immediately restarting the app.
+* [setDeploymentKey](#codepushsetdeploymentkey): Dynamically updates the deployment key that the CodePush runtime will use to query for app updates.
 * [sync](#codepushsync): Allows checking for an update, downloading it and installing it, all with a single call. Unless you need custom UI and/or behavior, we recommend most developers to use this method when integrating CodePush into their apps
 
 #### codePush.checkForUpdate
@@ -172,6 +175,40 @@ Notifies the CodePush runtime that an update is considered successful, and there
 
 If the `rollbackTimeout` parameter was not specified, the CodePush runtime will not enforce any automatic rollback behavior, and therefore, calling this function is not required and will result in a no-op.
 
+#### codePush.restartApp
+
+```javascript
+codePush.restartApp(rollbackTimeout: Number = 0): void;
+```
+
+Installs the pending update (if applicable) by immediately restarting the app, and optionally starting the rollback timer. This method is for advanced scenarios, and is useful when the following conditions are true:
+
+1. Your app is specifying an install mode value of `ON_NEXT_RESTART` when calling `sync` or `LocalPackage.install`, which has the effect of not applying your update until the app has been restarted (by either the end-user or OS)
+2. You have an app-specific user event (e.g. the end-user navigated back to the app's home page) that allows you to apply the update in an unobtrusive way, and potentially gets the update in front of the end-user sooner then waiting until the next restart.
+
+The `rollbackTimeout` parameter has the same behavior as the equivalent in the `sync` and `checkForUpdate` method, and allows your app to have control over the point that an update is installed, while still benefitting from rollback production. 
+
+#### codePush.setDeploymentKey
+
+```javascript
+codePush.setDeploymentKey(deploymentKey: String): Promise<void>;
+```
+
+Dynamically updates the deployment key that the CodePush runtime will use to query for app updates. This is beneficial if your app has a default deployment key which you added to your `Info.plist` file, but you want to dynamically change it at runtime based on some app-specific policy (e.g. you want to give early access to certain users, by pointing them at your staging deployment).
+
+The method simply takes a string representing the new deployment, and returns a `Promise` that will resolve once the specified deployment key has been applied, and calls to `sync` and/or `checkForUpdate` could be successfully called.
+
+Example Usage: 
+
+```javascript
+codePush.setDeploymentKey("SOME_VALID_KEY_VALUE").then(() => {
+    // The following call to sync with query the updated
+    // app deployment for an update
+    codePush.sync();
+});
+
+```
+
 #### codePush.sync
 
 ```javascript
@@ -287,20 +324,6 @@ The `RemotePackage` inherits all of the same properties as the `LocalPackage`, b
 
 ---
 
-## Running the Example
-
-* Clone this repository
-* From the root of this project, run `npm install`
-* `cd` into `Examples/CodePushDemoApp`
-* From this demo app folder, run `npm install`
-* Open `Info.plist` and fill in the value for CodePushDeploymentKey
-* Run `npm start` to launch the packager
-* Open `CodePushDemoApp.xcodeproj` in Xcode
-* Launch the project
-
-## Running Tests
+## Debugging
 
-* Open `CodePushDemoApp.xcodeproj` in Xcode
-* Navigate to the test explorer (small grey diamond near top left)
-* Click on the 'play' button next to CodePushDemoAppTests
-* After the tests are completed, green ticks should appear next to the test cases to indicate success
+When debugging your JavaScript using Chrome, make sure that your JS bundle location is configured in your `AppDelegate.m` file to point at the packager URL, since that will provide you with the most effecient debugging experience. Since your CodePush deployment key is specified in either the `Info.plist` file, by setting the `[CodePushConfig current].deploymentKey` property, or by calling the `codePush.setDeploymentKey()` method from JavaScript, any calls to `sync` or `checkForUpdate` will work just fine regardless if your `AppDelegate.m` file hasn't be configured to use the `[CodePush bundleURL]` method for its JS bundle location.