小程序管理

小程序管理主要介绍操作小程序的API，包括：打开小程序，关闭小程序，删除小程序等

1. 打开小程序

不同的场景，所使用的打开小程序的api也不同。所以，我们提供了多种不同的打开小程序的api。

1. 打开线上小程序，这里一般只需要小程序id和服务器地址即可，该api只能打开正式版和审核版的小程序。
2. 二维码打开小程序，这个场景是扫描小程序平台上的二维码，得到二维码里的内容，然后使用该内容打开小程序。正式版、体验版、审核版、开发版、预览版本的小程序二维码都可以使用该Api打开。

1.1 普通打开小程序

打开小程序时，会先判断本地是否有缓存的小程序，如果没有，则会自动从远程服务器上下载小程序，然后打开；如果有缓存的小程序，则会先打开本地小程序，然后再校验服务器端是否有新版本。

如果有新版本，则下载新版小程序，下次打开时，就会使用新版小程序；如果没有新版本，则什么也不做。

/// 启动小程序
/// [request] 启动小程序的request
Future<Map> startApplet(RemoteAppletRequest request)

RemoteAppletRequest

属性名	类型	描述
appletId	String	小程序id，必填
apiServer	String	小程序所属服务器地址，必填
startParams	Map<String, String>?	小程序启动参数，仅支持path 和 query
sequence	int?	小程序索引， 非必填
offlineMiniprogramZipPath	String?	离线小程序压缩包路径，可传入一个本地小程序包路径，加快首次启动速度， 非必填
offlineFrameworkZipPath	String?	离线基础库压缩包路径，可传入一个基础库路径，加快首次启动速度， 非必填
animated	bool	是否使用动画，非必填，默认值为true。仅iOS支持
isSingleProcess	bool	是否以单进程模式运行，默认值为false。仅Android支持
isSingTask	bool	是否以单任务栈模式运行，默认值为false。仅Android支持
reLaunchMode	FCRelaunchMode	执行reLaunch的模式。PARAMS_EXIST, ONLY_PARAMS_DIFF，ALWAYS，NEVER

注意：如果要首次离线启动，则offlineMiniprogramZipPath 和 offlineFrameworkZipPath必须都传递。

示例代码：

RemoteAppletRequest request = new RemoteAppletRequest(apiServer: 'https://api.finclip.com', appletId: appId);
request.startParams = {
  'path':'/pages/index/index',
  'query':'key1=value2&key2=value2'
};
Mop.instance.startApplet(request);

1.2 二维码打开小程序

这种情况流程一般会复杂一些，需要先扫描FinClip小程序开放平台上的二维码，得到二维码里的内容，然后使用二维码内容调用该接口打开小程序。

/// 二维码信息启动小程序
/// [qrcode] 二维码内的字符串内容
/// [isSingleProcess] 是否以单进程模式运行，仅Android支持该参数，默认为false
/// [isSingTask] 是否以单任务栈模式运行，仅Android支持该参数，默认为false
Future qrcodeOpenApplet(String qrcode, {bool isSingleProcess = false, bool isSingTask = false})

注意：打开体验版二维码时，需在初始化sdk时添加对应的体验成员userId。

示例代码：

String qrCode = '二维码内容';
Mop.instance.qrcodeOpenApplet(qrCode);

2. 关闭小程序

关闭小程序 等价于 点击右上角胶囊里的小程序，此时小程序是退至后台，小程序并未销毁。

2.1 关闭指定小程序

/**
关闭指定的小程序
@param appletId 小程序id
@param animated 是否显示动画，仅iOS生效
*/
Future<void> closeApplet(String appletId, bool animated) 

2.2 关闭所有小程序

有些场景下，可能存在A小程序打开B小程序，B小程序打开C小程序的情况，这时想要关闭打开的所有小程序，可以使用该方法。

/// 关闭打开的所有小程序
Future closeAllApplets()

3. 结束小程序

小程序被关闭后，并没有真的结束，而是在后台挂起。等下次打开小程序时，会立即将小程序切换至前台运行。 所以，如果我们希望小程序关闭后，真的被结束掉，可以根据实际情况使用以下API来结束指定小程序或所有小程序。

3.1 结束指定小程序

小程序关闭后，调用该api可删除缓存，即可销毁该小程序。

/// 结束小程序 小程序会从内存中清除
Future<void> finishRunningApplet(String appletId, bool animated)

3.2 结束所有小程序

/// clear mini programs cache
/// 结束所有小程序
Future clearApplets()

示例代码：

Mop.instance.clearApplets();

4. 删除小程序

由于小程序的运行，会将小程序包和小程序信息缓存在本地，以后打开时会优先使用缓存，所以打开时速度也就会很快。 所以，如果想要将小程序的所有信息都删除，那么可以使用以下api删除某个小程序或者删除所有小程序。

4.1 删除指定小程序

/// 清除指定的小程序本体缓存
Future removeUsedApplet(String appId)

4.2 删除所有小程序

/// 清除所有小程序缓存
Future removeAllUsedApplets()

3. 批量下载小程序

App可以在空闲的时间进行批量预下载小程序，可以减少启动小程序的时间。

  /// 批量下载/预加载小程序
  /// [appIds] 小程序ID列表
  /// [apiServer] 服务器地址
  /// [isBatchDownload] 是否批量下载小程序（默认true）
  ///
  /// 返回值格式：
  /// ```
  /// {
  ///   "retMsg": "ok",
  ///   "success": true,
  ///   "data": {
  ///     "list": [
  ///       {
  ///         "appId": "5f72e3559a6a7900019b5baa",
  ///         "success": true,  // 下载是否成功
  ///         "needUpdate": false,  // 是否需要更新
  ///         "errMsg": ""  // 错误信息，成功时为空
  ///       }
  ///     ]
  ///   }
  /// }
  /// ```
  Future<Map<String, dynamic>> downloadApplets(
    List<String> appIds,
    String apiServer,
    {bool isBatchDownload = true}
  )

4. 搜索小程序

App可以主动搜索已经发布的小程序

/// 搜索小程序
  /// [text] 搜索内容
  /// [apiServer] 服务器地址
  ///
  /// 返回值格式：
  /// ```
  /// {
  ///   "retMsg": "ok",
  ///   "success": true,
  ///   "data": {
  ///     "total": 10,          // 搜索到的小程序数量
  ///     "list": [            // 搜索到的小程序集合
  ///       {
  ///       }
  ///     ],
  ///     "pageNo": 0,  // 当前页码
  ///     "pageSize": 10  // 每页数量
  ///   }
  /// }
  /// ```
  Future<Map<String, dynamic>> searchApplets(
    String text,
    String apiServer
  )

5. 获取最近使用过的小程序列表

  /// 获取最近使用的小程序列表
  ///
  /// 返回值格式：
  /// ```
  /// {
  ///   "retMsg": "ok",
  ///   "success": true,
  ///   "data": {
  ///     "list": [            // 小程序数组
  ///       {
  ///       }
  ///     ]
  ///   }
  /// }
  /// ```
  Future<Map<String, dynamic>> getUsedApplets()

6.获取收藏过的小程序列表

  /// 获取收藏的小程序列表
  /// [apiServer] 服务器地址
  /// [pageNo] 页码（传0获取全部）
  /// [pageSize] 页大小（传0获取全部）
  ///
  /// 返回值格式：
  /// ```
  /// {
  ///   "retMsg": "ok",
  ///   "success": true,
  ///   "data": {
  ///     "data": {
  ///       "total": 3,              // 收藏的小程序总数
  ///       "list": [                // 收藏的小程序列表
  ///         {
  ///           "appId": "5f72e3559a6a7900019b5baa",
  ///           "name": "小程序名称",
  ///           "logo": "/api/v1/mop/runtime/download/xxx",  // 图标路径，需要拼接baseUrl
  ///           "createTime": 1758178260152,  // 收藏时间戳
  ///           "currentUserId": "18607180143",
  ///           "encryptedUserId": ""
  ///         }
  ///       ],
  ///       "apiServer": "https://www.finclip.com"
  ///     },
  ///     "errcode": "OK",
  ///     "error": "",
  ///     "traceid": "4aaf26a68c484a31aa9c37859f75d2cd"
  ///   }
  /// }
  /// ```
  Future<Map<String, dynamic>> getFavoriteApplets(
    String apiServer,
    {int pageNo = 0, int pageSize = 0}
  )