343 lines
9.2 KiB
Markdown
343 lines
9.2 KiB
Markdown
# App Upgrade Plugin
|
||
|
||
一款功能强大且灵活的 Flutter 应用内更新插件，专为提供符合主流平台用户习惯的无缝升级体验而设计。插件提供了简化版和增强版两套 API，满足不同复杂度的使用需求。
|
||
|
||
## ✨ 核心特性
|
||
|
||
- **🎯 智能平台适配**：Android 支持完整的下载-安装流程，iOS 自动跳转 App Store
|
||
- **🔄 双模式更新**：非强制更新（后台下载）+ 强制更新（阻塞式对话框）
|
||
- **🛡️ 全面权限管理**：自动适配不同 Android 版本的存储、安装、通知权限
|
||
- **📱 现代化 UI**：Material Design 风格对话框，支持暗色主题和自定义样式
|
||
- **🌐 健壮网络层**：基于 Dio，支持断点续传、重试机制、证书配置
|
||
- **🔒 安全可靠**：MD5/SHA256 文件校验，防止下载文件损坏
|
||
- **🎨 高度可定制**：丰富的配置选项和回调接口
|
||
|
||
## 📦 安装
|
||
|
||
在 `pubspec.yaml` 中添加依赖：
|
||
|
||
```yaml
|
||
dependencies:
|
||
app_upgrade_plugin: ^1.0.0
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式一：简化版 API（推荐新手）
|
||
|
||
```dart
|
||
import 'package:app_upgrade_plugin/app_upgrade_plugin.dart';
|
||
|
||
// 一行代码实现完整升级流程
|
||
void checkUpdate(BuildContext context) {
|
||
AppUpgradeSimple.instance.checkUpdate(
|
||
context: context,
|
||
url: 'https://your-api.com/check-update',
|
||
params: {'channel': 'release'}, // 可选参数
|
||
showNoUpdateToast: true,
|
||
autoDownload: true,
|
||
autoInstall: false,
|
||
);
|
||
}
|
||
```
|
||
|
||
### 方式二：分离式 API（更灵活）
|
||
|
||
```dart
|
||
// 1. 检查更新（纯逻辑，不涉及UI）
|
||
final upgradeInfo = await AppUpgradeSimple.instance.checkUpdateSilent(
|
||
url: 'https://your-api.com/check-update',
|
||
params: {'platform': 'android'},
|
||
);
|
||
|
||
// 2. 根据需要显示UI
|
||
if (upgradeInfo != null && context.mounted) {
|
||
AppUpgradeSimple.instance.showUpgradeDialog(
|
||
context: context,
|
||
info: upgradeInfo,
|
||
autoDownload: true,
|
||
autoInstall: false,
|
||
);
|
||
}
|
||
```
|
||
|
||
### 方式三：增强版 API（高级用户）
|
||
|
||
```dart
|
||
final plugin = AppUpgradePluginEnhanced.instance;
|
||
|
||
// 配置插件
|
||
plugin.configure(
|
||
debugMode: true,
|
||
wifiOnly: false,
|
||
autoCheck: true,
|
||
);
|
||
|
||
// 添加下载监听
|
||
plugin.addDownloadCallback((task) {
|
||
print('下载进度: ${task.progress}%');
|
||
});
|
||
|
||
// 智能检查更新
|
||
final info = await plugin.checkUpdateSmart(
|
||
'https://your-api.com/check-update'
|
||
);
|
||
```
|
||
|
||
## 🎨 UI 展示
|
||
|
||
插件提供多种精美的 UI 组件：
|
||
|
||
- **版本更新对话框**：显示版本信息、更新内容、文件大小
|
||
- **下载进度对话框**：实时显示下载进度和状态
|
||
- **应用市场选择**：支持多应用商店选择（华为、小米、OPPO等）
|
||
- **权限申请对话框**：友好的权限说明和引导
|
||
|
||
## ⚙️ Android 配置
|
||
|
||
### 1. 权限配置
|
||
|
||
在 `android/app/src/main/AndroidManifest.xml` 中添加：
|
||
|
||
```xml
|
||
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
|
||
<!-- 网络权限 -->
|
||
<uses-permission android:name="android.permission.INTERNET" />
|
||
|
||
<!-- 安装权限（必需） -->
|
||
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
|
||
|
||
<!-- 通知权限（Android 13+，可选） -->
|
||
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
|
||
|
||
<application>
|
||
<!-- 你的其他配置 -->
|
||
|
||
<!-- FileProvider 配置（必需，用于 Android 7.0+ APK 安装） -->
|
||
<provider
|
||
android:name="androidx.core.content.FileProvider"
|
||
android:authorities="${applicationId}.fileprovider"
|
||
android:exported="false"
|
||
android:grantUriPermissions="true">
|
||
<meta-data
|
||
android:name="android.support.FILE_PROVIDER_PATHS"
|
||
android:resource="@xml/file_paths" />
|
||
</provider>
|
||
</application>
|
||
</manifest>
|
||
```
|
||
|
||
### 2. FileProvider 路径配置
|
||
|
||
创建 `android/app/src/main/res/xml/file_paths.xml`：
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<paths xmlns:android="http://schemas.android.com/apk/res/android">
|
||
<!-- 外部存储 -->
|
||
<external-path name="external_files" path="." />
|
||
<!-- 应用内部存储 -->
|
||
<files-path name="files" path="." />
|
||
<!-- 缓存目录 -->
|
||
<cache-path name="cache" path="." />
|
||
<!-- 外部缓存 -->
|
||
<external-cache-path name="external_cache" path="." />
|
||
<!-- 下载目录 -->
|
||
<external-path name="downloads" path="Download/" />
|
||
</paths>
|
||
```
|
||
|
||
### 3. Gradle 配置（可选）
|
||
|
||
在 `android/app/build.gradle` 中：
|
||
|
||
```kotlin
|
||
android {
|
||
compileSdk 34
|
||
|
||
compileOptions {
|
||
sourceCompatibility JavaVersion.VERSION_11
|
||
targetCompatibility JavaVersion.VERSION_11
|
||
isCoreLibraryDesugaringEnabled = true
|
||
}
|
||
}
|
||
|
||
dependencies {
|
||
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
|
||
}
|
||
```
|
||
|
||
## 📡 服务端 API 协议
|
||
|
||
你的版本检查接口需要返回以下格式的 JSON：
|
||
|
||
```json
|
||
{
|
||
"hasUpdate": true,
|
||
"isForceUpdate": false,
|
||
"versionCode": "101",
|
||
"versionName": "1.0.1",
|
||
"updateContent": "1. 修复了登录问题\n2. 优化了界面显示\n3. 提升了性能",
|
||
"downloadUrl": "https://your-cdn.com/app-release.apk",
|
||
"appStoreUrl": "https://apps.apple.com/app/id123456789",
|
||
"apkSize": 25165824,
|
||
"apkMd5": "d41d8cd98f00b204e9800998ecf8427e",
|
||
"appMarkets": [
|
||
{
|
||
"name": "华为应用市场",
|
||
"packageName": "com.huawei.appmarket",
|
||
"url": "appmarket://details?id=com.yourapp.package"
|
||
},
|
||
{
|
||
"name": "小米应用商店",
|
||
"packageName": "com.xiaomi.market",
|
||
"url": "mimarket://details?id=com.yourapp.package"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `hasUpdate` | boolean | ✅ | 是否有更新 |
|
||
| `isForceUpdate` | boolean | ✅ | 是否强制更新 |
|
||
| `versionCode` | string | ✅ | 版本号（数字字符串，用于版本比较） |
|
||
| `versionName` | string | ✅ | 版本名称（显示给用户） |
|
||
| `updateContent` | string | ✅ | 更新内容描述 |
|
||
| `downloadUrl` | string | Android必需 | APK下载地址 |
|
||
| `appStoreUrl` | string | iOS必需 | App Store链接 |
|
||
| `apkSize` | number | ❌ | APK文件大小（字节） |
|
||
| `apkMd5` | string | ❌ | APK文件MD5校验值 |
|
||
| `appMarkets` | array | ❌ | 应用市场列表 |
|
||
|
||
## 🔧 高级配置
|
||
|
||
### 网络配置
|
||
|
||
```dart
|
||
// 自动模式（推荐）
|
||
// Debug: 自动绕过证书验证
|
||
// Release: 严格证书验证
|
||
|
||
// 手动配置
|
||
AppUpgradePlugin().configureHttp(HttpConfig(
|
||
ignoreCertificate: false, // 是否忽略证书
|
||
enableLog: true, // 启用网络日志
|
||
connectTimeout: 30, // 连接超时（秒）
|
||
receiveTimeout: 60, // 接收超时（秒）
|
||
defaultMethod: 'GET', // 默认请求方法
|
||
headers: { // 自定义请求头
|
||
'User-Agent': 'MyApp/1.0',
|
||
},
|
||
));
|
||
```
|
||
|
||
### 权限管理
|
||
|
||
插件提供了独立的权限管理工具：
|
||
|
||
```dart
|
||
import 'package:app_upgrade_plugin/core/permission_helper.dart';
|
||
|
||
// 检查并请求存储权限
|
||
final hasStorage = await PermissionHelper.checkAndRequestStoragePermission(
|
||
context: context,
|
||
);
|
||
|
||
// 检查并请求安装权限
|
||
final hasInstall = await PermissionHelper.checkAndRequestInstallPermission(
|
||
context: context,
|
||
);
|
||
|
||
// 检查并请求通知权限
|
||
final hasNotification = await PermissionHelper.checkAndRequestNotificationPermission(
|
||
context: context,
|
||
);
|
||
```
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 安装失败，提示 "解析包时出现问题"**
|
||
|
||
A: 检查以下几点：
|
||
- APK 文件是否完整下载（检查文件大小）
|
||
- APK 签名是否正确
|
||
- 设备架构是否匹配（armeabi-v7a, arm64-v8a）
|
||
|
||
**Q: 权限申请失败**
|
||
|
||
A: 确保：
|
||
- AndroidManifest.xml 中已声明相应权限
|
||
- FileProvider 配置正确
|
||
- 在 MaterialApp 环境中调用权限申请
|
||
|
||
**Q: 下载失败或进度不更新**
|
||
|
||
A: 检查：
|
||
- 网络连接是否正常
|
||
- 下载URL是否可访问
|
||
- 服务器是否支持断点续传
|
||
|
||
**Q: iOS 不跳转 App Store**
|
||
|
||
A: 确认：
|
||
- `appStoreUrl` 字段格式正确
|
||
- URL 为有效的 App Store 链接
|
||
|
||
### 调试技巧
|
||
|
||
开启调试模式以获取详细日志：
|
||
|
||
```dart
|
||
// 简化版
|
||
AppUpgradeSimple.instance.init(debugMode: true);
|
||
|
||
// 增强版
|
||
AppUpgradePluginEnhanced.instance.configure(debugMode: true);
|
||
```
|
||
|
||
## 📚 API 文档
|
||
|
||
### AppUpgradeSimple
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `checkUpdate()` | 检查更新并显示UI |
|
||
| `checkUpdateSilent()` | 静默检查更新 |
|
||
| `showUpgradeDialog()` | 显示升级对话框 |
|
||
|
||
### AppUpgradePluginEnhanced
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `configure()` | 配置插件 |
|
||
| `checkUpdateSmart()` | 智能检查更新 |
|
||
| `downloadApkSmart()` | 智能下载APK |
|
||
| `installApkSmart()` | 智能安装APK |
|
||
| `addDownloadCallback()` | 添加下载监听 |
|
||
|
||
### PermissionHelper
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `checkAndRequestStoragePermission()` | 存储权限 |
|
||
| `checkAndRequestInstallPermission()` | 安装权限 |
|
||
| `checkAndRequestNotificationPermission()` | 通知权限 |
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [Flutter 官网](https://flutter.dev)
|
||
- [Android 应用安装权限文档](https://developer.android.com/reference/android/Manifest.permission#REQUEST_INSTALL_PACKAGES)
|
||
- [FileProvider 使用指南](https://developer.android.com/reference/androidx/core/content/FileProvider) |