小程序管理

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

1. 打开小程序

1. 打开线上小程序，这里一般只需要小程序id和服务器地址即可，该api只能打开正式版和审核版的小程序。

2. 二维码打开小程序，这个场景是扫描小程序平台上的二维码，得到二维码里的内容，然后使用该内容打开小程序。正式版、体验版、审核版、真机调试版、预览版本的小程序二维码都可以使用该Api打开。

3. URL Scheme 打开小程序，这个场景是在H5网页里嵌入 URL Scheme 的URI，触发打开App里的小程序，只支持打开上架的正式版本小程序。

   
   

1.1 普通打开小程序

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)

调用示例

FinAppClient.appletApiManager.startApplet(
    this,
    IFinAppletRequest.fromAppId("apiServer", "appId")
)

FinAppClient.INSTANCE.getAppletApiManager().startApplet(
    this,
    IFinAppletRequest.Companion.fromAppId("apiServer", "appId"),
    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方法来设置启动参数。

调用示例

// path为小程序页面路径
// query为启动参数，内容为"key1=value1&key2=value2 ..."的形式
FinAppClient.appletApiManager.startApplet(
    this,
    IFinAppletRequest.fromAppId("apiServer", "appId")
        .setStartParams(mapOf(
            "path" to "/pages/index/index",
            "query" to "aaa=test&bbb=123"
        ))
)

Map<String, String> params = new HashMap<>();
// path为小程序页面路径
params.put("path", "/pages/index/index");
// query为启动参数，内容为"key1=value1&key2=value2 ..."的形式
params.put("query", "aaa=test&bbb=123");
FinAppClient.INSTANCE.getAppletApiManager().startApplet(
    this,
    IFinAppletRequest.Companion.fromAppId("apiServer", "appId")
        .setStartParams(params),
    null
);

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

注意：

1.如果离线包是放在工程assets目录下，需要先拷贝或移动到app工程沙盒目录。

2.如果离线包是下载至app沙盒目录的，则只需要将路径设置再request上即可。

// 注意，工程assets目录下的离线包，需要先拷贝或移动到app工程沙盒目录。
val assets = listOf(
    "framework-3.2.3.zip",
    "5f17f457297b540001e06ebb-1.0.44.zip"
)
assets.forEach {
    val res = copyFile(getAssets().open(it), "$filesDir/$it")
    toast("拷贝文件$it:$res")
}

FinAppClient.appletApiManager.startApplet(this, IFinAppletRequest.Companion.fromAppId("https://api.finclip.com","5f17f457297b540001e06ebb").setOfflineParams("$filesDir/framework-3.2.3.zip", "$filesDir/5f17f457297b540001e06ebb-1.0.44.zip"))

List<String> assets = Arrays.asList(
        "framework-3.2.3.zip",
        "5f17f457297b540001e06ebb-1.0.44.zip"
);

for (String asset : assets) {
    try {
        InputStream inputStream = getAssets().open(asset);
        String destinationPath = getFilesDir() + "/" + asset;
        boolean result = copyFile(inputStream, destinationPath);
        toast("拷贝文件" + asset + ":" + result);
    } catch (IOException e) {
        e.printStackTrace();
    }
}
String offlineFrameworkPath = getFilesDir() + "/framework-3.2.3.zip";
                String offlineMiniprogramPath = getFilesDir() + "/5f17f457297b540001e06ebb-1.0.44.zip";
RemoteFinAppletRequest remoteRequest = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "617bb42f530fb30001509b27");
                remoteRequest.setOfflineParams(offlineFrameworkPath, offlineMiniprogramPath);
FinAppClient.INSTANCE.getAppletApiManager().startApplet(this, remoteRequest, new FinSimpleCallback<String>() {
    @Override
    public void onSuccess(String result) {
        // 启动成功
    }

    @Override
    public void onError(int code, String error) {
        // 启动失败
    }
});

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)

通过传入QrCodeFinAppletRequest对象，执行二维码打开小程序的操作。

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

调用示例

FinAppClient.appletApiManager.startApplet(
    this,
    IFinAppletRequest.fromQrCode("qrCode"),
    object : FinSimpleCallback<String>() {
        override fun onSuccess(result: String) {
            // 启动成功
        }

        override fun onError(code: Int, error: String?) {
            // 启动失败
        }
    }
)

FinAppClient.INSTANCE.getAppletApiManager().startApplet(
    this,
    IFinAppletRequest.Companion.fromQrCode("qrCode"),
    new FinSimpleCallback<String>() {
        @Override
        public void onSuccess(String result) {
            // 启动成功
        }
        
        @Override
        public void onError(int code, String error) {
            // 启动失败
        }
    }
);

1.3 使用 URL Scheme 打开小程序

<string name="fin_applet_router_url_scheme">your scheme</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 设置小程序运行的进程模式

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

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

    /**
     * 单进程
     */
    SINGLE
}

FinAppClient.appletApiManager.startApplet(context,
    IFinAppletRequest.Companion.fromAppId("appId")
        .setProcessMode(IFinAppletRequest.ProcessMode.MULTI)
)

FinAppClient.INSTANCE.getAppletApiManager().startApplet(context,
        IFinAppletRequest.Companion.fromAppId("appId")
                .setProcessMode(IFinAppletRequest.ProcessMode.MULTI)
);

1. 小程序将在主进程中运行，所有逻辑在主进程中执行。

2. 小程序自定义api只需要在主进程注册，并且也会在主进程执行，自定义api内与主进程交互不需要进行跨进程通讯。在小程序进程注册api的接口不应该再使用。

3. sdk暴露的工厂类，例如watermarkFactoryClass， offlinePackageFactoryClass， offlineAccountInfoClass 等将会跟随小程序在主进程中执行。

1. 小程序将在独立的进程中运行。

2. 小程序自定义api需要视情况分别在主进程或小程序进程中注册，在主进程中注册的自定义api与主进程交互需要进行跨进程通讯。

3. sdk暴露的工厂类，例如watermarkFactoryClass， offlinePackageFactoryClass， offlineAccountInfoClass等在小程序进程中执行。

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

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

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

    /**
     * 单任务
     */
    SINGLE
}

FinAppClient.appletApiManager.startApplet(context,
    IFinAppletRequest.Companion.fromAppId("appId")
        .setTaskMode(IFinAppletRequest.TaskMode.MULTI)
)

FinAppClient.INSTANCE.getAppletApiManager().startApplet(context,
        IFinAppletRequest.Companion.fromAppId("appId")
                .setTaskMode(IFinAppletRequest.TaskMode.MULTI)
);

1. 小程序页面将和启动小程序的页面处于同一任务中。切换到系统近期任务列表，会看到小程序页面被添加到了启动小程序的页面所在的任务中。

2. 当关闭小程序时，小程序页面会被finish，再次打开需要重新启动小程序，小程序无法热执行启动。

1. 小程序页面将和启动小程序的页面处于不同任务中。切换到系统近期任务列表，会看到小程序处于一个独立的任务中。

2. 当关闭小程序时，小程序所在任务会被移至后台，再次打开时小程序所在任务会被唤回前台，小程序能够执行热启动。

1.6 小程序热启动

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

2. 如果热启动执行ReLaunch的模式为ReLaunchMode.ONLY_PARAMS_DIFF ，则表示有启动参数（启动参数中 path， query，referrerInfo 任意字段不为 null 也不为空字符串）且和上一次的启动参数不同时，才执行 reLaunch。

3. 如果热启动执行ReLaunch的模式为ReLaunchMode.ALWAYS ，则表示忽略启动参数（不管有没有启动参数，也不管启动参数是否和上一次的启动参数相同），始终执行 reLaunch。

4. 如果热启动执行ReLaunch的模式为ReLaunchMode.NEVER ，则表示忽略启动参数（不管有没有启动参数，也不管启动参数是否和上一次的启动参数相同），均不执行 reLaunch。

2. 关闭小程序

由于SDK使用多进程的方式加载小程序，该API并不会真正结束小程序，而是将小程序移至系统后台。

2.1 关闭指定小程序

API

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

调用示例

FinAppClient.appletApiManager.closeApplet("appId")

FinAppClient.INSTANCE.getAppletApiManager().closeApplet(appId);

2.2 关闭所有小程序

API

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

调用示例

FinAppClient.appletApiManager.closeApplets()

FinAppClient.INSTANCE.getAppletApiManager().closeApplets();

3. 结束小程序

3.1 结束指定小程序

API

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

调用示例

FinAppClient.appletApiManager.finishRunningApplet("appId")

FinAppClient.INSTANCE.getAppletApiManager().finishRunningApplet("appId");

3.2 结束所有小程序

API

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

调用示例

FinAppClient.appletApiManager.finishAllRunningApplets()

FinAppClient.INSTANCE.getAppletApiManager().finishAllRunningApplets();

4. 删除小程序

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

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

4.1 删除指定小程序

API

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

调用示例

FinAppClient.appletApiManager.removeUsedApplet("appId")

FinAppClient.INSTANCE.getAppletApiManager().removeUsedApplet("appId");

4.2 删除所有小程序

API

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

调用示例

FinAppClient.appletApiManager.clearApplets()

FinAppClient.INSTANCE.getAppletApiManager().clearApplets();

5. 批量下载小程序

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

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. 将小程序移至前台

if (FinAppClient.isFinAppProcess(context)) {
    // 小程序进程
    val activity = FinAppProcessClient.getAppletProcessActivity(appId) as? FinAppHomeActivity
    activity?.moveTaskToFront()
} else {
    // 主进程
    FinAppClient.appletApiManager.moveTaskToFront(appId)
}

if (FinAppClient.INSTANCE.isFinAppProcess(context)) {
    FinAppHomeActivity activity = (FinAppHomeActivity) FinAppProcessClient.INSTANCE.getAppletProcessActivity(appId);
    if (activity != null) {
        activity.moveTaskToFront();
    }
} else {
    FinAppClient.INSTANCE.getAppletApiManager().moveTaskToFront(appId);
}