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

# 小程序管理

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

# 1. 打开小程序

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

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

# 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
        # 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
          }
          

          调用示例

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

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

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

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

            1. 小程序将在独立的进程中运行。
            2. 小程序自定义api需要视情况分别在主进程或小程序进程中注册,在主进程中注册的自定义api与主进程交互需要进行跨进程通讯。
            3. 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
            }
            

            调用示例

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

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

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

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

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

              # 1.6 小程序热启动

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

              1. 如果热启动执行ReLaunch的模式为ReLaunchMode.PARAMS_EXIST ,则表示只要有启动参数(启动参数中 pathqueryreferrerInfo 任意字段不为 null 也不为空字符串,不管启动参数是否和上一次的启动参数相同),就执行 reLaunch。
              2. 如果热启动执行ReLaunch的模式为ReLaunchMode.ONLY_PARAMS_DIFF ,则表示有启动参数(启动参数中 pathqueryreferrerInfo 任意字段不为 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)
              
              # 调用示例

                # 2.2 关闭所有小程序

                # API
                /**
                 * 关闭所有小程序
                 */
                fun closeApplets()
                
                # 调用示例

                  # 3. 结束小程序

                  # 3.1 结束指定小程序

                  # API
                  /**
                   * 结束正在运行的小程序
                   *
                   * @param appId 小程序id
                   */
                  fun finishRunningApplet(appId: String)
                  
                  # 调用示例

                    # 3.2 结束所有小程序

                    # API
                    /**
                     * 结束所有正在运行的小程序
                     */
                    fun finishAllRunningApplets()
                    
                    # 调用示例

                      # 4. 删除小程序

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

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

                      # 4.1 删除指定小程序

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

                        # 4.2 删除所有小程序

                        # API
                        /**
                         * 清除所有小程序相关数据(数据库、文件等)
                         */
                        fun 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>>)
                          
                          # 调用示例

                            # 6. 将小程序移至前台

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

                              © 2022 FinClip with ❤