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

# 小程序管理

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

# 1. 打开小程序

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

  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)
# 调用示例

    # 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后,合适的时机下载好小程序和基础库包。

        FinAppClient.appletApiManager.startApplet(this, "https://api.finclip.com",
                          "617bb42f530fb30001509b27", null,
                          "$filesDir/framework-3.0.49.zip", "$filesDir/api_demo-1.1.1.zip")
         
      

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

      # 调用示例

        # 1.3 使用 URL Scheme 打开小程序

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

        其中 finapplet为默认的schema,在App中添加字符串资源

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

        可以替换默认的schema

        url的全部内容为 schema://applet/appid/{appId}?path=xxx&query=xxx

        其中{appId}为要打开的小程序id

        ?后面的部分为打开小程序的参数,参数是可选的,path为要打开的小程序路径,query为打开的参数,格式为a=1&b=2,因为path和query包含特殊字符,需要进行urlencode

        # 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 小程序热启动

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

            1. 如果启动参数为空(启动参数对象为 null,或者启动参数对象中 pathqueryreferrerInfo 字段全部为 null 或空字符串 ),则只直接唤起小程序不重新加载页面;
            2. 如果启动参数对象不为 null,且启动参数对象中 pathqueryreferrerInfo 任意字段不为 null 也不为空字符串,则唤起小程序后会重新加载页面。

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