From 6f7c7e8978f529abda605bd1b77fceab1ada6ac2 Mon Sep 17 00:00:00 2001 From: tdzl2003 Date: Tue, 5 Apr 2016 17:55:04 +0800 Subject: [PATCH] add document --- README.md | 34 ++++++++++ docs/guide.md | 98 ++++++++++++++++++++++++++++ docs/guide2.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/guide3.md | 18 ++++++ lib/index.js | 1 + 5 files changed, 320 insertions(+) create mode 100644 README.md create mode 100644 docs/guide.md create mode 100644 docs/guide2.md create mode 100644 docs/guide3.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..04db06c --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# react-native-update + +本组件是面向React Native提供热更新功能的组件，建议结合[Update服务](http://update.reactnative.cn/)使用。 + +### 优势 + +1. 命令行工具&网页双端管理，版本发布过程简单便捷，完全可以集成CI。 +2. 基于bsdiff算法创建的超小更新包，通常版本迭代后在1-10KB之间，避免数百KB的流量消耗。 +3. 支持崩溃回滚，安全可靠。 +4. meta信息及开放API，提供更高扩展性。 + +### 安装与快速入门 + +请查阅 + +* [文档-快速入门-准备工作](docs/guide.md)。 + +* [文档-快速入门-添加热更新功能](docs/guide2.md)。 + +* [文档-快速入门-发布版本](docs/guide3.md)。 + +### 命令行工具 + +请查阅[文档-命令行工具](docs/cli.md)。 + +### API接口 + +请查阅[文档-API接口](docs/api.md)。 + +### 关于我们 + +本组件由[React Native 中文网](http://reactnative.cn/)独家发布，如有定制需求可以[联系我们](http://reactnative.cn/about.html#content)。 + +关于此插件发现任何问题，可以前往[Issues](https://github.com/reactnativecn/react-native-pushy/issues)或者[中文社区](http://bbs.reactnative.cn/category/7)发帖提问。 diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..fa5765e --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,98 @@ +# 快速入门-准备工作 + +首先你应该有一个基于React Native开发的应用，我们把具有package.json的目录叫做你的"应用根目录"。 + +如果你还没有初始化应用，请参阅[开始使用React Native](http://reactnative.cn/docs/0.22/getting-started.html#content)。 + +所以我们也假设你已经拥有了开发React Native应用的一切环境，包括`Node.js`、`npm`、`XCode`、`Android SDK`等等。 + +如果你之前没安装过，你还必须安装[Android NDK](http://androiddevtools.cn)，并设置环境变量`ANDROID_NDK`，指向你的NDK根目录(例如`/Users/tdzl2003/Downloads/android-ndk-r10e`)。 + +## 安装 + +在你的项目根目录下运行以下命令(不要输入开头的美元符号)： + +```bash +$ npm install -g react-native-update-cli rnpm +$ npm install --save react-native-update +$ rnpm link react-native-update +``` + +> 其中第一句，在每一台电脑上仅需运行一次。 + +## 配置Bundle URL(iOS) + +// 文档建设中 + +## 配置Bundle URL(Android) + +在你的ReactActivity中增加如下代码： + +```java +// ... 其它代码 + +import cn.reactnative.modules.update.UpdateContext; +import cn.reactnative.modules.update.UpdatePackage; + +public class MainActivity extends ReactActivity { + + @Override + protected String getJSBundleFile() { + return UpdateContext.getBundleUrl(this); + } + // ... 其它代码 +} +``` + +## 登录与创建应用 + +在你的项目根目录下运行以下命令： + +```bash +$ pushy login +email: <输入你的注册邮箱> +password: <输入你的密码> +``` + +这会在项目文件夹下创建一个`.update`文件，注意不要把这个文件上传到Git等CVS系统上。你可以在`.gitignore`末尾增加一行`.update`来忽略这个文件。 + +登录之后可以创建应用。注意iOS平台和安卓平台需要分别创建： + +```bash +$ pushy createApp --platform ios +App Name: <输入应用名字> +$ pushy createApp --platform android +App Name: <输入应用名字> +``` + +> 两次输入的名字可以相同，这没有关系。 + +如果你已经在网页端或者其它地方创建过应用，也可以直接选择应用： + +```bash +$ pushy selectApp --platform ios +1) 鱼多多(ios) +3) 支付宝(ios) + +Total 2 apps +Enter appId: <输入应用前面的编号> +``` + +选择或者创建过应用后，你将可以在文件夹下看到`update.json`文件，其内容类似如下形式： + +```bash +{ + "ios": { + "appId": 1, + "appKey": "<一串随机字符串>" + }, + "android": { + "appId": 2, + "appKey": "<一串随机字符串>" + } +} +``` + +你可以安全的把`update.json`上传到Git等CVS系统上，与你的团队共享这个文件，它不包含任何敏感信息。当然，他们在使用任何功能之前，都必须先进行 + +至此应用的创建/选择就已经成功了。下一步，你需要给代码添加相应的功能，请参阅[添加热更新功能](guide2.md) diff --git a/docs/guide2.md b/docs/guide2.md new file mode 100644 index 0000000..dfdd5b9 --- /dev/null +++ b/docs/guide2.md @@ -0,0 +1,169 @@ +# 快速入门-添加热更新功能 + +## 获取appKey + +检查更新时必须提供你的`appKey`，这个值保存在`update.json`中，并且根据平台不同而不同。你可以用如下的代码获取： + +```javascript +import React, { + Platform, +} from 'react-native'; + +import _updateConfig from '../update.json'; +const {appKey} = _updateConfig[Platform.OS]; +``` + +如果你不使用pushy命令行，你也可以从网页端查看到两个应用appKey，并根据平台的不同来选择。 + +## 检查更新、下载更新 + +异步函数checkUpdate可以检查当前版本是否需要更新： + +```javascript +checkUpdate(appKey) + .then(info => { + }) + +``` + +返回的info有三种情况： + +1. `{expired: true}`：该应用包(原生部分)已过期，需要前往应用市场下载新的版本。 + +2. `{upToDate: true}`：当前已经更新到最新，无需进行更新。 + +3. `{update: true}`：当前有新版本可以更新。info的`name`、`description`字段可 +以用于提示用户，而`metaInfo`字段则可以根据你的需求自定义其它属性(如是否静默更新、 +是否强制更新等等)。另外还有几个字段，包含了完整更新包或补丁包的下载地址， +react-native-update会首先尝试耗费流量更少的更新方式。将info对象传递给downloadUpdate作为参数即可。 + +## 切换版本 + +downloadUpdate的返回值是一个hash字符串，它是当前版本的唯一标识。 + +你可以使用`switchVersion`函数立即切换版本(此时应用会立即重新加载)，或者选择调用 +`switchVersionLater`，让应用在下一次启动的时候再加载新的版本。 + +## 首次启动、回滚 + +在每次更新完毕后的首次启动时，`isFirstTime`常量会为`true`。 +你必须在应用退出前合适的任何时机，调用`markSuccess`，否则应用下一次启动的时候将会进行回滚操作。 +这一机制称作“反触发”，这样当你应用启动初期即遭遇问题的时候，也能在下一次启动时恢复运作。 + +你可以通过`isFirstTime`来获知这是当前版本的首次启动，也可以通过`isRolledBack`来获知应用刚刚经历了一次回滚操作。 +你可以在此时给予用户合理的提示。 + +## 完整的示例 + +```javascript +import React, { + AppRegistry, + Component, + StyleSheet, + Platform, + Text, + View, + Alert, + TouchableOpacity, + Linking, +} from 'react-native'; + +import { + isFirstTime, + isRolledBack, + packageVersion, + currentVersion, + checkUpdate, + downloadUpdate, + switchVersion, + switchVersionLater, + markSuccess, +} from 'react-native-update'; + +import _updateConfig from '../update.json'; +const {appKey} = _updateConfig[Platform.OS]; + +class MyProject extends Component { + componentWillMount(){ + if (isFirstTime) { + Alert.alert('提示', '这是当前版本第一次启动,是否要模拟启动失败?失败将回滚到上一版本', [ + {text: '是', onPress: ()=>{throw new Error('模拟启动失败,请重启应用')}}, + {text: '否', onPress: ()=>{markSuccess()}}, + ]); + } else if (isRolledBack) { + Alert.alert('提示', '刚刚更新失败了,版本被回滚.'); + } + } + doUpdate = info => { + downloadUpdate(info).then(hash => { + Alert.alert('提示', '下载完毕,是否重启应用?', [ + {text: '是', onPress: ()=>{switchVersion(hash);}}, + {text: '否',}, + {text: '下次启动时', onPress: ()=>{switchVersionLater(hash);}}, + ]); + }).catch(err => { + Alert.alert('提示', '更新失败.'); + }); + }; + checkUpdate = () => { + checkUpdate(appKey).then(info => { + if (info.expired) { + Alert.alert('提示', '您的应用版本已更新,请前往应用商店下载新的版本', [ + {text: '确定', onPress: ()=>{info.downloadUrl && Linking.openURL(info.downloadUrl)}}, + ]); + } else if (info.upToDate) { + Alert.alert('提示', '您的应用版本已是最新.'); + } else { + Alert.alert('提示', '检查到新的版本,是否下载?\n'+ info.description, [ + {text: '是', onPress: ()=>{this.doUpdate(info)}}, + {text: '否',}, + ]); + } + }).catch(err => { + Alert.alert('提示', '更新失败.'); + }); + } + render() { + return ( + + + 欢迎使用热更新服务 + + + 这是版本一 {'\n'} + 当前包版本号: {packageVersion}{'\n'} + 当前版本Hash: {currentVersion||'(空)'}{'\n'} + + + + 点击这里检查更新 + + + + ); + } +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + backgroundColor: '#F5FCFF', + }, + welcome: { + fontSize: 20, + textAlign: 'center', + margin: 10, + }, + instructions: { + textAlign: 'center', + color: '#333333', + marginBottom: 5, + }, +}); + +AppRegistry.registerComponent('MyProject', () => MyProject); +``` + +现在，你的应用已经可以通过update服务检查版本并进行更新了。下一步，你可以开始尝试发布应用包和版本，请参阅[发布应用](guide3.md) diff --git a/docs/guide3.md b/docs/guide3.md new file mode 100644 index 0000000..53ec400 --- /dev/null +++ b/docs/guide3.md @@ -0,0 +1,18 @@ +# 快速入门-发布应用 + +现在你的应用已经具备了检测更新的功能，下面我们来尝试发布并更新它。 + +## 发布iOS应用 + +首先参考[文档-在设备上运行](http://reactnative.cn/docs/0.22/running-on-device-ios.html#content)， +确定你正在使用离线包。然后点击菜单。 + +注意，从update上传发布版本到发布版本正式上线期间，不要修改任何脚本和资源，这会影响update +获取本地代码，从而导致版本不能更新。如果在发布之前修改了脚本或资源，请在网页端删除之前上传的版本并重新上传。 + +按照正常的发布流程打包`.ipa`文件(Product-Achieve)，然后运行如下命令 + +```bash +$ pushy uploadIpa +``` + diff --git a/lib/index.js b/lib/index.js index 9ba14d7..00c1107 100644 --- a/lib/index.js +++ b/lib/index.js @@ -77,6 +77,7 @@ export async function downloadUpdate(options) { hashName: options.hash, }); } + return options.hash; } export async function switchVersion(hash) {