文档
代码集成

请注意,当前版本的api经过了完全重构,与之前的版本(v10.0以下)不兼容。如果你需要查看之前版本的文档,请点击这里 (opens in a new tab)

安装配置完成后,确定应用编译顺利通过,下面我们来进行代码集成。

获取 appKey

检查更新时必须提供你的appKey,这个值保存在update.json中(使用pushy createApppushy selectApp命令后会自动生成),并且根据平台不同而不同。你可以用如下的代码获取appKey

import { Platform } from "react-native";
 
import _updateConfig from "./update.json";
const { appKey } = _updateConfig[Platform.OS];

如果你不使用 pushy 命令行,也可以从网页端查看到两个应用 appKey,并根据平台的不同来选择。

初始化服务

import { PushyProvider, Pushy } from "react-native-update";
 
// 唯一必填参数是appKey,其他选项请参阅 api 文档
const pushyClient = new Pushy({
  appKey,
  // 注意,默认情况下,在开发环境中不会检查更新
  // 如需在开发环境中调试更新,请设置debug为true
  // 但即便打开此选项,也仅能检查、下载热更,并不能实际应用热更。实际应用热更必须在release包中进行。
  // debug: true
});
 
// 在根组件外加上PushyProvider后导出
export default function Root() {
  // 注意,在使用 PushyProvider 的当前组件中,无法直接调用 usePushy
  // 只有当前组件的子组件才能调用 usePushy
  return (
    <PushyProvider client={pushyClient}>
      {/* ↓ 整个应用的根组件放到PushyProvider中 */}
      <App />
    </PushyProvider>
  );
}

如没有特别的自定义需求,那么到此热更新已经可以开始正常运作(如需在应用内执行 apk 更新,还需配置安装权限)。默认配置下,在 App 启动,以及从后台切换到前台时会触发更新检查,弹出提示的内容也固定。

如需自定义触发时机,以及修改界面提示等,请参考下面的自定义更新界面。

自定义更新界面

默认配置下,pushy 会以系统 alert 的形式来弹出更新提示,如需自定义更新界面,首先请关闭默认的 updateStrategy 更新策略,并打开 debug 选项以便调试:

const pushyClient = new Pushy({
  appKey,
+  updateStrategy: null,
+  debug: true,
});

所有更新相关的数据可以通过一个单一的usePushy()hook 函数来获取,然后可以根据其提供的数据来自行渲染自定义的界面,如下面的例子:

import { Icon, PaperProvider, Snackbar, Banner } from "react-native-paper";
function App() {
  const {
    client,
    checkUpdate,
    downloadUpdate,
    switchVersionLater,
    switchVersion,
    updateInfo,
    packageVersion,
    currentHash,
    progress: { received, total } = {},
  } = usePushy();
  const [showUpdateBanner, setShowUpdateBanner] = useState(false);
  const [showUpdateSnackbar, setShowUpdateSnackbar] = useState(false);
  const snackbarVisible = showUpdateSnackbar && updateInfo?.update;
  return (
    <View style={styles.container}>
      <Text>
        更新下载进度:{received} / {total}
      </Text>
      <Pressable onPress={checkUpdate}>
        <Text>点击这里检查更新</Text>
      </Pressable>
      {snackbarVisible && (
        <Snackbar
          visible={true}
          onDismiss={() => {
            setShowUpdateSnackbar(false);
          }}
          action={{
            label: "更新",
            onPress: async () => {
              setShowUpdateSnackbar(false);
              if (await downloadUpdate()) {
                setShowUpdateBanner(true);
              }
            },
          }}
        >
          <Text>有新版本({updateInfo.name})可用,是否更新?</Text>
        </Snackbar>
      )}
      <Banner
        style={{ width: "100%", position: "absolute", top: 0 }}
        visible={showUpdateBanner}
        actions={[
          {
            label: "立即重启",
            onPress: switchVersion,
          },
          {
            label: "下次再说",
            onPress: () => {
              switchVersionLater();
              setShowUpdateBanner(false);
            },
          },
        ]}
        icon={({ size }) => (
          <Icon name="checkcircleo" size={size} color="#00f" />
        )}
      >
        更新已完成,是否立即重启?
      </Banner>
    </View>
  );
}

其中checkUpdate方法可以用来手动触发更新检查。检查后会更新usePushy返回的updateInfo(注意checkUpdate方法本身没有返回值),有三种情况:

  1. {expired: true}:该应用原生包已过期(三种情况:1. 主动设置为过期状态,2. 主动删除,3. 从未上传),开发者应该在 pushy 的管理后台添加一个更新下载链接,并自行提示用户下载。如需在应用内执行 apk 更新,还需配置安装权限

  2. {upToDate: true}:当前已经更新到最新,无需进行更新。

  3. {update: true}:当前有新版本可以更新。info 的namedescription字段可以用于提示用户,而metaInfo字段则可以根据你的需求自定义其它属性(如是否静默更新、是否强制更新等等),具体用法可参考场景实践。另外还有几个字段,包含了补丁包的下载地址等。 pushy 会首先尝试耗费流量更少的更新方式。

当返回的updateInfoupdate字段为 true 时,即可调用downloadUpdate方法来下载更新,此时可以获取到下载的进度数据progress。下载完成后可以调用switchVersion来立即重启更新,也可以使用switchVersionLater来标记下次启动时更新。

统计数据

初始化 Pushy 客户端时可以传入自定义的 logger 函数,其中可以自己记录日志或上报统计数据,比如下面的例子使用 Google Analytics 来上报事件:

import { getAnalytics, logEvent } from "firebase/analytics";
const analytics = getAnalytics();
 
const pushyClient = new Pushy({
  appKey,
  logger: ({ type, data }) => {
    logEvent(analytics, "pushy_" + type, data);
  },
});

以上提及的所有 api 的说明文档可在这里查看。

现在,你的应用已经可以通过 pushy 服务检查版本并进行更新了。下一步,你可以开始尝试发布应用包和版本,请参阅发布热更新