Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit b7e2531

Browse files
geof90geof90
committed
Update README.md
1 parent 37c62f5 commit b7e2531

File tree

1 file changed

+86
-27
lines changed

1 file changed

+86
-27
lines changed

‎README.md

Lines changed: 86 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ This plugin provides client-side integration for the [CodePush service](http://c
88
* [Getting Started](#getting-started)
99
* [iOS Setup](#ios-setup)
1010
* [Plugin Installation](#plugin-installation-ios)
11+
* [RNPM](#plugin-installation-ios---rnpm)
12+
* [CocoaPods](#plugin-installation-ios---cocoapods)
13+
* ["Manual"](#plugin-installation-ios---manual)
1114
* [Plugin Configuration](#plugin-configuration-ios)
1215
* [Android Setup](#android-setup)
1316
* [Plugin Installation](#plugin-installation-android)
@@ -21,6 +24,7 @@ This plugin provides client-side integration for the [CodePush service](http://c
2124
* [Objective-C API Reference (iOS)](#objective-c-api-reference-ios)
2225
* [Java API Reference (Android)](#java-api-reference-android)
2326
* [Example Apps](#example-apps)
27+
* [Debugging / Troubleshooting](#debugging--troubleshooting)
2428

2529
## How does it work?
2630

@@ -80,16 +84,56 @@ If you want to see how other projects have integrated with CodePush, you can che
8084

8185
## iOS Setup
8286

83-
Once you've acquired the CodePush plugin, you need to integrate it into the Xcode project of your React Native app. To do this, take the following steps:
87+
Once you've acquired the CodePush plugin, you need to integrate it into the Xcode project of your React Native app and configure it correctly. To do this, take the following steps:
8488

8589
### Plugin Installation (iOS)
8690

91+
In order to accomodate as many developer preferences as possible, the CodePush plugin supports iOS installation via three mechanisms:
92+
93+
1. [**RNPM**](#plugin-installation-ios---rnpm) - [React Native Package Manager (RNPM)](https://github.com/rnpm/rnpm) is an awesome tool that provides the simplest installation experience possible for React Native plugins. If you're already using it, or you want to use it, then we recommend this approach.
94+
95+
2. [**CocoaPods**](#plugin-installation-ios---cocoapods) - If you're building a native iOS app that is embedding React Native into it, or you simply prefer using [CocoaPods](https://cocoapods.org), then we recommend using the Podspec file that we ship as part of our plugin.
96+
97+
3. [**"Manual"**](#plugin-installation-ios---manual) - If you don't want to depend on any additional tools or are fine with a few extra installation steps (it's a one-time thing), then go with this approach.
98+
99+
#### Plugin Installation (iOS - RNPM)
100+
101+
1. Run `rnpm link react-native-code-push`
102+
103+
*Note: If you don't already have RNPM installed, you can do so by simply running `npm i -g rnpm` and then executing the above command.*
104+
105+
2. Open your app's Xcode project
106+
107+
3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration.
108+
109+
4. Click the plus sign underneath the "Link Binary With Libraries" list and select the `libz.tbd` library underneath the `iOS` node that matches your target version.
110+
111+
![Libz reference](https://cloud.githubusercontent.com/assets/116461/11605042/6f786e64-9aaa-11e5-8ca7-14b852f808b1.png)
112+
113+
*Note: Alternatively, if you prefer, you can add the `-lz` flag to the `Other Linker Flags` field in the `Linking` section of the `Build Settings`.*
114+
115+
We hope to eventually remove the need for steps #2-4, but in the meantime, RNPM doesn't support automating them.
116+
117+
#### Plugin Installation (iOS - CocoaPods)
118+
119+
1. Add the CodePush plugin dependency to your `Podfile`, pointing at the path where NPM installed it
120+
121+
```ruby
122+
pod 'CodePush', :path => './node_modules/react-native-code-push`
123+
```
124+
125+
2. Run `pod install`
126+
127+
#### Plugin Installation (iOS - Manual)
128+
87129
1. Open your app's Xcode project
130+
88131
2. Find the `CodePush.xcodeproj` file within the `node_modules/react-native-code-push/ios` directory (or `node_modules/react-native-code-push` for <=`1.7.3-beta` installations) and drag it into the `Libraries` node in Xcode
89132

90133
![Add CodePush to project](https://cloud.githubusercontent.com/assets/8598682/13368613/c5c21422-dca0-11e5-8594-c0ec5bde9d81.png)
91134

92135
3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration.
136+
93137
4. Drag `libCodePush.a` from `Libraries/CodePush.xcodeproj/Products` into the "Link Binary With Libraries" section of your project's "Build Phases" configuration.
94138
95139
![Link CodePush during build](https://cloud.githubusercontent.com/assets/516559/10322221/a75ea066-6c31-11e5-9d88-ff6f6a4d6968.png)
@@ -149,7 +193,7 @@ To let the CodePush runtime know which deployment it should query for updates ag
149193

150194
![Deployment list](https://cloud.githubusercontent.com/assets/116461/11601733/13011d5e-9a8a-11e5-9ce2-b100498ffb34.png)
151195

152-
2. In your app's `Info.plist` make sure your `Bundle versions string, short` (aka `CFBundleShortVersionString`) value is a valid [semver](http://semver.org/) version. If a version string does not contain a patch version, the CodePush server will assume the patch value to be "0" when it is queried by the plugin for updates (e.g. "1.0" will be treated as "1.0.0").
196+
2. In your app's `Info.plist` make sure your `Bundle versions string, short` (aka `CFBundleShortVersionString`) value is a valid [semver](http://semver.org/) version (e.g. 1.0.0 not 1.0)
153197
154198
![Bundle version](https://cloud.githubusercontent.com/assets/116461/12307416/f9b82688-b9f3-11e5-839a-f1c6b4acd093.png)
155199
@@ -225,7 +269,7 @@ After installing the plugin and syncing your Android Studio project with Gradle,
225269
}
226270
```
227271

228-
2. Ensure that the `android.defaultConfig.versionName` property in your `android/app/build.gradle` file is set to a semver compliant value. If a patch version is not specified, the CodePush server will assume a patch version of "0" when it is queried by the plugin for updates (e.g. "1.0" will be treated as "1.0.0").
272+
2. Ensure that the `android.defaultConfig.versionName` property in your `android/app/build.gradle` file is set to a semver compliant value (i.e. "1.0.0" not "1.0")
229273

230274
```gradle
231275
android {
@@ -281,7 +325,7 @@ After installing the plugin and syncing your Android Studio project with Gradle,
281325
}
282326
```
283327

284-
2. Ensure that the `android.defaultConfig.versionName` property in your `android/app/build.gradle` file is set to a semver compliant value. If a patch version is not specified, the CodePush server will assume a patch version of "0" when it is queried by the plugin for updates (e.g. "1.0" will be treated as "1.0.0").
328+
2. Ensure that the `android.defaultConfig.versionName` property in your `android/app/build.gradle` file is set to a semver compliant value (i.e. "1.0.0" not "1.0")
285329

286330
```gradle
287331
android {
@@ -326,7 +370,7 @@ Once your app has been configured and distributed to your users, and you've made
326370
327371
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.
328372

329-
2. Execute `code-push release <appName> <jsBundleFilePath> <targetBinaryRange> --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 `<targetBinaryRange>` parameter should be set to a range that satisfies the [**app store version**](http://codepush.tools/docs/cli.html#target-binary-range-parameter) (i.e. the semver version end users would see when installing it) you want this CodePush update to target.
373+
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.
330374

331375
For more info regarding the `release` command and its parameters, refer to the [CLI documentation](http://codepush.tools/docs/cli.html#releasing-app-updates).
332376

@@ -337,34 +381,15 @@ react-native bundle --platform ios --entry-file index.ios.js --bundle-output cod
337381
code-push release MyApp codepush.js 1.0.0
338382
```
339383

340-
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).
384+
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.
341385
342386
*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.*
343387
344388
## Releasing Updates (JavaScript + images)
345389
346390
*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.*
347391

348-
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. You can do this via one of the following workflows:
349-
350-
### Using the release-react command
351-
352-
The `release-react` command is a single-step utility that automates the process of generating the update contents (JS bundle, image assets) for your project via the `react-native` bundle command and uploading a release to CodePush via the `code-push release` command with those contents. It automatically infers parameters such as the `<targetBinaryRange>` from the project's config files (`Info.plist` for updates targeting iOS or `build.gradle` for updates targeting Android).
353-
354-
To use it, simply execute the `release-react` command specifying your app name and [target platform](http://codepush.tools/docs/cli.html#platform-parameter) ("ios" or "android"), e.g.
355-
```
356-
code-push release-react Foo ios
357-
```
358-
359-
Once the command has finished execution, your latest update should be released to CodePush! For more information about the `release-react` command and its parameters, refer to the [CLI documentation](http://codepush.tools/docs/cli.html#releasing-updates-to-a-react-native-app).
360-
361-
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.
362-
363-
*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!*
364-
365-
### Manually generating update contents and releasing to CodePush
366-
367-
For scenarios where you require more control over where and how your update contents get generated and what gets released to CodePush e.g. in CI setups, you can use the following workflow:
392+
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:
368393

369394
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.
370395
@@ -381,9 +406,15 @@ For scenarios where you require more control over where and how your update cont
381406
382407
*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.*
383408

384-
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 a [**targetBinaryRange**](http://codepush.tools/docs/cli.html#target-binary-range-parameter) that satisfies the app store version that this update targets (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.
409+
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.
385410

386411
For more info regarding the `release` command and its parameters, refer to the [CLI documentation](http://codepush.tools/docs/cli.html#releasing-app-updates).
412+
413+
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.
414+
415+
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.
416+
417+
*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!*
387418

388419
---
389420

@@ -757,3 +788,31 @@ The React Native community has graciously created some awesome open source apps
757788
* [MoveIt!](https://github.com/multunus/moveit-react-native) - An app by [Multunus](http://www.multunus.com) that allows employees within a company to track their work-outs.
758789

759790
*Note: If you've developed a React Native app using CodePush, that is also open-source, please let us know. We would love to add it to this list!*
791+
792+
## Debugging / Troubleshooting
793+
794+
The `sync` method includes a lot of diagnostic logging out-of-the-box, so if you're encountering an issue when using it, the best thing to try first is examining the output logs of your app. This will tell you whether the app is configured correctly (e.g. can the plugin find your deployment key?), if the app is able to reach the server, if an available update is being discovered, if the update is being successfully downloaded/installed, etc. We want to continue improving the logging to be as intuitive/comprehensive as possible, so please [let us know](mailto:codepushfeed@microsoft.com) if you find it to be confusing or missing anything.
795+
796+
![Xcode Console](https://cloud.githubusercontent.com/assets/116461/13536459/d2687bea-e1f4-11e5-9998-b048ca8d201e.png)
797+
798+
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:
799+
800+
1. Add an `#import "RCTLog.h"` statement
801+
802+
2. Add the following statement to the top of your `application:didFinishLaunchingWithOptions` method:
803+
804+
```objective-c
805+
RCTSetLogThreshold(RCTLogLevelInfo);
806+
```
807+
808+
Now you'll be able to see CodePush logs in either debug or release mode, on both iOS or Android. If examining the logs don't provide an indication of the issue, please refer to the following common issues for additional resolution ideas:
809+
810+
| Issue / Symptom | Possible Solution |
811+
|-----------------|-------------------|
812+
| Compilation Error | Double-check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using. |
813+
| Network timeout / hang when calling `sync` or `checkForUpadte` in the iOS Simulator | Try resetting the simulator by selecting the `Simulator -> Reset Content and Settings..` menu item, and then re-running your app. |
814+
| Server responds with a `404` when calling `sync` or `checkForUpdate` | Double-check that the deployment key you added to your `Info.plist` (iOS), `build.gradle` (Android) or that you're passing to `sync`/`checkForUpdate`, is in fact correct. You can run `code-push deployment ls [APP_NAME] -k` to view the correct keys for your app deployments. |
815+
| Update not being discovered | Double-check that the version of your running app (e.g. `1.0.0`) matches the version you specified when releasing the update to CodePush. Additionally, make sure that you are releasing to the same deployment that your app is configured to sync with. |
816+
| Update not being displayed after restart | If you're not calling `sync` on app start (e.g. within `componentDidMount` of your root component), then you need to explicitly call `notifyApplicationReady` on app start, otherwise, the plugin will think your update failed and roll it back. |
817+
| Images dissappear after installing CodePush update | If your app is using the React Native assets system to load images (i.e. the `require(./foo.png)` syntax), then you **MUST** release your assets along with your JS bundle to CodePush. Follow [these instructions](#releasing-updates-javascript--images) to see how to do this. |
818+
| No JS bundle is being found when running your app against the iOS simulator | By default, React Native doesn't generate your JS bundle when running against the simulator. Therefore, if you're using `[CodePush bundleURL]`, and targetting the iOS simulator, you may be getting a `nil` result. This issue will be fixed in RN 0.22.0, but only for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally.

0 commit comments

Comments
 (0)