add document

2025-10-31 21:33:12 +08:00 · 2016-04-05 17:55:04 +08:00
parent e13675522c
commit 6f7c7e8978
5 changed files with 320 additions and 0 deletions
--- a/README.md
+++ 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)发帖提问。
--- a/docs/guide.md
+++ 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)
--- a/docs/guide2.md
+++ 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 (
+      <View style={styles.container}>
+        <Text style={styles.welcome}>
+          欢迎使用热更新服务
+        </Text>
+        <Text style={styles.instructions}>
+          这是版本一 {'\n'}
+          当前包版本号: {packageVersion}{'\n'}
+          当前版本Hash: {currentVersion||'(空)'}{'\n'}
+        </Text>
+        <TouchableOpacity onPress={this.checkUpdate}>
+          <Text style={styles.instructions}>
+            点击这里检查更新
+          </Text>
+        </TouchableOpacity>
+      </View>
+    );
+  }
+}
+
+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)
--- a/docs/guide3.md
+++ 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 <your-package.ipa>
+```
+
--- 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) {