react-native-code-push
Advanced tools
Comparing version 1.10.0-beta to 1.10.1-beta
{ | ||
"name": "react-native-code-push", | ||
"version": "1.10.0-beta", | ||
"version": "1.10.1-beta", | ||
"description": "React Native plugin for the CodePush service", | ||
@@ -21,5 +21,15 @@ "main": "CodePush.js", | ||
}, | ||
"devDependencies": { | ||
"react-native": "0.19.0" | ||
"rnpm": { | ||
"android": { | ||
"packageInstance": "new CodePush(${androidDeploymentKey}, this, BuildConfig.DEBUG)" | ||
}, | ||
"ios": { | ||
"sharedLibraries": ["libz"] | ||
}, | ||
"params": [{ | ||
"type": "input", | ||
"name": "androidDeploymentKey", | ||
"message": "What is your CodePush deployment key for Android (hit <ENTER> to ignore)" | ||
}] | ||
} | ||
} | ||
} |
100
README.md
@@ -1,2 +0,2 @@ | ||
# React Native Plugin for CodePush | ||
# React Native Module for CodePush | ||
@@ -21,4 +21,3 @@ This plugin provides client-side integration for the [CodePush service](http://codepush.tools), allowing you to easily add a dynamic update experience to your React Native app(s). | ||
* [Plugin Usage](#plugin-usage) | ||
* [Releasing Updates (JavaScript-only)](#releasing-updates-javascript-only) | ||
* [Releasing Updates (JavaScript + images)](#releasing-updates-javascript--images) | ||
* [Releasing Updates](#releasing-updates) | ||
* [API Reference](#api-reference) | ||
@@ -53,4 +52,4 @@ * [JavaScript API](#javascript-api-reference) | ||
| v0.15.0-v0.18.0 | v1.4.0-v1.6.0 *(introduced iOS asset support)* | | ||
| v0.19.0-v0.23.0 | v1.7.0+ *(introduced Android asset support)* | | ||
| v0.24.0+ | TBD :) We work hard to respond to new RN releases, but they do occasionally break us. We will update this chart with each RN release, so that users can check to see what our "official" support is. | ||
| v0.19.0-v0.24.0 | v1.7.0+ *(introduced Android asset support)* | | ||
| v0.25.0+ | TBD :) We work hard to respond to new RN releases, but they do occasionally break us. We will update this chart with each RN release, so that users can check to see what our "official" support is. | ||
@@ -81,3 +80,3 @@ ## Supported Components | ||
```shell | ||
npm install --save react-native-code-push | ||
npm install --save react-native-code-push@latest | ||
``` | ||
@@ -216,2 +215,13 @@ | ||
2. If you're using RNPM >=1.6.0, you will be prompted for the deployment key you'd like to use. If you don't already have it, you can retreive this value by running `code-push deployment ls <appName> -k`, or you can choose to ignore it (by simply hitting `<ENTER>`) and add it in later. To get started, we would recommend just using your `Staging` deployment key, so that you can test out the CodePush end-to-end. | ||
3. (Only needed in v1.8.0+ of the plugin) In your `android/app/build.gradle` file, add the `codepush.gradle` file as an additional build task definition underneath `react.gradle`: | ||
```gradle | ||
... | ||
apply from: "react.gradle" | ||
apply from: "../../node_modules/react-native-code-push/android/codepush.gradle" | ||
... | ||
``` | ||
And that's it for installation using RNPM! Continue below to the [Plugin Configuration](#plugin-configuration-android) section to complete the setup. | ||
@@ -227,2 +237,3 @@ | ||
``` | ||
2. In your `android/app/build.gradle` file, add the `:react-native-code-push` project as a compile-time dependency: | ||
@@ -236,3 +247,4 @@ | ||
} | ||
``` | ||
``` | ||
3. (Only needed in v1.8.0+ of the plugin) In your `android/app/build.gradle` file, add the `codepush.gradle` file as an additional build task definition underneath `react.gradle`: | ||
@@ -275,3 +287,2 @@ | ||
new MainReactPackage(), | ||
// new CodePush() <-- remove this generated line if you used RNPM for plugin installation. | ||
new CodePush("deployment-key-here", this, BuildConfig.DEBUG) | ||
@@ -290,2 +301,3 @@ ); | ||
1. When (and how often) to check for an update? (e.g. app start, in response to clicking a button in a settings page, periodically at some fixed interval) | ||
2. When an update is available, how to present it to the end user? | ||
@@ -311,54 +323,40 @@ | ||
## Releasing Updates (JavaScript-only) | ||
## Releasing Updates | ||
Once your app has been configured and distributed to your users, and you've made some JS changes, it's time to release it to them instantly! If you're not using React Native to bundle images (via `require('./foo.png')`), then perform the following steps. Otherwise, skip to the next section instead: | ||
Once your app has been configured and distributed to your users, and you've made some JS and/or asset changes, it's time to instantly release them! The simplest (and recommended) way to do this is to use the `release-react` comand in the CodePush CLI, which will handle bundling your JavaScript and asset files and releasing the update to the CodePush server. | ||
1. Execute `react-native bundle` (passing the appropriate parameters, see example below) in order to generate the updated JS bundle for your app. You can place this file wherever you want via the `--bundle-output` flag, since the exact location isn't relevant for CodePush purposes. It's important, however, that you set `--dev false` so that your JS code is optimized appropriately and any "yellow box" warnings won't be displayed. | ||
In it's most basic form, this command only requires two parameters: your app name and the platform you are bundling the update for (either `ios` or `android`). | ||
2. Execute `code-push release <appName> <jsBundleFilePath> <targetBinaryVersion> --deploymentName <deploymentName>` in order to publish the generated JS bundle to the server. The `<jsBundleFilePath>` parameter should equal the value you provided to the `--bundle-output` flag in step #1. Additionally, the `<targetBinaryVersion>` parameter should equal the [**exact app store version**](http://codepush.tools/docs/cli.html#app-store-version-parameter) (i.e. the semver version end users would see when installing it) you want this CodePush update to target. | ||
```shell | ||
code-push release-react <appName> <platform> | ||
For more info regarding the `release` command and its parameters, refer to the [CLI documentation](http://codepush.tools/docs/cli.html#releasing-app-updates). | ||
Example Usage: | ||
```shell | ||
react-native bundle --platform ios --entry-file index.ios.js --bundle-output codepush.js --dev false | ||
code-push release MyApp codepush.js 1.0.0 | ||
code-push release-react MyApp ios | ||
code-push release-react MyApp-Android android | ||
``` | ||
And that's it! for more information regarding the CLI and how the release (or promote and rollback) commands work, refer to the [documentation](http://microsoft.github.io/code-push/docs/cli.html). Additionally, if you run into any issues, you can ping us within the [#code-push](https://discord.gg/0ZcbPKXt5bWxFdFu) channel on Reactiflux, [e-mail us](mailto:codepushfeed@microsoft.com) and/or check out the [troubleshooting](#debugging--troubleshooting) details below. | ||
*Note: Instead of running `react-native bundle`, you could rely on running `xcodebuild` and/or `gradlew assemble` instead to generate the JavaScript bundle file, but that would be unneccessarily doing a native build, when all you need for distributing updates via CodePush is your JavaScript bundle.* | ||
The `release-react` command enables such a simple workflow because it provides many sensible defaults (e.g. generating a release bundle, assuming your app's entry file on iOS is either `index.ios.js` or `index.js`). However, all of these defaults can be customized to allow incremental flexibility as neccessary, which makes it a good fit for most scenarios. | ||
## Releasing Updates (JavaScript + images) | ||
```shell | ||
# Release a mandatory update with a changelog | ||
code-push release-react MyApp ios -m --description "Modified the header color" | ||
*Note: Android support for updating assets was added to React Native v0.19.0, and requires you to use CodePush v1.7.0. If you are using an older version of RN, you can't update assets via CodePush, and therefore, need to either upgrade or use the previous workflow for simply updating your JS bundle.* | ||
# Release an update for an app that uses a non-standard entry file name, and also capture | ||
# the sourcemap file generated by react-native bundle | ||
code-push release-react MyApp ios --entryFile MyApp.js --sourcemapOutput ../maps/MyApp.map | ||
If you are using the new React Native [assets system](https://facebook.github.io/react-native/docs/images.html#content), as opposed to loading your images from the network and/or platform-specific mechanisms (e.g. iOS asset catalogs), then you can't simply pass your jsbundle to CodePush as demonstrated above. You **MUST** provide your images as well. To do this, simply use the following workflow: | ||
# Release a dev Android build to just 1/4 of your end users | ||
code-push release-react MyApp-Android android --rollout 25% --dev true | ||
1. Create a new directory that can be used to organize your app's release assets (i.e. the JS bundle and your images). We recommend calling this directory "release" but it can be named anything. If you create this directory within your project's directory, make sure to add it to your `.gitignore` file, since you don't want it checked into source control. | ||
# Release an update that targets users running any 1.1.* binary, as opposed to | ||
# limiting the update to exact version name in the build.gradle file | ||
code-push release-react MyApp-Android android --targetBinaryVersion "~1.1.0" | ||
2. When calling `react-native bundle`, specify that your assets and JS bundle go into the directory you created in #1, and that you want a non-dev build for your respective platform and entry file. For example, assuming you called this directory "release", you could run the following command: | ||
``` | ||
```shell | ||
react-native bundle \ | ||
--platform ios \ | ||
--entry-file index.ios.js \ | ||
--bundle-output ./release/main.jsbundle \ | ||
--assets-dest ./release \ | ||
--dev false | ||
``` | ||
The CodePush client supports differential updates, so even though you are releasing your JS bundle and assets on every update, your end users will only actually download the files they need. The service handles this automatically so that you can focus on creating awesome apps and we can worry about optimizing end user downloads. | ||
*NOTE: The file name that you specify as the value for the `--bundle-output` parameter must have one of the following extensions in order to be detected by the plugin: `.js`, `.jsbundle`, `.bundle` (e.g. `main.jsbundle`, `ios.js`). The name of the file isn't relevant, but the extension is used for detectining the bundle within the update contents, and therefore, using any other extension will result in the update failing.* | ||
3. Execute `code-push release`, passing the path to the directory you created in #1 as the ["updateContents"](http://codepush.tools/docs/cli.html#package-parameter) parameter, and the [**exact binary version**](http://codepush.tools/docs/cli.html#app-store-version-parameter) that this update is targetting as the ["targetBinaryVersion"](http://codepush.tools/docs/cli.html#app-store-version-parameter) parameter (e.g. `code-push release Foo ./release 1.0.0`). The code-push CLI will automatically handle zipping up the contents for you, so don't worry about handling that yourself. | ||
For more details about how the `release-react` command works, as well as the various parameters it exposes, refer to the [CLI docs](https://github.com/Microsoft/code-push/tree/master/cli#releasing-updates-react-native). Additionally, if you would prefer to handle running the `react-native bundle` command yourself, and therefore, want an even more flexible solution than `release-react`, refer to the [`release` command](https://github.com/Microsoft/code-push/tree/master/cli#releasing-updates-general) for more details. | ||
For more info regarding the `release` command and its parameters, refer to the [CLI documentation](http://codepush.tools/docs/cli.html#releasing-app-updates). | ||
Additionally, the CodePush client supports differential updates, so even though you are releasing your JS bundle and assets on every update, your end users will only actually download the files they need. The service handles this automatically so that you can focus on creating awesome apps and we can worry about optimizing end user downloads. | ||
If you run into any issues, or have any questions/comments/feedback, you can ping us within the [#code-push](https://discord.gg/0ZcbPKXt5bWxFdFu) channel on Reactiflux, [e-mail us](mailto:codepushfeed@microsoft.com) and/or check out the [troubleshooting](#debugging--troubleshooting) details below. | ||
If you run into any issues, you can ping us within the [#code-push](https://discord.gg/0ZcbPKXt5bWxFdFu) channel on Reactiflux, [e-mail us](mailto:codepushfeed@microsoft.com) and/or check out the [troubleshooting](#debugging--troubleshooting) details below. | ||
*Note: Releasing assets via CodePush requires that you're using React Native v0.15.0+ and CodePush v1.4.0+ (for iOS) and React Native v0.19.0+ and CodePush v1.7.0+ (Android). If you are using assets and an older version of the CodePush plugin, you should not release updates via CodePush, because it will break your app's ability to load images from the binary. Please test and release appropriately!* | ||
--- | ||
@@ -631,2 +629,3 @@ | ||
###### Methods | ||
- __install(installMode: codePush.InstallMode = codePush.InstallMode.ON_NEXT_RESTART, minimumBackgroundDuration = 0): Promise<void>__: Installs the update by saving it to the location on disk where the runtime expects to find the latest version of the app. The `installMode` parameter controls when the changes are actually presented to the end user. The default value is to wait until the next app restart to display the changes, but you can refer to the [`InstallMode`](#installmode) enum reference for a description of the available options and what they do. If the `installMode` parameter is set to `InstallMode.ON_NEXT_RESUME`, then the `minimumBackgroundDuration` parameter allows you to control how long the app must have been in the background before forcing the install after it is resumed. | ||
@@ -645,2 +644,3 @@ | ||
###### Methods | ||
- __download(downloadProgressCallback?: Function): Promise<LocalPackage>__: Downloads the available update from the CodePush service. If a `downloadProgressCallback` is specified, it will be called periodically with a `DownloadProgress` object (`{ totalBytes: Number, receivedBytes: Number }`) that reports the progress of the download until it completes. Returns a Promise that resolves with the `LocalPackage`. | ||
@@ -712,7 +712,7 @@ | ||
Constructs the CodePush client runtime and includes methods for integrating CodePush into your app's `ReactInstanceManager`. | ||
Constructs the CodePush client runtime and represents the `ReactPackage` instance that you add to you app's list of packages. | ||
##### Constructors | ||
- __CodePush(String deploymentKey, Activity mainActivity)__ - Creates a new instance of the CodePush runtime, that will be used to query the service for updates via the provided deployment key. The `mainActivity` parameter should always be set to `this` when configuring your `ReactInstanceManager` inside the `MainActivity` class. This constructor puts the CodePush runtime into "release mode", so if you want to enable debugging behavior, use the following constructor instead. | ||
- __CodePush(String deploymentKey, Activity mainActivity)__ - Creates a new instance of the CodePush runtime, that will be used to query the service for updates via the provided deployment key. The `mainActivity` parameter should always be set to `this` when configuring your React packages list inside the `MainActivity` class. This constructor puts the CodePush runtime into "release mode", so if you want to enable debugging behavior, use the following constructor instead. | ||
@@ -725,3 +725,3 @@ - __CodePush(String deploymentKey, Activity mainActivity, bool isDebugMode)__ - Equivalent to the previous constructor, but allows you to specify whether you want the CodePush runtime to be in debug mode or not. When using this constructor, the `isDebugMode` parameter should always be set to `BuildConfig.DEBUG` in order to stay synchronized with your build type. When putting CodePush into debug mode, the following behaviors are enabled: | ||
##### Methods | ||
##### Static Methods | ||
@@ -732,4 +732,2 @@ - __getBundleUrl()__ - Returns the path to the most recent version of your app's JS bundle file, assuming that the resource name is `index.android.bundle`. If your app is using a different bundle name, then use the overloaded version of this method which allows specifying it. This method has the same resolution behavior as the Objective-C equivalent described above. | ||
- __getReactPackage()__ - Returns a `ReactPackage` object that should be added to your `ReactInstanceManager` via its `addPackage` method. Without this, the `react-native-code-push` JS module won't be available to your script. | ||
## Example Apps | ||
@@ -752,3 +750,3 @@ | ||
To view these logs, you can use either the Chrome DevTools Console, the XCode Console (iOS) and/or ADB logcat (Android). By default, React Native logs are disabled on iOS in release builds, so if you want to view them in a release build, you simply need to make the following changes to your `AppDelegate.m` file: | ||
To view these logs, you can use either the Chrome DevTools Console, the XCode Console (iOS), the [OS X Console](https://en.wikipedia.org/wiki/Console_%28OS_X%29#.7E.2FLibrary.2FLogs) (iOS) and/or ADB logcat (Android). By default, React Native logs are disabled on iOS in release builds, so if you want to view them in a release build, you simply need to make the following changes to your `AppDelegate.m` file: | ||
@@ -755,0 +753,0 @@ 1. Add an `#import "RCTLog.h"` statement |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
0
2501
747915
757