From 5bcee498c580cda85298fbc1ee0c5dc6a0bc6185 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Thu, 3 Mar 2016 09:49:45 -0800 Subject: [PATCH 1/7] Adding docs for RNPM/CocoaPods installation --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b023079..9639143 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ This plugin provides client-side integration for the [CodePush service](http://c * [Getting Started](#getting-started) * [iOS Setup](#ios-setup) * [Plugin Installation](#plugin-installation-ios) + * [RNPM](#plugin-installation-ios---rnpm) + * [CocoaPods](#plugin-installation-ios---cocoapods) + * ["Manual"](#plugin-installation-ios---manual) * [Plugin Configuration](#plugin-configuration-ios) * [Android Setup](#android-setup) * [Plugin Installation](#plugin-installation-android) @@ -80,16 +83,54 @@ If you want to see how other projects have integrated with CodePush, you can che ## iOS Setup -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: +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: ### Plugin Installation (iOS) +In order to accomodate as many developer preferences as possible, the CodePush plugin supports iOS installation via three mechanisms: + +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. + +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. + +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. + +#### Plugin Installation (iOS - RNPM) + +1. Run `rnpm link react-native-code-push` + +2. Open your app's Xcode project + +3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration. + +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. + + ![Libz reference](https://cloud.githubusercontent.com/assets/116461/11605042/6f786e64-9aaa-11e5-8ca7-14b852f808b1.png) + + *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`.* + +We hope to eventually remove the need for steps #2-4, but in the meantime, RNPM doesn't support automating them. + +#### Plugin Installation (iOS - CocoaPods) + +1. Add the CodePush plugin dependency to your `Podfile`, pointing at the path where NPM installed it + + ```ruby + pod 'CodePush', :path => './node_modules/react-native-code-push` + ``` + +2. Run `pod install` + +#### Plugin Installation (iOS - Manual) + 1. Open your app's Xcode project + 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 ![Add CodePush to project](https://cloud.githubusercontent.com/assets/8598682/13368613/c5c21422-dca0-11e5-8594-c0ec5bde9d81.png) 3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration. + 4. Drag `libCodePush.a` from `Libraries/CodePush.xcodeproj/Products` into the "Link Binary With Libraries" section of your project's "Build Phases" configuration. ![Link CodePush during build](https://cloud.githubusercontent.com/assets/516559/10322221/a75ea066-6c31-11e5-9d88-ff6f6a4d6968.png) From 7f1735ad1f191298bda4dedaf748c2a4aad812e9 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Thu, 3 Mar 2016 12:29:06 -0800 Subject: [PATCH 2/7] Adding RNPM install instructions --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 9639143..8b82695 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,8 @@ In order to accomodate as many developer preferences as possible, the CodePush p 1. Run `rnpm link react-native-code-push` + *Note: If you didn't already have RNPM installed, you can do so by running `npm i -g rnpm` and the executing the above command once `rnpm` is in your path.* + 2. Open your app's Xcode project 3. Select the project node in Xcode and select the "Build Phases" tab of your project configuration. From 1e60aeaa8d7f700bb664a2cbdecdd0a9b2f2c168 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Thu, 3 Mar 2016 12:34:11 -0800 Subject: [PATCH 3/7] Fixing typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8b82695..c5449d6 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ In order to accomodate as many developer preferences as possible, the CodePush p 1. Run `rnpm link react-native-code-push` - *Note: If you didn't already have RNPM installed, you can do so by running `npm i -g rnpm` and the executing the above command once `rnpm` is in your path.* + *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.* 2. Open your app's Xcode project From 69f41c7886a542c37cb74152845e491551fd5393 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Fri, 4 Mar 2016 13:35:38 -0800 Subject: [PATCH 4/7] Troubleshooting docs --- README.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c5449d6..6245b6c 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ This plugin provides client-side integration for the [CodePush service](http://c * [Objective-C API Reference (iOS)](#objective-c-api-reference-ios) * [Java API Reference (Android)](#java-api-reference-android) * [Example Apps](#example-apps) +* [Debugging / Troubleshooting](#debugging--troubleshooting) ## How does it work? @@ -380,7 +381,7 @@ react-native bundle --platform ios --entry-file index.ios.js --bundle-output cod code-push release MyApp codepush.js 1.0.0 ``` -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). +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 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.* @@ -411,6 +412,8 @@ If you are using the new React Native [assets system](https://facebook.github.io 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, you 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!* --- @@ -785,3 +788,31 @@ The React Native community has graciously created some awesome open source apps * [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. *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!* + +## Debugging / Troubleshooting + +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 intutuive/comprehensive as possible, so please [let us know](mailto:codepushfeed@microsoft.com) if you find it to be confusing or missing anything. + +![Xcode Console](https://cloud.githubusercontent.com/assets/116461/13536459/d2687bea-e1f4-11e5-9998-b048ca8d201e.png) + +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: + +1. Add an `#import "RCTLog.h"` statement + +2. Add the following statement to the top of your `application:didFinishLaunchingWithOptions` method: + + ```objective-c + RCTSetLogThreshold(RCTLogLevelInfo); + ``` + +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: + +| Issue / Symptom | Possible Solution | +|-----------------|-------------------| +| Compilation Error | Double check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using | +| Network timeout / hang when calling `sync` or `checkForUpadte` in the iOS Simulator | Try resetting it the simulator by selecting the `Simulator -> Reset Content and Settings..` menu item. | +| 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 correct. You can run `code-push deployment ls [APP_NAME] -k` to view the correct keys for your app deployments. | +| 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 you're app is configured to sync with. | +| 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. | +| 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. | +| No JS bundle is being found (iOS) when running your app against the simulator | By default, React Native doesn't generate and bundle your JS bundle in the binary 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, specifically for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally. \ No newline at end of file From 87d968d634138fa5e5fa20b35915edec77161d5c Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Fri, 4 Mar 2016 14:08:45 -0800 Subject: [PATCH 5/7] Fixing typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6245b6c..d478d10 100644 --- a/README.md +++ b/README.md @@ -791,7 +791,7 @@ The React Native community has graciously created some awesome open source apps ## Debugging / Troubleshooting -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 intutuive/comprehensive as possible, so please [let us know](mailto:codepushfeed@microsoft.com) if you find it to be confusing or missing anything. +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. ![Xcode Console](https://cloud.githubusercontent.com/assets/116461/13536459/d2687bea-e1f4-11e5-9998-b048ca8d201e.png) @@ -812,7 +812,7 @@ Now you'll be able to see CodePush logs in either debug or release mode, on both | Compilation Error | Double check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using | | Network timeout / hang when calling `sync` or `checkForUpadte` in the iOS Simulator | Try resetting it the simulator by selecting the `Simulator -> Reset Content and Settings..` menu item. | | 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 correct. You can run `code-push deployment ls [APP_NAME] -k` to view the correct keys for your app deployments. | -| 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 you're app is configured to sync with. | +| 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. | | 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. | -| 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. | +| 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. | | No JS bundle is being found (iOS) when running your app against the simulator | By default, React Native doesn't generate and bundle your JS bundle in the binary 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, specifically for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally. \ No newline at end of file From feefa56d02eea41926c43e957d140acf537be022 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Fri, 4 Mar 2016 14:47:45 -0800 Subject: [PATCH 6/7] Adding missing word --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d478d10..e8e1422 100644 --- a/README.md +++ b/README.md @@ -381,7 +381,7 @@ react-native bundle --platform ios --entry-file index.ios.js --bundle-output cod code-push release MyApp codepush.js 1.0.0 ``` -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 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. +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.* @@ -412,7 +412,7 @@ If you are using the new React Native [assets system](https://facebook.github.io 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, you 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!* @@ -815,4 +815,4 @@ Now you'll be able to see CodePush logs in either debug or release mode, on both | 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. | | 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. | | 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. | -| No JS bundle is being found (iOS) when running your app against the simulator | By default, React Native doesn't generate and bundle your JS bundle in the binary 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, specifically for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally. \ No newline at end of file +| No JS bundle is being found (iOS) when running your app against the simulator | By default, React Native doesn't generate and bundle your JS bundle in the binary 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, specifically for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally. From 6cdb80be8001f20e132cc4eaebf71aa98b67b699 Mon Sep 17 00:00:00 2001 From: Jonathan Carter Date: Fri, 4 Mar 2016 14:51:37 -0800 Subject: [PATCH 7/7] Fixing typos --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e8e1422..1b8acd6 100644 --- a/README.md +++ b/README.md @@ -809,10 +809,10 @@ Now you'll be able to see CodePush logs in either debug or release mode, on both | Issue / Symptom | Possible Solution | |-----------------|-------------------| -| Compilation Error | Double check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using | -| Network timeout / hang when calling `sync` or `checkForUpadte` in the iOS Simulator | Try resetting it the simulator by selecting the `Simulator -> Reset Content and Settings..` menu item. | -| 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 correct. You can run `code-push deployment ls [APP_NAME] -k` to view the correct keys for your app deployments. | +| Compilation Error | Double-check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using. | +| 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. | +| 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. | | 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. | | 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. | | 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. | -| No JS bundle is being found (iOS) when running your app against the simulator | By default, React Native doesn't generate and bundle your JS bundle in the binary 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, specifically for release builds. You can unblock this scenario right now by making [this change](https://github.com/facebook/react-native/commit/9ae3714f4bebdd2bcab4d7fdbf23acebdc5ed2ba) locally. +| 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.