Flutter应用版本升级插件custom_upgrader的使用

Flutter应用版本升级插件custom_upgrader的使用

Flutter包用于在应用商店有新版本时提示用户升级。

UI

UI有两种形式：弹窗警报或卡片。UpgradeAlert类用于显示弹出警报提示，UpgradeCard类用于显示内联的Material设计卡片。

本地化

upgrader包中的文本在许多语言中进行了本地化，并支持自定义。

发布说明

默认情况下，当有新版本可用时会显示发布说明。在Android上，如果可用，将从Google Play的WHAT’S NEW部分获取发布说明，否则将使用主应用描述。在iOS上，将从App Store的What’s New部分获取发布说明。对于appcast，将从描述字段获取发布说明。

警报示例

只需将你的主体小部件包装在UpgradeAlert小部件中，它将处理其余部分。

import 'package:flutter/material.dart';
import 'package:custom_upgrader/custom_upgrader.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  MyApp({
    Key key,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Upgrader Example',
      home: Scaffold(
          appBar: AppBar(
            title: Text('Upgrader Example'),
          ),
          body: UpgradeAlert(
            child: Center(child: Text('Checking...')),
          )
      ),
    );
  }
}

截图警报

Cupertino警报示例

你也可以通过使用dialogStyle参数来显示Cupertino风格的对话框。

body: UpgradeAlert(
  dialogStyle: UpgradeDialogStyle.cupertino,
  child: Center(child: Text('Checking...')),
)

截图Cupertino警报

卡片示例

只需在构建方法中返回一个UpgradeCard小部件，当检测到更新时将显示一个Material设计卡片。当未检测到更新时，该小部件的宽度和高度为0.0。

return Container(
  margin: EdgeInsets.fromLTRB(12.0, 0.0, 12.0, 0.0),
  child: UpgradeCard(),
);

截图卡片

自定义

UpgradeAlert小部件可以通过在其构造函数中设置参数进行自定义。

• appcastConfig: 应用程序配置，默认为null
• client: 可替换用于模拟测试的HTTP客户端，默认为null
• durationUntilAlertAgain: 用户再次被提醒的持续时间，默认为3天
• debugDisplayAlways: 强制显示升级，默认为false
• debugDisplayOnce: 显示升级至少一次，默认为false
• debugLogging: 显示日志语句，默认为false
• messages: 用于显示在upgrader中的可选本地化消息
• onIgnore: 忽略按钮被点击时调用，默认为null
• onLater: 后面按钮被点击时调用，默认为null
• onUpdate: 更新按钮被点击时调用，默认为null
• shouldPopScope: 返回按钮被点击时调用，默认为null
• showIgnore: 隐藏或显示忽略按钮，默认为true
• showLater: 隐藏或显示后面按钮，默认为true
• showReleaseNotes: 隐藏或显示发布说明，默认为true
• canDismissDialog: 是否可以点击对话框外部来关闭对话框，默认为false（不适用于UpgradeCard）
• countryCode: 将覆盖系统区域设置的国家代码，默认为null（仅限iOS）
• minAppVersion: 此应用程序支持的最小应用程序版本。此应用程序的早期版本将被强制更新到当前版本。默认为null。
• dialogStyle: 升级对话框样式，可以是material或cupertino，默认为material，仅适用于UpgradeAlert，在Android和iOS上都适用。

安卓返回键

当使用UpgradeAlert小部件时，默认情况下安卓返回键不会关闭警报对话框。要允许返回键关闭对话框，请使用shouldPopScope并返回true，如下所示：

UpgradeAlert(
  shouldPopScope: () => true,
);

iOS国家代码

当你的应用不在iOS的US应用商店中时，必须使用上述提到的countryCode参数。upgrader包不知道应该使用哪个国家的应用商店，因为Apple没有提供这方面的信息。它假定应用在US应用商店中。

限制

这些小部件在Android和iOS上都可以工作。在Android上，Google Play商店将提供最新应用版本。在iOS上，App Store将提供最新应用版本。在这种情况下，小部件将在适当的时间显示提示。

在Android上，版本号通常无法从Google Play商店获取，例如Google Maps应用。在这种情况下，版本号被列为Varies with device。这不是有效的版本号，不能用于upgrader。在这种情况下，upgrader小部件将不会显示。

有一个appcast可以用来远程配置最新的应用版本。详情请参见appcast部分。

Appcast

在此Flutter包中使用的Appcast类由Upgrader小部件用于从appcast下载应用程序详细信息，基于Andy Matuschak的Sparkle框架。你可以阅读Sparkle文档在这里：https://sparkle-project.org/documentation/publishing/

appcast是一个RSS源，其中包含一个具有多个描述每个应用版本项的通道。appcast将描述每个应用版本，并提供最新的应用版本给Upgrader，以指示何时应推荐升级。

appcast必须托管在一个可以从应用程序访问的服务器上。appcast XML文件可以在发布过程中自动生成，或者在应用商店有可用版本后手动更新。

Appcast类可以单独使用或作为Upgrader的一部分使用。

Appcast示例

这是Android的Appcast示例。

@override
Widget build(BuildContext context) {
  // 在Android上，设置Appcast。
  // 在iOS上，默认行为将是使用App Store版本。
  final appcastURL =
      'https://raw.githubusercontent.com/larryaasen/upgrader/master/test/testappcast.xml';
  final cfg = AppcastConfiguration(url: appcastURL, supportedOS: ['android']);

  return MaterialApp(
    title: 'Upgrader Example',
    home: Scaffold(
        appBar: AppBar(
          title: Text('Upgrader Example'),
        ),
        body: UpgradeAlert(
          appcastConfig: cfg,
          child: Center(child: Text('Checking...')),
        )),
  );
}

Appcast样本文件

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
    <channel>
        <title>Debt Now App - Appcast</title>
        <item>
            <title>Version 1.15.0</title>
            <description>Minor updates and improvements.</description>
            <pubDate>Sun, 30 Dec 2018 12:00:00 +0000</pubDate>
            <enclosure url="https://play.google.com/store/apps/details?id=com.moonwink.treasury" sparkle:version="1.15.0" sparkle:os="android" />
        </item>
    </channel>
</rss>

Appcast类

final appcast = Appcast();
final items = await appcast.parseAppcastItemsFromUri('https://raw.githubusercontent.com/larryaasen/upgrader/master/test/testappcast.xml');
final bestItem = appcast.bestItem();

自定义显示

upgrader中显示的字符串可以通过扩展UpgraderMessages类来提供自定义值。

例如，要将忽略按钮替换为自定义值，首先创建一个扩展UpgraderMessages的新类，并覆盖buttonTitleIgnore函数。接下来，在调用UpgradeAlert（或UpgradeCard）时，添加messages参数并传入你的扩展类的一个实例。这是一个示例：

class MyUpgraderMessages extends UpgraderMessages {
  @override
  String get buttonTitleIgnore => '我的忽略';
}

UpgradeAlert(messages: MyUpgraderMessages());

语言本地化

upgrader中显示的字符串已经在各种语言中本地化。未来会有更多语言支持，通过次要更新添加。

支持的语言包括：

• 英语 (‘en’)
• 阿拉伯语 (‘ar’)
• 孟加拉语 (‘bn’)
• 菲律宾语 (‘fil’)
• 法语 (‘fr’)
• 德语 (‘de’)
• 匈牙利语 (‘hu’)
• 印度尼西亚语 (‘id’)
• 意大利语 (‘it’)
• 哈萨克语 (‘kk’)
• 韩语 (‘ko’)
• 波斯语 (‘fa’)
• 波兰语 (‘pl’)
• 葡萄牙语 (‘pt’)
• 俄语 (‘ru’)
• 西班牙语 (‘es’)
• 泰米尔语 (‘ta’)
• 土耳其语 (‘tr’)
• 乌克兰语 (‘uk’)
• 越南语 (‘vi’)

upgrader包可以通过在代码中扩展UpgraderMessages类来提供额外的语言。

例如，要添加西班牙语（已提供），首先创建一个扩展UpgraderMessages的新类，并覆盖message函数。接下来，为每个消息添加一个字符串。最后，在调用UpgradeAlert（或UpgradeCard）时，添加messages参数并传入你的扩展类的一个实例。这是一个示例：

class MySpanishMessages extends UpgraderMessages {
  /// 覆盖message函数以提供自定义语言本地化。
  @override
  String message(UpgraderMessage messageKey) {
    if (languageCode == 'es') {
      switch (messageKey) {
        case UpgraderMessage.body:
          return 'es A new version of {{appName}} is available!';
        case UpgraderMessage.buttonTitleIgnore:
          return 'es Ignore';
        case UpgraderMessage.buttonTitleLater:
          return 'es Later';
        case UpgraderMessage.buttonTitleUpdate:
          return 'es Update Now';
        case UpgraderMessage.prompt:
          return 'es Want to update?';
        case UpgraderMessage.title:
          return 'es Update App?';
      }
    }
    // 未提供以上消息仍可使用默认值。
    return super.message(messageKey);
  }
}

UpgradeAlert(messages: MySpanishMessages());

你甚至可以强制升级包使用特定语言，而不是设备上的系统语言。只需传递语言代码到UpgraderMessages实例中即可显示警告或卡片。这是一个示例：

UpgradeAlert(messages: UpgraderMessages(code: 'es'));

iTunes搜索API

在此Flutter包中有一个类用于通过iTunes搜索API下载应用详细信息。ITunesSearchAPI类可以独立使用以查询iTunes获取应用详细信息。

iTunes搜索API示例

final iTunes = ITunesSearchAPI();
final resultsFuture = iTunes.lookupByBundleId('com.google.Maps');
resultsFuture.then((results) {
    print('results: $results');
});

结果

命令行应用 - Android

有一个命令行应用用于显示来自Google Play Store的结果。代码位于bin/playstore_lookup.dart，可以从命令行运行，如下所示：

$ dart playstore_lookup.dart id=com.google.android.apps.mapslite

结果：

playstore_lookup releaseNotes: • Support plus.codes URLs• Bug fixes
playstore_lookup version: 152.0.0
...

命令行应用 - iOS

有一个命令行应用用于显示来自iTunes搜索的结果。代码位于bin/itunes_lookup.dart，可以从命令行运行，如下所示：

$ dart itunes_lookup.dart bundleid=com.google.Maps

结果：

upgrader: download: https://itunes.apple.com/lookup?bundleId=com.google.Maps
upgrader: response statusCode: 200
itunes_lookup bundleId: com.google.Maps
itunes_lookup releaseNotes: Thanks for using Google Maps!
itunes_lookup trackViewUrl: https://apps.apple.com/us/app/google-maps-transit-food/id585027354?uo=4
itunes_lookup version: 5.58
itunes_lookup all results:
{resultCount: 1, results:
...