更新记录

1.0.1(2026-11-17)

fix bug

1.0.0(2026-11-17)

  • iOS 请求 https://itunes.apple.com/lookup?id=,把苹果返回的 JSON 放在 lookup
  • Android 读取 Play 应用内更新状态,返回 versionCode、可用性、安装进度
  • 不比较版本。未传入的 appleId、country、更新方式不会被补成默认值

平台兼容性

uni-app(4.27)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- √ - - - - 5.0 13 -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.27)

Chrome Safari Android Android插件版本 iOS iOS插件版本 鸿蒙 微信小程序
× × 5.0 1.0.1 13 1.0.1 × ×

fz-store-update

1.0.0

读取商店里的更新信息,把结构化 JSON 交给宿主。插件不比较版本,也不在缺参时填默认值;有没有更新、弹不弹窗,全部由宿主自己决定。

平台 实际做什么
iOS 请求 iTunes Lookup:https://itunes.apple.com/lookup?id={appleId}
Android 读取本机 Google Play 应用内更新(AppUpdateManager)状态
H5 / 非 App 直接 reject,错误码 94608

两端路径完全独立:在 Android 上调用不会请求 iTunes;在 iOS 上调用不会走 Play。Android 不读 appleId / country。

拷到 uni_modules 后必须打自定义基座或正式包。改 .kt / .swift / .uts 要重打。

环境

项 要求
HBuilderX 4.27 及以上
工程 uni-app Vue3。uni-app x 的 App 也可
Android minSdk 21,依赖 com.google.android.play:app-update:2.1.0(插件已声明)
iOS 13.0 及以上

不额外申请权限。iOS 使用系统网络访问 itunes.apple.com。Android 使用 Play 应用内更新库,结果只有从 Google Play 安装 的包才有意义;侧载、HBuilderX 直装、国内应用商店包,availability 经常是 not_available,这是 Play 的返回,不是插件填的。

隐私说明

  • 无广告、无统计 SDK、无自有服务器。
  • iOS:仅向 itunes.apple.com 查询宿主传入的 App Store 数字 ID,把苹果返回的 JSON 原样交给宿主。
  • Android:仅向本机 Google Play 查询应用内更新状态,不上传业务数据。
  • 插件不做版本比较,也不上传 localVersion / 包名到第三方。

接入

  1. 复制 uni_modules/fz-store-update 到工程。
  2. 制作自定义调试基座(或打正式包)。
  3. 仅在 App 端调用(建议 #ifdef APP-PLUS)。
import { checkStoreUpdate, startStoreUpdate, completeStoreUpdate } from '@/uni_modules/fz-store-update'

// —— iOS:appleId 必填。country 不想限制商店区域就不要传 ——
const iosInfo = await checkStoreUpdate({
  appleId: '6787389201',
  country: 'cn' // 可选。不传则 URL 不带 country,不会默认成 us
})
const item = iosInfo.lookup && iosInfo.lookup.results && iosInfo.lookup.results[0]
const storeVersion = item && item.version
const storeUrl = item && item.trackViewUrl
// 有更新时用 plus.runtime.openURL(storeUrl) 打开 App Store
// iOS 没有应用内更新流程,startStoreUpdate / completeStoreUpdate 会返回 94606

// —— Android:不读 appleId,可传 null ——
const androidInfo = await checkStoreUpdate(null)
if (androidInfo.availability === 'available' && androidInfo.immediateAllowed) {
  const flow = await startStoreUpdate({ type: 'immediate' })
  // flow.result:ok | canceled | failed
}

// 灵活更新下载完成后,由宿主决定是否安装
if (androidInfo.installStatusName === 'downloaded') {
  await completeStoreUpdate()
}

示例页:pages/store-update/store-update(测试工程内)。输入框默认为空,iOS 必须自己填 App Store 数字 ID。

API

checkStoreUpdate(options?: StoreCheckOptions | null): Promise<StoreCheckResult>
startStoreUpdate(options: StoreUpdateOptions): Promise<StoreFlowResult>
completeStoreUpdate(): Promise<StoreFlowResult>

checkStoreUpdate

参数 平台 说明
appleId iOS 必填 App Store 数字 ID,仅数字,最长 18 位。Android 忽略
country 可选 两位字母,如 cn / us。不传或 null 时 lookup 不带 country,不会改成 us 或本机地区。非法值直接 94601

iOS 实际请求:

https://itunes.apple.com/lookup?id={appleId}
https://itunes.apple.com/lookup?id={appleId}&country={country}

请求超时约 15 秒。失败 reject,错误码 94602(网络失败、超时、非 JSON、HTTP 非 200 等)。

startStoreUpdate / completeStoreUpdate

仅 Android。

参数 说明
type 必填,只能是 immediate 或 flexible。不传、传空、传别的字都是 94601,不会自动改成其中一种
  • immediate:阻塞式更新界面。
  • flexible:可后台下载;下载完成后宿主再调 completeStoreUpdate() 提交安装。
  • iOS 调用这两个方法固定 94606。打开商店请用 lookup 里的 trackViewUrl。
  • 必须在有前台 Activity 时调用,否则 94604。
  • 用户取消不算 94605,看返回里的 result === 'canceled'。

返回字段

没有的字段是 null,不是空串、0 或 false。插件不裁字段、不补默认值。

公共字段(checkStoreUpdate)

字段 说明
platform ios / android
source itunes / play
appleId 本次实际请求的 ID。Android 为 null
country 本次实际带上的国家码。没传是 null
lookupUrl 本次实际请求的 lookup 地址。Android 为 null
packageName 本机包名 / Bundle ID。读不到是 null
localVersion 本机 versionName / CFBundleShortVersionString。读不到是 null
localBuild 本机 versionCode / CFBundleVersion。读不到是 null
lookup iTunes 响应原文。Android 为 null

localVersion / localBuild 只是本机正在跑的版本。插件不会用它们和商店版本做比较。

iOS:lookup

苹果响应原文,字段不裁、不补。常见在 lookup.results[0]:

字段 说明
version 商店 versionName
releaseNotes 更新说明
currentVersionReleaseDate 当前版本上架时间
trackViewUrl App Store 页面地址,可用来跳转
bundleId Bundle ID

resultCount 为 0 时 results 是空数组,插件仍算成功(例如 ID 错了或该国区没有这个 App)。是否提示用户由宿主判断。

Android:Play 字段

字段 说明
updateAvailability Play 原值。0 unknown,1 not_available,2 available,3 in_progress
availability unknown / not_available / available / in_progress。认不出是 null
availableVersionCode Play 给出的版本号整数。没有 versionName。没有更新时这个数也可能有值,请先看 availability
stalenessDays 已发布天数。Play 没给是 null
updatePriority 0 到 5,商店后台填的优先级
installStatus / installStatusName 灵活更新下载状态。认不出的状态名是 null
immediateAllowed / flexibleAllowed Play 是否允许该更新方式
bytesDownloaded / totalBytesToDownload 已下载和总字节

installStatusName 常见值:unknown / pending / downloading / installing / installed / failed / canceled / requires_ui / downloaded。

start / complete 返回

字段 说明
platform android
type 调用时传入的 immediate / flexible(complete 可能没有)
resultCode Activity 结果码。ok 为 -1,取消为 0,失败为 1
result ok / canceled / failed。认不出是 null
completed completeStoreUpdate 成功时为 true

错误码

失败 reject,errSubject 为 fz-store-update。可用 err.errCode / err.errMsg(或 code / message)读取。

码 含义
94601 appleId、country 或更新方式不合法,或必填没传
94602 iTunes 请求失败、超时,或返回的不是 JSON
94603 Play 更新信息读取失败或超时(约 15 秒)
94604 没有前台页面
94605 更新界面没拉起,或完成安装失败。用户取消不算这个码,看 result
94606 iOS 没有应用内更新流程
94608 非 App 端

平台对照

iOS Android
检查更新 iTunes Lookup 网络请求 本机 Play appUpdateInfo
是否需要商店数字 ID 要,appleId 必填 不要
商店 versionName lookup.results[0].version 没有,只有 availableVersionCode
应用内更新 UI 无,用 trackViewUrl 跳转 startStoreUpdate
侧载 / 自定义基座 Lookup 只要网络通就能查 通常 not_available 或超时
超时表现 94602(访问 itunes.apple.com) 94603(Play 回调未返回)

测试建议

自定义基座 + 真机。

iOS

  1. 填真实 App Store 数字 ID,建议同时填 country(如 cn)。
  2. 点检查,应拿到 source: 'itunes' 和 lookup。
  3. 同机 Safari 打开 https://itunes.apple.com/lookup?id=你的ID&country=cn:若浏览器也慢或打不开,属于网络/地区问题,不是插件逻辑错误。
  4. startStoreUpdate 应得到 94606。

Android

  1. 输入框可空,直接检查。应拿到 source: 'play'。
  2. 要从 Google Play 安装(或 Internal App Sharing / 正式轨)才容易看到 availability === 'available'。
  3. HBuilderX 直接安装、侧载、无 Play 服务的设备,常见 not_available 或 94603 超时。
  4. 灵活更新:先 startStoreUpdate({ type: 'flexible' }),待 installStatusName === 'downloaded' 再 completeStoreUpdate()。

FAQ

uts 插件编译失败 / 调用无效果
没打进当前基座。改过插件原生代码后,重新制作自定义基座。

为什么我在安卓上测「iOS 更新」会超时?
安卓不会请求 iTunes。安卓超时是 Play 检查超时(94603),和 iOS Lookup 无关。要测 iTunes 必须用 iOS 真机。

iOS 报 94602 / timed out
访问 itunes.apple.com 失败或超过约 15 秒。先用同机浏览器打开 lookup URL 验证网络;可试加 country: 'cn'。插件不会把空 country 改成默认国家。

Android 一直 not_available
包不是从 Google Play 装的,或商店没有更高 versionCode。侧载和调试基座很常见。这是 Play 返回,不是插件写死的。

Android 报 94603 timed out
Play 服务不可用、无前台、或 appUpdateInfo 一直不回调。插件约 15 秒后主动结束。

iOS 如何打开更新页?
用 checkStoreUpdate 结果里的 lookup.results[0].trackViewUrl,宿主自行 plus.runtime.openURL。不要调 startStoreUpdate。

插件会不会自动弹更新窗、强制升级?
不会。不比较版本,不弹窗,不跳转。是否提示、是否强制、文案怎么写,全部由宿主处理。

传错 appleId 会怎样?
只要是合法数字 ID,请求成功且 resultCount === 0 时插件仍 resolve,results 为空数组。ID 格式非法才是 94601。

能不能在 H5 调试?
不能。H5 固定 94608。请用 App 真机自定义基座。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

不额外申请权限。iOS 使用系统网络访问 itunes.apple.com。Android 使用 Play 应用内更新库。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

iOS 只向 itunes.apple.com 查询宿主传入的 App Store ID,并把返回的 JSON 交给宿主。Android 只向本机 Google Play 查询应用内更新状态。插件无自有服务器,不比较版本,不上传数据。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无广告。无统计 SDK。

暂无用户评论。