# 小程序管理

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

# 1. 打开小程序

支持的app类型

小程序✅ 小游戏✅ H5应用✅

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

打开线上小程序，这里一般只需要小程序id和服务器地址即可，该api只能打开正式版和审核版的小程序。
二维码打开小程序，这个场景是扫描小程序平台上的二维码，得到二维码里的内容，然后使用该内容打开小程序。正式版、体验版、审核版、真机调试版、预览版本的小程序二维码都可以使用该Api打开。
URL Scheme 打开小程序，这个场景是在H5网页里嵌入 URL Scheme 的URI，触发打开App里的小程序，只支持打开上架的正式版本小程序。

# 1.1 普通打开小程序

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

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

RemoteFinAppletRequest

属性	类型	描述
appId	String	小程序id，必填
apiServer	String	小程序所属服务器，必填
appTitle	String	小程序名称，非必填
appAvatar	String	小程序图标的网络地址，非必填
startParams	FinAppInfo.StartParams	小程序启动参数，支持的key，path、query，非必填
processMode	ProcessMode	进程模式。枚举类型，默认为 [ProcessMode.MULTI]，即多进程模式
taskMode	TaskMode	任务参数。枚举类型，默认为 [TaskMode.MULTI]，即多任务模式
schemes	Array.<String>	自定义的scheme数组
hideMiniProgramCloseButton	boolean	是否隐藏小程序页面胶囊里的关闭按钮，默认为false
hideMiniProgramMoreButton	boolean	是否隐藏小程序页面胶囊里的更多按钮，默认为false
sequence	Int	小程序索引，非必填
offlineLibraryPath	String	离线小程序压缩包路径，可传入一个本地小程序包路径，加快首次启动速度，非必填
offlineFrameworkZipPath	String	离线基础库压缩包路径，可传入一个基础库路径，加快首次启动速度，非必填
from	Int	来源，数据上报时记录到apm事件中
reLaunchMode	ReLaunchMode	小程序热启动时执行reLaunch的模式。枚举类型，默认为 [ReLaunchMode.PARAMS_EXIST]，即只要有启动参数（启动参数不为null也不为空字符串，不管启动参数是否和上一次的启动参数相同），就执行reLaunch
backgroundColorContent	Int	小程序页面容器背景色

# 1.1.1 打开小程序(基础参数)

# API

/**
 * 通过参数封装对象来启动小程序
 * @param request 参数封装，包括RemoteFinAppletRequest, QrCodeFinAppletRequest, LocalFinAppletRequest, DecryptFinAppletRequest,
 * 建议使用IFinAppletRequest.fromAppId, IFinAppletRequest.fromQrCode, IFinAppletRequest.fromLocal, IFinAppletRequest.fromDecrypt等方法生成对应的request对象。
 */
fun startApplet(context: Context, request: IFinAppletRequest, callback: FinCallback<String?>? = null)

# 调用示例

# 1.1.2 打开小程序(带启动参数)

# API

/**
 * 通过参数封装对象来启动小程序
 * @param request 参数封装，包括RemoteFinAppletRequest, QrCodeFinAppletRequest, LocalFinAppletRequest, DecryptFinAppletRequest,
 * 建议使用IFinAppletRequest.fromAppId, IFinAppletRequest.fromQrCode, IFinAppletRequest.fromLocal, IFinAppletRequest.fromDecrypt等方法生成对应的request对象。
 */
fun startApplet(context: Context, request: IFinAppletRequest, callback: FinCallback<String?>? = null)

通过传入RemoteFinAppletRequest对象，并通过setStartParams方法来设置启动参数。

# 调用示例

# 1.1.3 打开小程序(使用离线包)

由于首次打开小程序时，要下载小程序包和基础库包，所以首次启动较慢。针对这种情况，我们可以将小程序包、基础库包下载好放置再工程中打包；也可以在打开app后，合适的时机下载好小程序和基础库包。

注意： 1.如果离线包是放在工程assets目录下，需要先拷贝或移动到app工程沙盒目录。 2.如果离线包是下载至app沙盒目录的，则只需要将路径设置再request上即可。

# 1.2 二维码打开小程序

扫描平台中的小程序二维码，将解析出来的小程序二维码内容传给接口打开小程序。

QrCodeFinAppletRequest

属性	类型	描述
qrCode	String	二维码内容，必填
appTitle	String	小程序名称，非必填
appAvatar	String	小程序图标的网络地址，非必填
processMode	ProcessMode	进程模式。枚举类型，默认为 [ProcessMode.MULTI]，即多进程模式
taskMode	TaskMode	任务参数。枚举类型，默认为 [TaskMode.MULTI]，即多任务模式
schemes	Array.<String>	自定义的scheme数组
hideMiniProgramCloseButton	boolean	是否隐藏小程序页面胶囊里的关闭按钮，默认为false
hideMiniProgramMoreButton	boolean	是否隐藏小程序页面胶囊里的更多按钮，默认为false
from	Int	来源，数据上报时记录到apm事件中
reLaunchMode	ReLaunchMode	小程序热启动时执行reLaunch的模式。枚举类型，默认为 [ReLaunchMode.PARAMS_EXIST]，即只要有启动参数（启动参数不为null也不为空字符串，不管启动参数是否和上一次的启动参数相同），就执行reLaunch
backgroundColorContent	Int	小程序页面容器背景色

# API

/**
 * 通过参数封装对象来启动小程序
 * @param request 参数封装，包括RemoteFinAppletRequest, QrCodeFinAppletRequest, LocalFinAppletRequest, DecryptFinAppletRequest,
 * 建议使用IFinAppletRequest.fromAppId, IFinAppletRequest.fromQrCode, IFinAppletRequest.fromLocal, IFinAppletRequest.fromDecrypt等方法生成对应的request对象。
 */
fun startApplet(context: Context, request: IFinAppletRequest, callback: FinCallback<String?>? = null)

通过传入QrCodeFinAppletRequest对象，执行二维码打开小程序的操作。注意：打开体验版二维码时，需在初始化sdk时添加对应的体验成员userId。

# 调用示例

# 1.3 使用 URL Scheme 打开小程序

小程序支持通过URL Scheme的方式打开，在浏览器或者其他应用中打开如"finapplet://applet/appid/xxxx"形式的链接可以打开小程序

其中 finapplet为默认的scheme，在App中添加字符串资源，来替换默认的scheme

<string name="fin_applet_router_url_scheme">your scheme</string>

Scheme URI 的完整格式：${scheme}://applet/appid/${appId}?path=${path}&query=${encode过的query}&apiServer=${encode过的apiServer}

配置名称	类型	是否必填	配置描述
scheme	String	是	默认值为finapplet，最好自己设置，避免与其他app重复，可使用fat{sdkKey的16位小写md5}，示例fat705b46f78820c7a8
appId	String	是	小程序id
path	String	否	小程序页面路径，示例pages/index/index
query	String	否	小程序的参数，URLEncode(key1=value1&key2=value2)
apiServer	String	否	小程序所属服务器，默认会取初始化的第一个服务器。当初始化多个服务器时，需要传入。

示例如下：

<a href='fatd919cec7395563d7://applet/appid/617bb42f530fb30001509b27?path=pages/index/index&query=key%3Dvalue%26name%3Dtable&apiServer=https%3A%2F%2Fwww.finclip.com'>打开小程序</a>

# 1.4 设置小程序运行的进程模式

小程序支持以多进程或单进程模式运行，默认为多进程模式，配置的方式为在打开小程序时设置IFinAppletRequest的processMode属性。

/**
 * 设置打开小程序时使用的进程模式
 * @param processMode 进程模式，[ProcessMode.MULTI] 为多进程模式，[ProcessMode.SINGLE] 为单进程模式
 */
fun setProcessMode(processMode: ProcessMode): IFinAppletRequest

进程模式ProcessMode：

/**
 * 进程模式
 */
enum class ProcessMode {
    /**
     * 多进程
     */
    MULTI,

    /**
     * 单进程
     */
    SINGLE
}

调用示例

小程序单进程与多进程运行模式的不同

当小程序以单进程模式运行时：

小程序将在主进程中运行，所有逻辑在主进程中执行。
小程序自定义api只需要在主进程注册，并且也会在主进程执行，自定义api内与主进程交互不需要进行跨进程通讯。在小程序进程注册api的接口不应该再使用。
sdk暴露的工厂类，例如watermarkFactoryClass， offlinePackageFactoryClass， offlineAccountInfoClass 等将会跟随小程序在主进程中执行。

当小程序以多进程模式运行时：

小程序将在独立的进程中运行。
小程序自定义api需要视情况分别在主进程或小程序进程中注册，在主进程中注册的自定义api与主进程交互需要进行跨进程通讯。
sdk暴露的工厂类，例如watermarkFactoryClass， offlinePackageFactoryClass， offlineAccountInfoClass等在小程序进程中执行。

# 1.5 设置小程序运行的任务模式

小程序支持以多任务或单任务模式运行，默认为多任务模式，配置的方式为在打开小程序时设置IFinAppletRequest的taskMode属性。

/**
 * 设置打开小程序时使用的任务模式
 * @param taskMode 任务模式，[TaskMode.MULTI] 为多任务模式，[TaskMode.SINGLE] 为单任务模式
 */
fun setTaskMode(taskMode: TaskMode): IFinAppletRequest

任务模式TaskMode：

/**
 * 任务模式
 */
enum class TaskMode {
    /**
     * 多任务
     */
    MULTI,

    /**
     * 单任务
     */
    SINGLE
}

调用示例

小程序单任务与多任务运行模式的不同

当小程序以单任务模式运行时：

小程序页面将和启动小程序的页面处于同一任务中。切换到系统近期任务列表，会看到小程序页面被添加到了启动小程序的页面所在的任务中。
当关闭小程序时，小程序页面会被finish，再次打开需要重新启动小程序，小程序无法热执行启动。

当小程序以多任务模式运行时：

小程序页面将和启动小程序的页面处于不同任务中。切换到系统近期任务列表，会看到小程序处于一个独立的任务中。
当关闭小程序时，小程序所在任务会被移至后台，再次打开时小程序所在任务会被唤回前台，小程序能够执行热启动。

# 1.6 小程序热启动

在小程序已经打开过的情况下，再次打开时如果不是打开新版本，则会执行热启动，即直接唤起已打开的小程序，并根据启动小程序时设置的热启动执行ReLaunch的模式和启动参数判断是否重新加载页面：

如果热启动执行ReLaunch的模式为ReLaunchMode.PARAMS_EXIST ，则表示只要有启动参数（启动参数中 path， query，referrerInfo 任意字段不为 null 也不为空字符串，不管启动参数是否和上一次的启动参数相同），就执行 reLaunch。
如果热启动执行ReLaunch的模式为ReLaunchMode.ONLY_PARAMS_DIFF ，则表示有启动参数（启动参数中 path， query，referrerInfo 任意字段不为 null 也不为空字符串）且和上一次的启动参数不同时，才执行 reLaunch。
如果热启动执行ReLaunch的模式为ReLaunchMode.ALWAYS ，则表示忽略启动参数（不管有没有启动参数，也不管启动参数是否和上一次的启动参数相同），始终执行 reLaunch。
如果热启动执行ReLaunch的模式为ReLaunchMode.NEVER ，则表示忽略启动参数（不管有没有启动参数，也不管启动参数是否和上一次的启动参数相同），均不执行 reLaunch。

# 2. 关闭小程序

支持的app类型

小程序✅ 小游戏✅ H5应用✅

1.使用多任务栈的方式加载小程序，该API并不会真正结束小程序，而是将小程序移至系统后台。下次打开小程序，会热启动。 2.使用单任务栈的方式加载小程序，该API会将结束小程序(即销毁小程序)。下次打开小程序，会冷启动。

# 2.1 关闭指定小程序

# API

/**
 * 关闭小程序
 *
 * @param appId 小程序id
 */
fun closeApplet(appId: String)

# 调用示例

# 2.2 关闭所有小程序

# API

/**
 * 关闭所有小程序
 */
fun closeApplets()

# 调用示例

# 3. 结束小程序

支持的app类型

小程序✅ 小游戏✅ H5应用✅

结束小程序，就是销毁小程序。下次使用相同小程序id 打开小程序时，会新建一个小程序对象，即冷启动小程序。

多任务栈打开小程序时，通过右上角的胶囊关闭小程序，或者调用关闭小程序api，都是将小程序退至后台，下次再打开会热启动小程序。

冷启动小程序，最直观的感受是有loading页面，进入小程序页面的耗时会稍微长一点。

# 3.1 结束指定小程序

# API

/**
 * 结束正在运行的小程序
 *
 * @param appId 小程序id
 */
fun finishRunningApplet(appId: String)

# 调用示例

# 3.2 结束所有小程序

# API

/**
 * 结束所有正在运行的小程序
 */
fun finishAllRunningApplets()

# 调用示例

# 4. 删除小程序

支持的app类型

小程序✅ 小游戏✅ H5应用✅

由于会将小程序包和小程序信息缓存在本地，以后打开时速度会非常快。

所以，如果想要将小程序的所有信息都删除，那么可以调用以下api删除某个小程序或者删除所有小程序，删除的内容包括小程序本体、数据库、文件等。

# 4.1 删除指定小程序

# API

/**
 * 移除使用过的小程序
 *
 * @param appId 小程序id
 */
fun removeUsedApplet(appId: String)

# 调用示例

# 4.2 删除所有小程序

# API

/**
 * 清除所有小程序相关数据（数据库、文件等）
 */
fun clearApplets()

# 调用示例

# 5. 批量下载小程序

支持的app类型

小程序✅ 小游戏✅ H5应用✅

提前把小程序下载到本地，可以提高初次启动小程序的时间。

# API

/**
 * 批量下载小程序到本地
 * @param context [Context]实例
 * @param apiServer 小程序所在应用市场的服务器地址
 * @param appIds 需要下载的小程序id数组
 * @param callback 结果回调
 * 注意：回调结果对象[AppletDownLoadInfo]字段
         @param appId       被下载的小程序id 
         @param success     小程序是否获取成功
         @param needUpdate  是否需要更新本地小程序  true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
 */
fun downloadApplets(context: Context ,apiServer:String ,appIds: List<String>,callback: FinSimpleCallback<List<AppletDownLoadInfo>>)

/**
 * 批量下载小程序到本地
 * @param context [Context]实例
 * @param apiServer 小程序所在应用市场的服务器地址
 * @param appIds 需要下载的小程序id数组
 * @param isBatchDownloadApplets 获取小程序详情后是否下载这些小程序
 * @param callback 结果回调
 * 注意：回调结果对象[AppletDownLoadInfo]字段
         @param appId       被下载的小程序id 
         @param success     小程序是否获取成功
         @param needUpdate  是否需要更新本地小程序  true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
 */
fun downloadApplets(context: Context ,apiServer:String ,appIds: List<String>, isBatchDownloadApplets: Boolean, callback: FinSimpleCallback<List<AppletDownLoadInfo>>)

# 调用示例

val appIds = listOf("appId1","appId2")
FinAppClient.appletApiManager.downloadApplets(this, "apiServer", appIds, object :
                FinSimpleCallback<List<AppletDownLoadInfo>>() {
                override fun onError(code: Int, error: String?) {
                // 失败回调，仅回调一次（ 和onSuccess是互斥的）
                // 由于批量下载小程序是多个网络请求，意味错误的发生会有多次。为了避免多次回调。
                // 此回调出现，代表所有小程序都下载失败（可能是网络问题、可能是小程序id问题等等；总之就是这个回调意味着没有任何一个小程序下载成功）。
                }

                override fun onSuccess(result: List<AppletDownLoadInfo>) {
                //成功回调，仅回调一次；但是并不代表所有小程序都下载成功，需要根据 AppletDownLoadInfo 字段解释
                //AppletDownLoadInfo#appId  被下载的小程序id
                //AppletDownLoadInfo#success  小程序是否获取成功. true:获取成功 ; false:获取失败
                //AppletDownLoadInfo#needUpdate  是否需要更新本地小程序 ; true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
                //总之：小程序是否下载成功，一定要通过 AppletDownLoadInfo#success 字段判断，不要通过回调是否成功来判断。
                }
            })

val appIds = listOf("appId1","appId2")
FinAppClient.appletApiManager.downloadApplets(this, "apiServer", appIds, true,object :
                FinSimpleCallback<List<AppletDownLoadInfo>>() {
                override fun onError(code: Int, error: String?) {
                // 失败回调，仅回调一次（ 和onSuccess是互斥的）
                // 由于批量下载小程序是多个网络请求，意味错误的发生会有多次。为了避免多次回调。
                // 此回调出现，代表所有小程序都下载失败（可能是网络问题、可能是小程序id问题等等；总之就是这个回调意味着没有任何一个小程序下载成功）。
                }

                override fun onSuccess(result: List<AppletDownLoadInfo>) {
                //成功回调，仅回调一次；但是并不代表所有小程序都下载成功，需要根据 AppletDownLoadInfo 字段解释
                //AppletDownLoadInfo#appId  被下载的小程序id
                //AppletDownLoadInfo#success  小程序是否获取成功. true:获取成功 ; false:获取失败
                //AppletDownLoadInfo#needUpdate  是否需要更新本地小程序 ; true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
                //总之：小程序是否下载成功，一定要通过 AppletDownLoadInfo#success 字段判断，不要通过回调是否成功来判断。
                }
            })

List<String> appIds = Arrays.asList("appId1","appId2");
FinAppClient.INSTANCE.getAppletApiManager().downloadApplets(this, "apiServer", appIds,
        new FinSimpleCallback<List<AppletDownLoadInfo>>() {
            @Override
            public void onError( int code, String error) {
             // 失败回调，仅回调一次（ 和onSuccess是互斥的）
             // 由于批量下载小程序是多个网络请求，意味错误的发生会有多次。为了避免多次回调。
             // 此回调出现，代表所有小程序都下载失败（可能是网络问题、可能是小程序id问题等等；总之就是这个回调意味着没有任何一个小程序下载成功）。
            }
            @Override
            public void onSuccess( List<AppletDownLoadInfo> result) {
             //成功回调，仅回调一次；但是并不代表所有小程序都下载成功，需要根据 AppletDownLoadInfo 字段解释
             //AppletDownLoadInfo#appId  被下载的小程序id
             //AppletDownLoadInfo#success  小程序是否获取成功. true:获取成功 ; false:获取失败
             //AppletDownLoadInfo#needUpdate  是否需要更新本地小程序 ; true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
             //总之：小程序是否下载成功，一定要通过 AppletDownLoadInfo#success 字段判断，不要通过回调是否成功来判断。
            }
        }
);

List<String> appIds = Arrays.asList("appId1","appId2");
FinAppClient.INSTANCE.getAppletApiManager().downloadApplets(this, "apiServer", appIds,true
        new FinSimpleCallback<List<AppletDownLoadInfo>>() {
            @Override
            public void onError( int code, String error) {
             // 失败回调，仅回调一次（ 和onSuccess是互斥的）
             // 由于批量下载小程序是多个网络请求，意味错误的发生会有多次。为了避免多次回调。
             // 此回调出现，代表所有小程序都下载失败（可能是网络问题、可能是小程序id问题等等；总之就是这个回调意味着没有任何一个小程序下载成功）。
            }
            @Override
            public void onSuccess( List<AppletDownLoadInfo> result) {
             //成功回调，仅回调一次；但是并不代表所有小程序都下载成功，需要根据 AppletDownLoadInfo 字段解释
             //AppletDownLoadInfo#appId  被下载的小程序id
             //AppletDownLoadInfo#success  小程序是否获取成功. true:获取成功 ; false:获取失败
             //AppletDownLoadInfo#needUpdate  是否需要更新本地小程序 ; true:小程序来源于网络 ; false:小程序本地已经是最新版无需下载 （此字段只有 success 为 true 的时候才有意义）
             //总之：小程序是否下载成功，一定要通过 AppletDownLoadInfo#success 字段判断，不要通过回调是否成功来判断。
            }
        }
);

# 6. 将小程序移至前台

部分特殊场景下可能会需要手动将小程序页面从页面栈中移至栈顶，可以通过以下方法实现。

FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# 小程序管理

# 1. 打开小程序

# 1.1 普通打开小程序

# 1.1.1 打开小程序(基础参数)

# API

# 调用示例

# 1.1.2 打开小程序(带启动参数)

# API

# 调用示例

# 1.1.3 打开小程序(使用离线包)

# 1.2 二维码打开小程序

# API

# 调用示例

# 1.3 使用 URL Scheme 打开小程序

# 1.4 设置小程序运行的进程模式

# 1.5 设置小程序运行的任务模式

# 1.6 小程序热启动

# 2. 关闭小程序

# 2.1 关闭指定小程序

# API

# 调用示例

# 2.2 关闭所有小程序

# API

# 调用示例

# 3. 结束小程序

# 3.1 结束指定小程序

# API

# 调用示例

# 3.2 结束所有小程序

# API

# 调用示例

# 4. 删除小程序

# 4.1 删除指定小程序

# API

# 调用示例

# 4.2 删除所有小程序

# API

# 调用示例

# 5. 批量下载小程序

# API

# 调用示例

# 6. 将小程序移至前台