326 lines
7.0 KiB
Markdown
326 lines
7.0 KiB
Markdown
# App Upgrade Plugin - 完整使用指南
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 基础用法（一行代码）
|
||
```dart
|
||
import 'package:app_upgrade_plugin/app_upgrade_plugin.dart';
|
||
|
||
// 最简单的使用方式
|
||
await AppUpgradeSimple.instance.checkUpdate(
|
||
context: context,
|
||
url: 'https://api.example.com/check-update',
|
||
);
|
||
```
|
||
|
||
## ⚙️ 配置选项
|
||
|
||
### 预设配置
|
||
```dart
|
||
// 开发模式（详细日志+提示信息）
|
||
AppUpgradeSimple.instance.configure(UpgradeConfig.development);
|
||
|
||
// 生产模式（静默检查+性能优化）
|
||
AppUpgradeSimple.instance.configure(UpgradeConfig.production);
|
||
```
|
||
|
||
### 自定义配置
|
||
```dart
|
||
AppUpgradeSimple.instance.configure(UpgradeConfig(
|
||
showNoUpdateToast: true, // 显示无更新提示
|
||
autoInstall: false, // 自动安装
|
||
installTimeout: 45, // 安装检测超时（秒）
|
||
enableDebugLog: true, // 启用调试日志
|
||
customToast: (message) { // 自定义Toast
|
||
ScaffoldMessenger.of(context).showSnackBar(
|
||
SnackBar(content: Text(message)),
|
||
);
|
||
},
|
||
));
|
||
```
|
||
|
||
## 🎯 使用场景
|
||
|
||
### 1. 应用启动时检查更新
|
||
```dart
|
||
class MyApp extends StatelessWidget {
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return MaterialApp(
|
||
home: Builder(
|
||
builder: (context) {
|
||
// 应用启动后检查更新
|
||
WidgetsBinding.instance.addPostFrameCallback((_) {
|
||
AppUpgradeSimple.instance.checkUpdate(
|
||
context: context,
|
||
url: 'https://api.example.com/check-update',
|
||
);
|
||
});
|
||
return MyHomePage();
|
||
},
|
||
),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 定期检查更新
|
||
```dart
|
||
class MyHomePage extends StatefulWidget {
|
||
@override
|
||
State<MyHomePage> createState() => _MyHomePageState();
|
||
}
|
||
|
||
class _MyHomePageState extends State<MyHomePage> {
|
||
Timer? _updateTimer;
|
||
|
||
@override
|
||
void initState() {
|
||
super.initState();
|
||
// 每24小时检查一次更新
|
||
_updateTimer = Timer.periodic(const Duration(hours: 24), (_) {
|
||
AppUpgradeSimple.instance.checkUpdateSilent(
|
||
url: 'https://api.example.com/check-update',
|
||
);
|
||
});
|
||
}
|
||
|
||
@override
|
||
void dispose() {
|
||
_updateTimer?.cancel();
|
||
super.dispose();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 手动检查更新
|
||
```dart
|
||
ElevatedButton(
|
||
onPressed: () async {
|
||
await AppUpgradeSimple.instance.checkUpdate(
|
||
context: context,
|
||
url: 'https://api.example.com/check-update',
|
||
params: {
|
||
'userId': currentUserId,
|
||
'channel': releaseChannel,
|
||
},
|
||
onComplete: () {
|
||
print('更新检查完成');
|
||
},
|
||
);
|
||
},
|
||
child: const Text('检查更新'),
|
||
)
|
||
```
|
||
|
||
## 🔧 高级功能
|
||
|
||
### 预下载APK
|
||
```dart
|
||
// 后台预下载，不显示UI
|
||
final filePath = await AppUpgradeSimple.instance.preDownloadApk(
|
||
url: 'https://example.com/app.apk',
|
||
onProgress: (progress) {
|
||
print('下载进度: ${progress.percentage}%');
|
||
},
|
||
);
|
||
```
|
||
|
||
### 查找已下载的APK
|
||
```dart
|
||
final existingApk = await AppUpgradeSimple.instance.findDownloadedApk('1.2.0');
|
||
if (existingApk != null) {
|
||
print('找到已下载的APK: $existingApk');
|
||
}
|
||
```
|
||
|
||
### 网络状态检查
|
||
```dart
|
||
final hasNetwork = await AppUpgradeSimple.instance.checkNetworkStatus();
|
||
if (!hasNetwork) {
|
||
showDialog(
|
||
context: context,
|
||
builder: (context) => AlertDialog(
|
||
title: const Text('网络错误'),
|
||
content: const Text('请检查网络连接'),
|
||
actions: [
|
||
TextButton(
|
||
onPressed: () => Navigator.of(context).pop(),
|
||
child: const Text('确定'),
|
||
),
|
||
],
|
||
),
|
||
);
|
||
}
|
||
```
|
||
|
||
### 清理下载缓存
|
||
```dart
|
||
// 清理所有下载的APK文件
|
||
await AppUpgradeSimple.instance.clearDownloadCache();
|
||
```
|
||
|
||
## 🎨 UI定制
|
||
|
||
### 自定义Toast
|
||
```dart
|
||
AppUpgradeSimple.instance.configure(UpgradeConfig(
|
||
customToast: (message) {
|
||
// 使用SnackBar代替Toast
|
||
ScaffoldMessenger.of(context).showSnackBar(
|
||
SnackBar(
|
||
content: Text(message),
|
||
backgroundColor: Colors.deepPurple,
|
||
behavior: SnackBarBehavior.floating,
|
||
),
|
||
);
|
||
},
|
||
));
|
||
```
|
||
|
||
### 富文本更新内容
|
||
服务器返回的更新内容支持简单的富文本格式：
|
||
```
|
||
**新功能**
|
||
- 添加了[暗黑模式]支持
|
||
- 优化了`网络请求`性能
|
||
- __修复了已知问题__
|
||
|
||
**重要更新**
|
||
请及时更新到最新版本以获得更好的体验！
|
||
```
|
||
|
||
## 📱 平台支持
|
||
|
||
### Android
|
||
- ✅ APK下载和安装
|
||
- ✅ 权限自动处理
|
||
- ✅ 多应用商店支持
|
||
- ✅ 安装状态智能检测
|
||
- ✅ 断点续传
|
||
- ✅ 文件校验
|
||
|
||
### iOS
|
||
- ✅ App Store跳转
|
||
- ✅ 企业证书分发
|
||
- ✅ TestFlight支持
|
||
|
||
## 🔍 调试和测试
|
||
|
||
### 启用调试日志
|
||
```dart
|
||
AppUpgradeSimple.instance.configure(UpgradeConfig.development);
|
||
```
|
||
|
||
### 查看日志输出
|
||
```
|
||
🔍 检查更新结果: UpgradeInfo(...)
|
||
⚡ 应用回到前台，立即检查安装状态
|
||
✅ 检测结果: 安装成功
|
||
❌ 检测结果: 安装未完成
|
||
```
|
||
|
||
### 测试不同场景
|
||
插件内置了测试按钮，可以模拟各种安装场景：
|
||
- 模拟安装取消
|
||
- 模拟权限拒绝
|
||
- 模拟安装超时
|
||
|
||
## 🛡️ 错误处理
|
||
|
||
插件提供了完善的错误处理机制：
|
||
|
||
### 网络错误
|
||
- 连接超时
|
||
- DNS解析失败
|
||
- 服务器错误
|
||
- 证书验证失败
|
||
|
||
### 安装错误
|
||
- 权限被拒绝
|
||
- APK文件损坏
|
||
- 存储空间不足
|
||
- 系统版本不兼容
|
||
|
||
### 自动重试
|
||
- 智能检测安装状态
|
||
- 多种重试方式
|
||
- 用户友好的错误提示
|
||
|
||
## 📊 最佳实践
|
||
|
||
### 1. 应用启动检查
|
||
```dart
|
||
// 推荐：应用启动时静默检查
|
||
WidgetsBinding.instance.addPostFrameCallback((_) {
|
||
AppUpgradeSimple.instance.checkUpdateSilent(
|
||
url: 'https://api.example.com/check-update',
|
||
).then((info) {
|
||
if (info != null && info.hasUpdate) {
|
||
// 发现更新，显示提示
|
||
showUpdateNotification(context, info);
|
||
}
|
||
});
|
||
});
|
||
```
|
||
|
||
### 2. 定期检查
|
||
```dart
|
||
// 推荐：每日检查一次
|
||
Timer.periodic(const Duration(days: 1), (_) {
|
||
AppUpgradeSimple.instance.checkUpdateSilent(
|
||
url: 'https://api.example.com/check-update',
|
||
);
|
||
});
|
||
```
|
||
|
||
### 3. 用户手动检查
|
||
```dart
|
||
// 推荐：提供手动检查按钮
|
||
ElevatedButton(
|
||
onPressed: () {
|
||
AppUpgradeSimple.instance.checkUpdate(
|
||
context: context,
|
||
url: 'https://api.example.com/check-update',
|
||
);
|
||
},
|
||
child: const Text('检查更新'),
|
||
)
|
||
```
|
||
|
||
## 🎯 完整示例
|
||
|
||
查看 `example/lib/main_enhanced.dart` 获取完整的使用示例，包含所有功能的演示。
|
||
|
||
## 📝 API文档
|
||
|
||
### 主要方法
|
||
|
||
#### `checkUpdate()`
|
||
检查并处理应用更新的主要方法。
|
||
|
||
#### `checkUpdateSilent()`
|
||
静默检查更新，不显示UI。
|
||
|
||
#### `preDownloadApk()`
|
||
后台预下载APK文件。
|
||
|
||
#### `clearDownloadCache()`
|
||
清理下载缓存。
|
||
|
||
#### `checkNetworkStatus()`
|
||
检查网络连接状态。
|
||
|
||
### 配置类
|
||
|
||
#### `UpgradeConfig`
|
||
升级配置类，控制插件的行为。
|
||
|
||
#### 预设配置
|
||
- `UpgradeConfig.development` - 开发模式（详细日志+提示信息）
|
||
- `UpgradeConfig.production` - 生产模式（静默检查+性能优化）
|
||
|
||
---
|
||
|
||
这个插件现在提供了完整的应用升级解决方案，支持各种使用场景和自定义需求！
|