使用CodePush热更新ReactNative JS代码
纠结了半天，不知要不要用ReactNative来开发新项目，
例如本地存储，例如webView 里面js 与native 的互动，例如地图，纠结。。。
通过查看文档，一一得到答案，还是很想用ReactNative做这个项目。
最吸引我的就是传说中的热更新。但是，，具体是怎么样才能热更新啊，
看了大部分翻译文档，没说这回事啊。。。
貌似只是在开发时候，用直接连本地服务器，可以直接reload，
难道上线后，也是直接连服务器来拿js ？不会吧？？？
那app 不能联机的时候呢？
后来看了文档，原来是打包时候可以打成一个bundle包，
我擦咧，那怎么更新厘米的包？没看到，那不是跟原生一样，要通过这个app store进行更新？
要不就是我自己来，在AppDelegate里面判断，是否需要更新，是就下载新的bundle包，下完毕，再load这个bundle给用户使用。
嗯，好吧，也就这优点？
刚好看了文章说他们的经验：
http://bbs.react-china.org/t/react-native/3169
最近1个月完成了一个RN的项目，这里记录一下，以备后面的总结
项目内容
1. 登录
2. 根据剪贴板的内容查找数据
3. 显示查找后的数据，并对这个数据进行一些处理
平台支持
iOS和Android
iOS已经上架2版
开发方式和架构内容
1. 使用Git作为版本管理
2. 使用Atom作为开发工具，XCode辅助，没有用Android Studio
3. 使用CodePush69作为js package的升级工具
4. 使用Redux作为React的数据框架
5. 使用Stackoverflow和React的issue list作为主要的知识查找
6. 开发了一些自己使用的Android的插件，因为Android不支持Onresume事件，所以自己写了插件，后面会open出来
7. 主要使用ios做开发，然后Android适配
8. 使用了自定义字体作为图标，进入了ttf文件
9. 使用eslint做js的静态检查
总结
1. ios还是比较稳定并且功能也比较全
2. Android的坑是有不少，比如：不支持Shadow，还有对absolute的布局支持的也不够好
3. Android的事件支持的不好，很多事件还没有支持
4. Android的性能好像也不是很好，但是，也能凑合用
5. Android的原生控件封装的不好
6. 如果希望代码复用高，最好让iOS和Android尽量保持样式的一致
7. 这篇文章对我在Mac上调试Android有很大帮助69
使用到的第三方库
1. Redux
2. Redux-react
3. ImmutableJS
4. moment
5. React-native 0.14.1
6. react-native-android-statusbar
7. react-native-clipboard ，因为owner很久不维护，我做了一些修改，后面会open出来
8. react-native-code-push
9. react-native-device
10. react-native-icons
11. react-native-keyboard-spacer
12. react-native-navbar"
13. react-native-simpledialog-android
14. redux-thunk
我擦咧，我只看到一句，就跟一见钟情似的：3. 使用CodePush69作为js package的升级工具
我就查资料去了，没有，，没人有教程给我，，，擦咧
好吧，老老实实看官方英文文档，祈求能用，不要浪费一天时间。
下面是我的安装经验：忙乱，因为每一步都有点心惊，怕出错，不知如何修复。
CodePush v1.40 安装使用
1， 开，在项目根目录输入：
npm install react-native-code-push -/-save //去掉-/-中的/
参数 —-save 在安装的同时，把信息写入package.json 文件的项目路径
如果npm 执行不了，因为网络原因，请使用cnpm 来代替
2，安装完毕，检查
a. package.json 文档加入了
"dependencies": {
"react-native": "^0.16.0",
"react-native-code-push": "^1.4.2-beta"
}
b. node_modules 下有 react-native-code-push 文件夹，里面有 CodePush.xcodeproj 这个文件，因为后面要加入到当前的项目中去
3，用Xcode 打开项目，点开Libraries 目录，
打开项目根目录下的 /node_modules/react-native-code-push ， 把文件 CodePush.xcodeproj 拉入 上面的Libraries 目录下作为依赖项目
打开 Xcode的项目－》target －》Build Phase －》 Link Binary With Libraries
把刚才拖进去的子项目CodePush.xcodeproj 点开，找到Products 目录，把红色的libCodePush.a拉进去
4，点击 Link Binary With Libraries 下面的加号， 查找 libz ， 选中iOS 9.1 下面的 libz.tbd
5，选择上面的标题为 Build Setings 查找Header Search Path， 双击值，弹出列表界面，
点击加号， 输入 $(SRCROOT)/../node_modules/react-native-code-push
选择后面的 recursive 选项
6，打开 AppDelegate.m ,
添加 #import “CodePush.h”
找到：
// jsCodeLocation = [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
jsCodeLocation = [CodePush bundleURL];
7，接下来是安装 code-push 服务器端
先看官网：https://github.com/Microsoft/code-push
看了半天，tmd要我安装 gulp，下载git源代码，再编译，，，吓傻了我，，，这不是我想要的生活
再用cnam search code-push 出来一个网页，第二行是 code-push-cli ，
好吧，安装 react-native-cli 有经验，嗯嗯，这个也类似吧。
还是仔细看了淘宝镜像的网页英文介绍，https://npm.taobao.org/package/code-push-cli#account-creation，原来是出自官网的cli文件夹里，https://github.com/Microsoft/code-push/tree/master/cli，
还好没有去编译，臣妾不熟啊，
确定下面是有code-push 服务器配置appName的事情，
才斗胆安装了这个，看下面的结果
MacdeiMac:~ mac$ cnpm install -g code-push-cli
WARN engine [email protected]: wanted: {"node":"0.x"} (current: {"node":"5.1.0","npm":"2.14.12"})
/Users/mac/.nvm/versions/node/v5.1.0/bin/code-push -> /Users/mac/.nvm/versions/node/v5.1.0/lib/node_modules/code-push-cli/script/cli.js
[email protected] /Users/mac/.nvm/versions/node/v5.1.0/lib/node_modules/code-push-cli
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
└── [email protected] ([email protected], [email protected])
试试看版本，貌似最新的哦
MacdeiMac:~ mac$ code-push -v
1.3.0-beta
8，根据英文指引，注册Code-Push帐号
终端输入 code-push register
弹出网页 https://codepush.azurewebsites.net/auth/register?hostname=MacdeiMac.local
看最后，貌似是我本机的机器名字，看终端
MacdeiMac:~ mac$
我输入了gitHub的帐号，一开始我以为我没有，进去后发觉有哦，
原来是[email protected] ，好吧，刚好也是为这个建立的，就用这个吧，反正后面可以log out
允许了权限之后，帮我注册了一个帐号，得到了token
MacdeiMac:~ mac$ code-push register
A browser is being launched to authenticate your account. Follow the instructions it displays to complete your registration.
Enter your access token: 这个要保密哦
eyxxxxxxxJ9
Successfully logged-in. Your session token was written to /Users/mac/.code-push.config. You can run the code-push logout command at any time to delete this file and terminate your session.
9，使用code-push 服务器
登陆 code-push login
注销 code-push logout
列出 登陆的token
code-push access-key ls
删除某个access-key
code-push access-key rm
其他功能暂时不想去试试，
MacdeiMac:~ mac$ code-push access-key ls
┌───────────────────────────────────────┬───────────────┬─────────────────┬─────────────┐
│ Key │ Time Created │ Created From │ Description │
├───────────────────────────────────────┼───────────────┼─────────────────┼─────────────┤
│ xmYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxVBl │ 6 minutes ago │ MacdeiMac.local │ Login │
└───────────────────────────────────────┴───────────────┴─────────────────┴─────────────┘
10，接下来是弄我们的app了，终于等到了
增加一个app进行管理
MacdeiMac:~ mac$ code-push app ls
┌──────┬─────────────┐
│ Name │ Deployments │
└──────┴─────────────┘
MacdeiMac:~ mac$ code-push app add SwitchCheck
Successfully added the "SwitchCheck" app, along with the following default deployments:
到了这里一直不出来，不知何事
强行ctrl c 出来，再看看列表
MacdeiMac:~ mac$ code-push app ls
[Error] connect ETIMEDOUT 23.101.203.117:443
好的，出问题了，估计网络问题，用 继续
MacdeiMac:~ mac$ code-push app ls
┌─────────────┬─────────────────────┐
│ Name │ Deployments │
├─────────────┼─────────────────────┤
│ SwitchCheck │ Production, Staging │
└─────────────┴─────────────────────┘
弄好了么？不知道，没底，看英文内容All new apps automatically come with two deployments (Staging and Production) so that you can begin distributing updates to multiple channels without needing to do anything extra (see deployment instructions below).
貌似ok
有命令： 更名 code-push app rename 旧名字 新名字
删除 code-push app rm 旧名字
11，部署管理
上面的部署类型 Production Staging，还可以自己加例如dev alpha beta等，
用语法 code-push deployment add app名字 部署名字
还可以重命名部署名字： code-push deployment rename app名字 旧部署名字 新部署名字
删除部署名字 code-push deployment rm app名字 部署名字
列表部署名字 code-push deployment ls app名字
MacdeiMac:~ mac$ code-push deployment ls SwitchCheck
┌────────────┬───────────────────────────────────────┬──────────────────┐
│ Name │ Deployment Key │ Package Metadata │
├────────────┼───────────────────────────────────────┼──────────────────┤
│ Production │ edxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBl │ │
├────────────┼───────────────────────────────────────┼──────────────────┤
│ Staging │ INxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxVBl │ │
└────────────┴───────────────────────────────────────┴──────────────────┘
OK
到了这里，应该回应在Xcode里info.plist里添加的CodePushDeploymentKey 的值，拷贝 Staging 的 key值 INcoNHeF7fVcSs4ZJNupzGJzYh49EyLxu0VBl到那里去，
再确保 Bundle Version String， short 这一行的值是 1.0.0 而不是 1.0
Android 的我没有尝试，内容如下：
Android Setup
In order to integrate CodePush into your Android project, perform the following steps:
Plugin Installation (Android)
- In your android/settings.gradle file, make the following additions:
include ':app', ':react-native-code-push' - project(':react-native-code-push').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-code-push/android/app')
- In your android/app/build.gradle file, add the :react-native-code-push project as a compile-time dependency:
... - dependencies {
- ...
- compile project(':react-native-code-push')
- }
Plugin Configuration (Android)
After installing the plugin and syncing your Android Studio project with Gradle, you need to configure your app to consult CodePush for the location of your JS bundle, since it will "take control" of managing the current and all future versions. To do this, perform the following steps:
- Update the MainActivity.java file to use CodePush via the following changes:
... - // 1. Import the plugin class
- import com.microsoft.codepush.react.CodePush;
- // 2. Optional: extend FragmentActivity if you intend to show a dialog prompting users about updates.
- // If you do this, make sure to also add "import android.support.v4.app.FragmentActivity" below #1.
- public class MainActivity extends FragmentActivity implements DefaultHardwareBackBtnHandler {
- ...
- @Override
- protected void onCreate(Bundle savedInstanceState) {
- ...
- // 3. Initialize CodePush with your deployment key and an instance of your MainActivity.
- CodePush codePush = new CodePush("d73bf5d8-4fbd-4e55-a837-accd328a21ba", this);
- ...
- mReactInstanceManager = ReactInstanceManager.builder()
- .setApplication(getApplication())
- ...
- // 4. DELETE THIS LINE --> .setBundleAssetName("index.android.bundle")
- // 5. Let CodePush determine which location to load the most updated bundle from.
- // If there is no updated bundle from CodePush, the location will be the assets
- // folder with the name of the bundle passed in, e.g. index.android.bundle
- .setJSBundleFile(codePush.getBundleUrl("index.android.bundle"))
- // 6. Expose the CodePush module to JavaScript.
- .addPackage(codePush.getReactPackage())
- ...
- }
- }
- 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")
android { - ...
- defaultConfig {
- ...
- versionName "1.0.0"
- ...
- }
- ...
- }
12，xcode里使用 插件
12.1 ，实现更新策略，
a，多久多频繁去check 更新，例如app 启动时，还是在setting 页面点击更新，或定时去更新
b，当一个更新出现，如何向用户展现
在javascript 文件里加入
var CodePush = require(“react-native-code-push”);
componentDidMount函数里加入 CodePush.sync(updateDialog: { title: "An update is available!" } });
如果有更新，将会被悄悄下载，在用户或系统重启app后，就会安装为新的
尽量不要表现得太invasive 强制性的更新
如果你想询问用户是否更新，或更好的体验，请使用sync 函数的提取信息，去更改默认的更新行为
12.2，只更新 js 文件，不更新图片等资源
a，到项目根目录，我自己新建一个文件夹，不是必须的，只是为了好打理，终端输入：
MacdeiMac:6-SwitchCheck mac$ mkdir bundles
MacdeiMac:6-SwitchCheck mac$ react-native bundle --parameter ios --entry-file index.ios.js --bundle-output ./bundles/SwitchCheck010000.js
bundle: Created ReactPackager
bundle: start
bundle: finish
bundle: Writing bundle output to: ./bundles/SwitchCheck010000.js
bundle: Done writing bundle output
bundle: Closing client
Assets destination folder is not set, skipping...
只更新js 文件，不需要通过Xcode 和 gradlew assemble 。用codePush 就够了
code-push release SwitchCheck ./bundles/SwitchCheck010000.js 1.0.0
这里用的是一个js文件就行了，下面带有图片等，则要用下面的语句，差别在于release 整个文件夹
12.3，更新 js 文件，和react-native打包的图片（不包括网络图片和images.xcassets），请使用下面的方法
同上面差不多，但你需要加上图片目录，-/-assets-dest ./bundles
确保文件夹 bundles 里面没有任何文件
react-native bundle --parameter ios --entry-file index.ios.js --bundle-output ./bundles/SwitchCheck010000.js --assets-dest ./bundles
bundle: Created ReactPackager
bundle: start
bundle: finish
bundle: Writing bundle output to: ./bundles/SwitchCheck010000.js
bundle: Done writing bundle output
bundle: Closing client
刚开始没有图片，所以只看到一个js文件，可能初创项目，没有图片
好了，用codePush命令
code-push release SwitchCheck ./bundles 1.0.0
那个code－push－cli工具会帮你打包送上去的
看上去似乎就是打包，然后release，文档上说无论release多少次，终端用户只会更新到他需要的文件，很智能是不是？
13，目前为止还没有指定要push的项目文件夹，心里疑惑
看到发布版本命令是
cide-push release appName package参数 appStoreVersion参数 [-/-deploymentName 部署名字] [-/-description 描述] [-/-mandatory true/false]
mandatory 的意思是强制的，－／－要去掉斜杠，因为编辑器自动把两个短横线变成了一个长横线，
不要执行，因为还没有package参数和 appStoreVersion参数，看下面，就跟项目文件夹有关了
13.1 解释 package参数
cd命令去到项目根目录下，根据ios 和 android不同，使用不同的命令，看上面，
| React Native (Android) |
react-native bundle --platform android --entry-file |
Value of the --bundle-output option |
| React Native (iOS) |
react-native bundle --platform ios --entry-file |
Value of the --bundle-output option |
13.2，解释appStoreVersion参数
没看懂，，不过貌似要求1.0.0 这个格式，后来就在这里出问题了，导致我半夜12:19分还在查找这个问题，请看上传了之后的解决问题的描述，所以，英文不熟，害死人啊
This specifies the semver compliant store/binary version of the application you are releasing the update for. Only users running this exact version will receive the update. This is important if your JavaScript/etc. takes a dependency on a new capabilitiy of the native side of your app (e.g. a Cordova plugin), and therefore, requires the user to update to the latest version from the app store before being able to get it.
The following table outlines the value that CodePush expects you to provide for each respective app type:
| Platform |
Source of app store version |
| Cordova |
The |
| React Native (Android) |
The android.defaultConfig.versionName property in your build.gradle file |
| React Native (iOS) |
The CFBundleShortVersionString key in the Info.plist file |
13.3 解释－／－deploymentName 部署名字，可以缩写为 －d
默认可以不给，使用的是Staging ，因此未发布的版本，请在xcode的info.plist上的 CFBundleShortVersionString
的值为和staging 那个 deployment key 是一样的
如果有了发布版本production ，才在Xcode的info.plist 的CFBundleShortVersionString换用这个production的key
13.4 解释 －／－description ，可以缩写为 －desc
用来记录这个版本的更新信息，另外可以用来在app 里获取之后向用户显示更新的内容
13.5 解释 －／－mandatory参数，可以缩写成 －m
是否强制更新，让用户是否有选择的余地
14，提升开发版本，dev 为 staging ，staging 为production ，
code-push promote appName sourceDeploymentName destDeploymentName
15，回退版本 rollback ，
code-push rollback appName deploymentName
回退到这个版本之前的一个版本，
16，查看release 的历史版本
code-push deployment history appName deploymentName
好啦，来安装到真机试试啦，不会更新，哈？深夜了哦，，，我想睡觉去了
没办法，不会是debug版本和release版本不一致吧？好，试试edit scheme，改debug为release 版本
结果遇到问题：编译不通过，貌似看过，好吧，去百度，果然，提前拷到我的博客了，问题是没碰过，还是要靠百度挖出来
http://my.oschina.net/imot/blog/512808?fromerr=KGezAdED
Xcode7上运行报错解决方法
在 Xcode7 指定真机运行，结果报出如下错误：
Undefined symbols for architecture arm64: "_RCTSetLogFunction", referenced from: -[PropertyFinderTests testRendersWelcomeScreen] in PropertyFinderTests.o ld: symbol(s) not found for architecture arm64 clang: error: linker command failed with exit code 1 (use -v to see invocation)
一开始以为的 React Native 库的问题，查找了一下资料，研究了一下，原来在 Build Setting 中设置 Dead Code Stripping 为 No （如下图）就可以解决了
测试url ： https://codepush.azurewebsites.net/updateCheck?deploymentKey=INxxxxBl&appVersion=1.0.0&packageHash=&isCompanion=
返回 {"updateInfo":{"downloadURL":"","description":"","isAvailable":false,"isMandatory":false,"appVersion":"1.0.3","packageHash":"","label":"","packageSize":0,"updateAppVersion":true}}
貌似不对，因为1.0.3 我设置为强制更新了，因此isMandatory":false,是错误的
妈蛋，12点了，在找这个问题，因为今天一天就是为了搞定这个啊。。。
还好，找了issue，找到这个 https://github.com/Microsoft/react-native-code-push/issues/83
这个同学跟我一样，不过他试出来问题在哪里了，
请看 https://codepush.azurewebsites.net/updateCheck?deploymentKey=INxxxxBl&appVersion=1.0.3
返回
{"updateInfo":{"downloadURL":"https://codepush.blob.core.windows.net/storagev2/eSxxxVBl","description":"Edit index.ios.js 3 mandatory to test Code-Push","isAvailable":true,"isMandatory":true,"appVersion":"1.0.3","packageHash":"c4xxxx3ffxx98668cd","label":"v3","updateAppVersion":false}}
我原想省一步，不要再bundle一个版本，就用现成的最新的那个包，
code-push release SwitchCheck ./bundles/SwitchCheck010003.js 1.0.0 --deploymentName Staging --description 'Edit index.ios.js 4 mandatory to test Code-Push' --mandatory true
Upload progress:[==================================================] 100% 0.0s
[Error] The uploaded package is identical to the contents of the specified deployment's current release.
结果出错了，原来会和服务器当前最新的比较，
所以我重新bundle了一个版本，release时候用的参数是1.0.0，代表1.0.0的app来检查，就会下载最新的版本4，嗯嗯，是有点让人困惑，请看上面的帖子https://github.com/Microsoft/react-native-code-push/issues/83
release 是可以一直以同一个版本号作为更新的基准的呢，还是很厉害。
MacdeiMac:6-SwitchCheck mac$ react-native bundle --parameter ios --entry-file index.ios.js --bundle-output ./bundles/SwitchCheck010000.js
bundle: Created ReactPackager
bundle: start
bundle: finish
bundle: Writing bundle output to: ./bundles/SwitchCheck010000.js
bundle: Done writing bundle output
bundle: Closing client
Assets destination folder is not set, skipping...
MacdeiMac:6-SwitchCheck mac$ code-push release SwitchCheck ./bundles/SwitchCheck010000.js 1.0.0 --deploymentName Staging --description 'Edit index.ios.js 4 mandatory to test Code-Push' --mandatory true
Upload progress:[==================================================] 100% 0.0s
Successfully released an update containing the "./bundles/SwitchCheck010000.js" file to the "Staging" deployment of the "SwitchCheck" app.
在模拟器上就真的，结果就能更新了哦：
看列表
MacdeiMac:6-SwitchCheck mac$ code-push deployment history SwitchCheck Staging
┌───────┬────────────────┬─────────────┬───────────┬───────────────────────────────┐
│ Label │ Release Time │ App Version │ Mandatory │ Description │
├───────┼────────────────┼─────────────┼───────────┼───────────────────────────────┤
│ v1 │ 2 hours ago │ 1.0.1 │ No │ Edit index.ios.js to test │
│ │ │ │ │ Code-Push │
├───────┼────────────────┼─────────────┼───────────┼───────────────────────────────┤
│ v2 │ an hour ago │ 1.0.2 │ No │ Edit index.ios.js 2nd to test │
│ │ │ │ │ Code-Push │
├───────┼────────────────┼─────────────┼───────────┼───────────────────────────────┤
│ v3 │ 44 minutes ago │ 1.0.3 │ Yes │ Edit index.ios.js 3 mandatory │
│ │ │ │ │ to test Code-Push │
├───────┼────────────────┼─────────────┼───────────┼───────────────────────────────┤
│ v4 │ 14 minutes ago │ 1.0.0 │ Yes │ Edit index.ios.js 4 mandatory │
│ │ │ │ │ to test Code-Push │
└───────┴────────────────┴─────────────┴───────────┴───────────────────────────────┘
原来，是我用code-push release 的时候，那个AppVersion参数说的是指定要已经发布出去的app的版本，而不是app本身会拿自己的版本比较我用code-push release出去的制定version，原理就是这样，release的命令是指定在app Store 上的版本更新不更新，以此为基准
留待以后看这些api
Xcode插件里的code-push 的API
以下来自：API reference
API Reference
The CodePush plugin is made up of two components:
- A JavaScript module, which can be imported/required, and allows the app to interact with the service during runtime (e.g. check for updates, inspect the metadata about the currently running app update).
- A native API (Objective-C and Java) which allows the React Native app host to bootstrap itself with the right JS bundle location.
The following sections describe the shape and behavior of these APIs in detail:
JavaScript API Reference
When you require react-native-code-push, the module object provides the following top-level methods:
- checkForUpdate: Asks the CodePush service whether the configured app deployment has an update available.
- getCurrentPackage: Retrieves the metadata about the currently installed update (e.g. description, installation time, size).
- notifyApplicationReady: Notifies the CodePush runtime that an installed update is considered successful. If you are manually checking for and installing updates (i.e. not using the sync method to handle it all for you), then this method MUST be called; otherwise CodePush will treat the update as failed and rollback to the previous version when the app next restarts.
- restartApp: Immediately restarts the app. If there is an update pending, it will be immediately displayed to the end user. Otherwise, calling this method simply has the same behavior as the end user killing and restarting the process.
- sync: 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
codePush.checkForUpdate(deploymentKey: String = null): Promise<RemotePackage>;
Queries the CodePush service to see whether the configured app deployment has an update available. By default, it will use the deployment key that is configured in your Info.plist file (iOS), or MainActivity.java file (Android), but you can override that by specifying a value via the optional deploymentKey parameter. This can be useful when you want to dynamically "redirect" a user to a specific deployment, such as allowing "Early access" via an easter egg or a user setting switch.
This method returns a Promise which resolves to one of two possible values:
- null if there is no update available.
- A RemotePackage instance which represents an available update that can be inspected and/or subsequently downloaded.
Example Usage:
codePush.checkForUpdate()
.then((update) => {
if (!update) {
console.log("The app is up to date!");
} else {
console.log("An update is available! Should we download it?");
}
});
codePush.getCurrentPackage
codePush.getCurrentPackage(): Promise<LocalPackage>;
Retrieves the metadata about the currently installed "package" (e.g. description, installation time). This can be useful for scenarios such as displaying a "what's new?" dialog after an update has been applied.
This method returns a Promise which resolves to the LocalPackage instance that represents the currently running update.
Example Usage:
codePush.getCurrentPackage()
.then((update) => {
// If the current app "session" represents the first time
// this update has run, and it had a description provided
// with it upon release, let's show it to the end user
if (update.isFirstRun && update.description) {
// Display a "what's new?" modal
}
});
codePush.notifyApplicationReady
codePush.notifyApplicationReady(): Promise
Notifies the CodePush runtime that a freshly installed update should be considered successful, and therefore, an automatic client-side rollback isn't necessary. It is mandatory to call this function somewhere in the code of the updated bundle. Otherwise, when the app next restarts, the CodePush runtime will assume that the installed update has failed and roll back to the previous version. This behavior exists to help ensure that your end users aren't blocked by a broken update.
If you are using the sync function, and doing your update check on app start, then you don't need to manually call notifyApplicationReady since sync will call it for you. This behavior exists due to the assumption that the point at which sync is called in your app represents a good approximation of a successful startup.
codePush.restartApp
codePush.restartApp(): void;
Immediately restarts the app. If there is an update pending, it will be presented to the end user and the rollback timer (if specified when installing the update) will begin. Otherwise, calling this method simply has the same behavior as the end user killing and restarting the process. This method is for advanced scenarios, and is primarily useful when the following conditions are true:
- Your app is specifying an install mode value of ON_NEXT_RESTART or ON_NEXT_RESUME when calling the sync or LocalPackage.install methods. This has the effect of not applying your update until the app has been restarted (by either the end user or OS) or resumed, and therefore, the update won't be immediately displayed to the end user .
- You have an app-specific user event (e.g. the end user navigated back to the app's home route) 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 or resume.
codePush.sync
codePush.sync(options: Object, syncStatusChangeCallback: function(syncStatus: Number), downloadProgressCallback: function(progress: DownloadProgress)): Promise<Number>;
Synchronizes your app's JavaScript bundle and image assets with the latest release to the configured deployment. Unlike the checkForUpdate method, which simply checks for the presence of an update, and let's you control what to do next, sync handles the update check, download and installation experience for you.
This method provides support for two different (but customizable) "modes" to easily enable apps with different requirements:
- Silent mode (the default behavior), which automatically downloads available updates, and applies them the next time the app restarts. This way, the entire update experience is "silent" to the end user, since they don't see any update prompt and/or "synthetic" app restarts.
- Active mode, which when an update is available, prompts the end user for permission before downloading it, and then immediately applies the update. If an update was released using the mandatory flag, the end user would still be notified about the update, but they wouldn't have the choice to ignore it.
Example Usage:
// Fully silent update which keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();
// Active update, which lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync({ updateDialog: true, installMode: codePush.InstallMode.IMMEDIATE });
Note: If you want to decide whether you check and/or download an available update based on the end user's device battery level, network conditions, etc. then simply wrap the call to sync in a condition that ensures you only call it when desired.
While the sync method tries to make it easy to perform silent and active updates with little configuration, it accepts an "options" object that allows you to customize numerous aspects of the default behavior mentioned above:
- 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 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. The following list represents the available options and their defaults:
- appendReleaseDescription (Boolean) - Indicates whether you would like to append the description of an available release to the notification message which is displayed to the end user. Defaults to false.
- descriptionPrefix (String) - Indicates the string you would like to prefix the release description with, if any, when displaying the update notification to the end user. Defaults to " Description: "
- mandatoryContinueButtonLabel (String) - The text to use for the button the end user must press in order to install a mandatory update. Defaults to "Continue".
- mandatoryUpdateMessage (String) - The text used as the body of an update notification, when the update is specified as mandatory. Defaults to "An update is available that must be installed.".
- optionalIgnoreButtonLabel (String) - The text to use for the button the end user can press in order to ignore an optional update that is available. Defaults to "Ignore".
- optionalInstallButtonLabel (String) - The text to use for the button the end user can press in order to install an optional update. Defaults to "Install".
- optionalUpdateMessage (String) - The text used as the body of an update notification, when the update is optional. Defaults to "An update is available. Would you like to install it?".
- title (String) - The text used as the header of an update notification that is displayed to the end user. Defaults to "Update available".
Example Usage:
// Use a different deployment key for this
// specific call, instead of the one configured
// in the Info.plist file
codePush.sync({ deploymentKey: "KEY" });
// Download the update silently
// but install is on the next resume
// instead of waiting until the app is restarted
codePush.sync({ installMode: 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!" } });
In addition to the options, the sync method also accepts two optional function parameters which allow you to subscribe to the lifecycle of the sync "pipeline" in order to display additional UI as needed (e.g. a "checking for update modal or a download progress modal):
- syncStatusChangedCallback ((syncStatus: Number) => void) - Called when the sync process moves from one stage to another in the overall update process. The method is called with a status code which represents the current state, and can be any of the SyncStatus values.
- downloadProgressCallback ((progress: DownloadProgress) => void) - Called periodically when an available update is being downloaded from the CodePush server. The method is called with a DownloadProgress object, which contains the following two properties:
- totalBytes (Number) - The total number of bytes expected to be received for this update package
- receivedBytes (Number) - The number of bytes downloaded thus far.
Example Usage:
// Prompt the user when an update is available
// and then display a "downloading" modal
codePush.sync({ updateDialog: true }, (status) => {
switch (status) {
case CodePush.SyncStatus.DOWNLOADING_PACKAGE:
// Show "downloading" modal
break;
case CodePush.SyncStatus.INSTALLING_UPDATE:
// Hide "downloading" modal
break;
}
});
This method returns a Promise which is resolved to a SyncStatus code that indicates why the sync call succeeded. This code can be one of the following SyncStatus values:
- CodePush.SyncStatus.UP_TO_DATE (4) - The app is up-to-date with the CodePush server.
- CodePush.SyncStatus.UPDATE_IGNORED (5) - The app had an optional update which the end user chose to ignore. (This is only applicable when the updateDialog is used)
- CodePush.SyncStatus.UPDATE_INSTALLED (6) - The update has been installed and will be run either immediately after the syncStatusChangedCallback function returns or the next time the app resumes/restarts, depending on the InstallMode specified in SyncOptions.
If the update check and/or the subsequent download fails for any reason, the Promise object returned by sync will be rejected with the reason.
The sync method can be called anywhere you'd like to check for an update. That could be in the componentWillMount lifecycle event of your root component, the onPress handler of a
Package objects
The checkForUpdate and getCurrentPackage methods return promises, that when resolved, provide acces to "package" objects. The package represents your code update as well as any extra metadata (e.g. description, mandatory?). The CodePush API has the distinction between the following types of packages:
- LocalPackage: Represents a downloaded update package that is either already running, or has been installed and is pending an app restart.
- RemotePackage: Represents an available update on the CodePush server that hasn't been downloaded yet.
LocalPackage
Contains details about an update that has been downloaded locally or already installed. You can get a reference to an instance of this object either by calling the module-level getCurrentPackage method, or as the value of the promise returned by the RemotePackage.download method.
Properties
- appVersion: The app binary version that this update is dependent on. This is the value that was specified via the appStoreVersion parameter when calling the CLI's release command. (String)
- deploymentKey: The deployment key that was used to originally download this update. (String)
- description: The description of the update. This is the same value that you specified in the CLI when you released the update. (String)
- failedInstall: Indicates whether this update has been previously installed but was rolled back. The sync method will automatically ignore updates which have previously failed, so you only need to worry about this property if using checkForUpdate. (Boolean)
- isFirstRun: Indicates whether this is the first time the update has been run after being installed. This is useful for determining whether you would like to show a "What's New?" UI to the end user after installing an update. (Boolean)
- isMandatory: Indicates whether the update is considered mandatory. This is the value that was specified in the CLI when the update was released. (Boolean)
- label: The internal label automatically given to the update by the CodePush server. This value uniquely identifies the update within it's deployment. (String)
- packageHash: The SHA hash value of the update. (String)
- packageSize: The size of the code contained within the update, in bytes. (Number)
Methods
- install(installMode: CodePush.InstallMode = CodePush.InstallMode.ON_NEXT_RESTART): Promise
: 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 enum reference for a description of the available options and what they do.
RemotePackage
Contains details about an update that is available for download from the CodePush server. You get a reference to an instance of this object by calling the checkForUpdate method when an update is available. If you are using the sync API, you don't need to worry about the RemotePackage, since it will handle the download and installation process automatically for you.
Properties
The RemotePackage inherits all of the same properties as the LocalPackage, but includes one additional one:
- downloadUrl: The URL at which the package is available for download. This property is only needed for advanced usage, since the download method will automatically handle the acquisition of updates for you. (String)
Methods
- download(downloadProgressCallback?: Function): Promise
: 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.
Enums
The CodePush API includes the following enums which can be used to customize the update experience:
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.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.
- CodePush.InstallMode.ON_NEXT_RESUME (2) - Indicates that you want to install the update, but don't want to restart the app until the next time the end user resumes it from the background. This way, you don't disrupt their current session, but you can get the update in front of them sooner then having to wait for the next natural restart. This value is appropriate for silent installs that can be applied on resume in a non-invasive way.
SyncStatus
This enum is provided to the syncStatusChangedCallback function that can be passed to the sync method, in order to hook into the overall update process. It includes the following values:
- CodePush.SyncStatus.CHECKING_FOR_UPDATE (0) - The CodePush server is being queried for an update.
- CodePush.SyncStatus.AWAITING_USER_ACTION (1) - An update is available, and a confirmation dialog was shown to the end user. (This is only applicable when the updateDialog is used)
- CodePush.SyncStatus.DOWNLOADING_PACKAGE (2) - An available update is being downloaded from the CodePush server.
- CodePush.SyncStatus.INSTALLING_UPDATE (3) - An available update was downloaded and is about to be installed.
- CodePush.SyncStatus.UP_TO_DATE (4) - The app is fully up-to-date with the configured deployment.
- CodePush.SyncStatus.UPDATE_IGNORED (5) - The app has an optional update, which the end user chose to ignore. (This is only applicable when the updateDialog is used)
- CodePush.SyncStatus.UPDATE_INSTALLED (6) - An available update has been installed and will be run either immediately after the syncStatusChangedCallback function returns or the next time the app resumes/restarts, depending on the InstallMode specified in SyncOptions.
- CodePush.SyncStatus.UNKNOWN_ERROR (-1) - The sync operation encountered an unknown error.
Objective-C API Reference (iOS)
The Objective-C API is made available by importing the CodePush.h header into your AppDelegate.m file, and consists of a single public class named CodePush.
CodePush
Contains static methods for retreiving the NSURL that represents the most recent JavaScript bundle file, and can be passed to the RCTRootView's initWithBundleURL method when bootstrapping your app in the AppDelegate.m file.
The CodePush class' methods can be thought of as composite resolvers which always load the appropriate bundle, in order to accomodate the following scenarios:
- When an end-user installs your app from the store (e.g. 1.0.0), they will get the JS bundle that is contained within the binary. This is the behavior you would get without using CodePush, but we make sure it doesn't break :)
- As soon as you begin releasing CodePush updates, your end-users will get the JS bundle that represents the latest release for the configured deployment. This is the behavior that allows you to iterate beyond what you shipped to the store.
- As soon as you release an update to the app store (e.g. 1.1.0), and your end-users update it, they will once again get the JS bundle that is contained within the binary. This behavior ensures that CodePush updates that targetted a previous app store version aren't used (since we don't know it they would work), and your end-users always have a working version of your app.
- Repeat #2 and #3 as the CodePush releases and app store releases continue on into infinity (and beyond?)
Because of this behavior, you can safely deploy updates to both the app store(s) and CodePush as neccesary, and rest assured that your end-users will always get the most recent version.
Methods
- (NSURL *)bundleURL - Returns the most recent JS bundle NSURL as described above. This method assumes that the name of the JS bundle contained within your app binary is main.jsbundle.
- (NSURL *)bundleURLForResource:(NSString *)resourceName - Equivalent to the bundleURL method, but also allows customizing the name of the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file main (which is the default convention). This method assumes that the JS bundle's extension is *.jsbundle.
- (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)resourceExtension: Equivalent to the bundleURLForResource: method, but also allows customizing the extension used by the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file *.jsbundle (which is the default convention).
Java API Reference (Android)
The Java API is made available by importing the com.microsoft.codepush.react.CodePush class into your MainActivity.java file, and consists of a single public class named CodePush.
CodePush
Constructs the CodePush client runtime and includes methods for integrating CodePush into your app's ReactInstanceManager.
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.
Methods
- getBundleUrl(String bundleName) - Returns the path to the most recent version of your app's JS bundle file, using the specified resource name (e.g. index.android.bundle). 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.