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

# SDK初始化

# 1 初始化

在使用小程序的API之前,需要先初始化小程序SDK。只有成功初始化之后,才能使用SDK提供的API,否则API调用会失败。

# API

/**
 * 初始化小程序SDK
 *
 * @param application  [android.app.Application]实例
 * @param finAppConfig [FinAppConfig]实例,小程序框架的配置信息
 * @param finCallback 初始化状态回调接口
 */
fun init(application: Application, finAppConfig: FinAppConfig, finCallback: FinCallback<Any?>?)

# 调用示例

注意

  1. 2.13.102版本开始,FinClip SDK 支持配置多个服务器信息,可以同时打开多个不同服务器上的小程序,所以我们提供了配置多个服务器信息的方式。
  2. Builder().setAppKeyBuilder().setAppSecret方式初始化单服务器的方法未来可能会禁用,请优先使用多服务器初始化的方式。

    # 2 配置项

    # FinAppConfig配置项

    
    /**
     * 小程序框架的配置信息
     */
    public class FinAppConfig {
    
        /**
         * sdkKey,通过凡泰小程序开放平台签发
         */
        @NonNull
        private String sdkKey = "";
    
        /**
         * sdkSecret,通过凡泰小程序开放平台签发
         */
        @NonNull
        private String sdkSecret = "";
    
        /**
         * SDK指纹
         */
        @NonNull
        private String sdkFingerprint = "";
    
        /**
         * 服务器地址
         */
        @NonNull
        private String apiUrl = "";
    
        /**
         * 数据上报服务器地址
         */
        private String apmServer = "";
    
        /**
         * 服务器接口请求路由前缀
         */
        @NonNull
        @Deprecated
        private String apiPrefix = "";
    
        /**
         * 用户ID
         */
        private String userId;
    
        /**
         * Jwt
         */
        @Deprecated
        private String jwt;
    
        /**
         * Access Token
         */
        @Deprecated
        private String accessToken;
    
        /**
         * 当前是否是Debug模式
         */
        private boolean isDebugMode;
    
        /**
         * Glide加载图片时是否自动加上了jwt
         */
        @Deprecated
        private boolean isGlideWithJWT;
    
        /**
         * UI配置
         */
        private UIConfig uiConfig;
    
        /**
         * APM统计扩展信息
         */
        private Map<String, Object> apmExtendInfo;
    
        /**
         * 加密方式,国密:SM,md5: MD5
         */
        @NonNull
        private String encryptionType;
    
        /*
         * 是否需要服务器对返回数据加密
         */
        private boolean encryptServerData;
    
        /**
         * 是否禁止发起运行时权限申请,默认不禁止
         */
        private boolean disableRequestPermissions;
    
        /**
         * 需要移除Cookies的域名
         */
        private List<String> needToRemoveCookiesDomains;
    
        /**
         * 是否禁止启用Tbs SDK
         */
        private boolean disableTbs;
    
        /**
         * 自定义WebView UserAgent
         */
        private String customWebViewUserAgent;
    
        /**
         * WebView mixed content mode
         */
        private int webViewMixedContentMode;
    
        /**
         * 定时批量更新小程序的数量
         */
        private int appletIntervalUpdateLimit;
    
        /**
         * 最大可同时运行的小程序个数。 如果打开超过此个数的小程序,最早打开的小程序将被回收,但仍可以重新打开
         */
        private int maxRunningApplet;
    
        /**
         * 小程序应用市场配置信息集合
         */
        @NonNull
        private List<FinStoreConfig> finStoreConfigs;
    
        /**
         * 是否在小程序前台运行时启动前台服务
         */
        private ForegroundServiceConfig foregroundServiceConfig;
    
        /**
         * 小程序与app进程绑定,App被杀死,小程序同步关闭
         */
        private boolean bindAppletWithMainProcess;
    
        /**
         * app被杀后关闭小程序的提示文案
         */
        private String killAppletProcessNotice;
    
        /**
         * 小程序文案,可以替换sdk内提示的"小程序"为别的名字
         */
        private String appletText;
    
        /**
         * 请求后端接口时,是否压缩请求的数据
         */
        private boolean enableApmDataCompression;
    
        /**
         * 是否禁止调用获取监管信息的小程序API{@link com.finogeeks.lib.applet.api.supervise.SuperviseModule#API_GET_SUPERVISE_INFO},
         * 默认是允许调用的。
         */
        private boolean disableGetSuperviseInfo;
    
        /**
         * 是否自动允许小程序申请的【小程序级别】的权限
         * 若自动允许,则申请时不会出现授权弹框。
         */
        private boolean appletAutoAuthorize;
    
        /**
         * 是否打开小程序vConsole调试按钮。
         */
        private boolean enableAppletDebug;
    
        /**
         * 截屏录屏配置项的优先级,默认GLOBAL
         */
        private FinAppConfigPriority screenShotPriority;
    
        /**
         * 是否允许截屏录屏,默认允许
         */
        private boolean enableScreenShot;
    
        /**
         * 水印配置项的优先级,默认GLOBAL
         */
        private FinAppConfigPriority watermarkPriority;
    
        /**
         * 是否开启水印,默认不开启
         */
        private boolean enableWatermark;
    
        /**
         * 指定小程序AppId的配置
         */
        private transient IAppletConfigFactory appletConfigFactory;
    
        /**
         * 水印View构造器
         */
        private String watermarkFactoryClass;
    
        /**
         * 请求header配置优先级
         */
        private FinAppConfigPriority headerPriority;
    
        /**
         * request等接口默认传入的header
         */
        private Map<String, String> header;
    
        /**
         * 由宿主app实现的离线分包package文件获取类
         */
        private String offlinePackageFactoryClass;
    
        /**
         * 小程序跳转处理
         */
        private transient NavigateDelegate navigateDelegate;
    
        /**
         * 小程序页面栈的最大深度,0则表示没有深度限制。
         */
        private int pageCountLimit;
    
        /**
         * 最低支持的Android SDK版本
         */
        private int minAndroidSdkVersion = Build.VERSION_CODES.LOLLIPOP;
    
        /**
         * 日志记录等级
         */
        private XLogLevel logLevel;
    
        /**
         * 日志文件最长缓存时间,单位秒。
         *
         * 最小不能小于1天,即不能小于 1 * 24 * 60 * 60 秒。
         */
        private long logMaxAliveSec = -1;
    
        /**
         * XLog日志文件路径
         */
        private String xLogDir = null;
    
        /**
         * 离线小程序AccountInfo工厂类
         */
        private String offlineAccountInfoClass = null;
    
    }
    

    # FinAppConfig配置示例

         val config = FinAppConfig.Builder()
                .setDebugMode(true)
                .setLogLevel(XLogLevel.LEVEL_VERBOSE)
                .setEnableAppletDebug(true)
                .setUiConfig(uiConfig)
                .setApmExtendInfo(apmExtendInfo)
                .setDisableRequestPermissions(false)
                .setNeedToRemoveCookiesDomains(listOf(""))
                .setDisableTbs(false)
                .setAppletIntervalUpdateLimit(3)
                .setMaxRunningApplet(5)
                .setPageCountLimit(5)
                .setBindAppletWithMainProcess(true)
                .setWebViewMixedContentMode(MIXED_CONTENT_NEVER_ALLOW)
                .setFinStoreConfigs(finStoreConfigs)
                .setEnableApmDataCompression(true)
                .setDisableGetSuperviseInfo(true)
                .setCustomWebViewUserAgent("android 7.1.1")
                .setUserId("13286836062")
                .setMinAndroidSdkVersion(Build.VERSION_CODES.LOLLIPOP)
                .build()
    
            FinAppClient.init(application, config, object : FinCallback<Any?> {
    

    # UIConfig配置项

    
        /**
         * UI配置
         */
        public static class UIConfig {
    
            /**
             * 当导航栏为默认导航栏时,是否始终显示返回按钮
             */
            private boolean isAlwaysShowBackInDefaultNavigationBar;
    
            /**
             * 导航栏标题相对父控件的Gravity
             */
            private int navigationBarTitleTextLayoutGravity = Gravity.NO_GRAVITY;
    
            /**
             * 导航栏标题文字样式
             */
            @StyleRes
            private int navigationBarTitleTextAppearance;
    
            /**
             * 是否清除导航栏导航按钮的背景
             */
            private boolean isClearNavigationBarNavButtonBackground;
    
            /**
             * 是否隐藏"更多"菜单中的"反馈与投诉"菜单入口
             */
            private boolean isHideFeedbackAndComplaints;
    
            /**
             * 是否隐藏导航栏上的"返回首页"按钮
             */
            private boolean isHideBackHome;
    
            /**
             * 导航栏上的"返回首页"按钮配置项的优先级,默认GLOBAL
             */
            private FinAppConfigPriority isHideBackHomePriority = FinAppConfigPriority.GLOBAL;
    
            /**
             * 是否隐藏"更多"菜单中的"转发"按钮
             */
            private boolean isHideForwardMenu;
    
            /**
             * 是否隐藏“更多”菜单中的“设置”按钮
             */
            private boolean isHideSettingMenu;
    
            /**
             * 加载小程序过程中(小程序Service层还未加载成功,基础库还没有向SDK传递小程序配置信息),是否隐藏导航栏的关闭按钮
             */
            private boolean hideTransitionCloseButton;
    
            /**
             * 禁用侧滑关闭小程序手势
             */
            private boolean disableSlideCloseAppletGesture;
    
            /**
             * "更多"菜单样式
             */
            @MoreMenuStyle
            private int moreMenuStyle;
    
            /**
             * 胶囊按钮配置
             */
            private CapsuleConfig capsuleConfig = new CapsuleConfig();
    
            private FloatWindowConfig floatWindowConfig = new FloatWindowConfig();
    
            /**
             * Loading页回调Class
             */
            private String loadingLayoutCls;
    
            /**
             * 暗黑模式
             */
            private boolean autoAdaptDarkMode;
    
            /**
             * 导航栏返回首页按钮配置
             */
            private NavHomeConfig navHomeConfig = new NavHomeConfig();
    
        }
    
    

    # UiConfig配置示例

            val uiConfig = UIConfig()
            uiConfig.isHideBackHome = true
            uiConfig.isHideForwardMenu = false
            uiConfig.isHideFeedbackAndComplaints = false
            uiConfig.isHideSettingMenu = false
            uiConfig.navigationBarTitleTextAppearance
    
            uiConfig.moreMenuStyle = UIConfig.MORE_MENU_DEFAULT
    
            val config = FinAppConfig.Builder()
                .setUiConfig(uiConfig)
                
    

    # CapsuleConfig配置项

    val uiConfig = UIConfig()
    uiConfig.setCapsuleConfig(CapsuleConfig())
    

    # 胶囊配置属性介绍

    public static class CapsuleConfig {
            /**
             *  右上角胶囊视图的宽度,默认值为88
             * 
             */
            public float capsuleWidth = 88;
        
            /**
             *  右上角胶囊视图的高度,默认值为32
             * 
             */
            public float capsuleHeight = 32;
        
            /**
             * 右上角胶囊视图的右边距
             */
            public float capsuleRightMargin = 7;
        
            /**
             *  右上角胶囊视图的圆角半径,默认值为5
             * 
             */
            public float capsuleCornerRadius = 5;
        
            /**
             *  右上角胶囊视图的边框宽度,默认值为0.8
             * 
             */
            public float capsuleBorderWidth = 1f;
        
            /**
             * 胶囊背景颜色浅色
             */
            public int capsuleBgLightColor = 0x33000000;
        
            /**
             * 胶囊背景颜色深色
             */
            public int capsuleBgDarkColor = 0x80ffffff;
        
            /**
             *  右上角胶囊视图的边框浅色颜色
             * 
             */
            public int capsuleBorderLightColor = 0x80ffffff;
        
            /**
             *  右上角胶囊视图的边框深色颜色
             * 
             */
            public int capsuleBorderDarkColor = 0x26000000;
        
            /**
             * 胶囊分割线浅色颜色
             */
            public int capsuleDividerLightColor = 0x80ffffff;
        
            /**
             * 胶囊分割线深色颜色
             */
            public int capsuleDividerDarkColor = 0x26000000;
        
            /**
             *  胶囊里的浅色更多按钮的图片对象,如果不传,会使用默认图标
             * 
             */
            public int moreLightImage = R.drawable.miniapps_more_light;
        
            /**
             *  胶囊里的深色更多按钮的图片对象,如果不传,会使用默认图标
             *  
             */
            public int moreDarkImage = R.drawable.miniapps_more_dark;
        
            /**
             *  胶囊里的更多按钮的宽度,高度与宽度相等
             * 
             */
            public float moreBtnWidth = 32;
        
            /**
             *  胶囊里的更多按钮的左边距
             * 
             */
            public float moreBtnLeftMargin = 6;
        
            /**
             *  胶囊里的浅色更多按钮的图片对象,如果不传,会使用默认图标
             * 
             */
            public int closeLightImage = R.drawable.miniapps_close_light;
        
            /**
             *  胶囊里的深色更多按钮的图片对象,如果不传,会使用默认图标
             * 
             */
            public int closeDarkImage = R.drawable.miniapps_close_dark;
        
            /**
             *  胶囊里的关闭按钮的宽度,高度与宽度相等
             * 
             */
            public float closeBtnWidth = 32;
        
            /**
             *  胶囊里的关闭按钮的左边距
             * 
             */
            public float closeBtnLeftMargin = 6;
    }
    

    # 配置胶囊示例

    uiConfig.capsuleConfig.apply {
        capsuleWidth = 86f
        capsuleHeight = 31f
        capsuleRightMargin = 15f
        capsuleCornerRadius = 15.5f
        capsuleBorderWidth = 0.5f
        capsuleBgLightColor = Color.TRANSPARENT
        capsuleBgDarkColor = Color.TRANSPARENT
        capsuleBorderLightColor = Color.parseColor("#88ffffff")
        capsuleBorderDarkColor = Color.parseColor("#a5a9b4")
        moreLightImage = R.drawable.more_light
        moreDarkImage = R.drawable.more_dark
        moreBtnWidth = 25f
        moreBtnLeftMargin = 11f
        closeLightImage = R.drawable.close_light
        closeDarkImage = R.drawable.close_dark
        closeBtnWidth = 25f
        closeBtnLeftMargin = 9f
        capsuleDividerLightColor = Color.parseColor("#88ffffff")
        capsuleDividerDarkColor = Color.parseColor("#a5a9b4")
    }
    
    val uiConfig = UIConfig()
    uiConfig.setNavHomeConfig(NavHomeConfig())
    

    目前返回首页按钮出现的条件为(需同时满足):

    1. 使用了默认导航栏样式(非 custom)。

    2. 不是首页或 tabbar 页面(在 app.json 中定义的)。

    3. 是页面栈最底层页面。

    小程序可在 onShow 中调用 hideHomeButton() 手动隐藏返回首页按钮。

    # 导航栏返回首页按钮样式属性介绍

    public static class NavHomeConfig {
        /**
         * 导航栏返回首页按钮浅色图标,如果不传,会使用默认图标
         */
        public int lightImage = R.drawable.miniapps_home_light;
        /**
         * 导航栏返回首页按钮浅色图标,如果不传,会使用默认图标
         */
        public int darkImage = R.drawable.miniapps_home_dark;
        
        /**
         * 返回首页按钮宽度,默认44
         */
        public float width = 44;
        
        /**
         * 返回首页按钮高度,默认32
         */
        public float height = 32;
        
        /**
         * 返回首页按钮的左边距,默认7
         */
        public float leftMargin = 7;
        
        /**
         * 返回首页按钮边框圆角半径,默认5
         */
        public float cornerRadius = 5;
        
        /**
         * 返回首页按钮边框宽度,默认1
         */
        public float borderWidth = 1;
        
        /**
         * 返回首页按钮浅色边框颜色,默认0X80FFFFFF
         */
        public int borderLightColor = 0x80ffffff;
        
        /**
         * 返回首页按钮深色边框颜色,默认0X26000000
         */
        public int borderDarkColor = 0x26000000;
        
        /**
         * 返回首页按钮浅色背景,默认0x33000000
         */
        public int bgLightColor = 0x33000000;
        
        /**
         * 返回首页按钮深色背景,默认0x33000000
         */
        public int bgDarkColor = 0x80ffffff;
    }
    

    # 配置导航栏返回按钮样式示例

    uiConfig.navHomeConfig.apply {
        width = 43f
        height = 31f
        leftMargin = 15f
        cornerRadius = 15.5f
        borderWidth = 0.5f
        bgLightColor = Color.TRANSPARENT
        bgDarkColor = Color.TRANSPARENT
        borderLightColor = Color.parseColor("#88ffffff")
        borderDarkColor = Color.parseColor("#a5a9b4")
        lightImage = R.drawable.home_light
        darkImage = R.drawable.home_dark
    }
    

    # 配置小程序浮窗运行

    在一些大屏幕设备上,可以配置小程序以浮窗形式运行。以浮窗形式运行时,小程序固定为竖屏模式,浮窗位置和大小可以配置,位于浮窗下层的页面不可交互

    // 设置悬浮模式后,同时要在sample styles.xml将FinAppletTheme覆盖为FinAppletTranslucentTheme

    <!--悬浮模式需要覆盖FinAppletTheme主题为FinAppletTranslucentTheme-->
    <style name="FinAppletTheme" parent="@style/FinAppletTranslucentTheme" />
    

    # 浮窗配置属性介绍

    
            public static class FloatWindowConfig {
                
                public boolean floatMode = false;
    
                public int x;
                public int y;
                public int width;
                public int height;
            }
    

    浮窗配置示例

    uiConfig.floatWindowConfig.apply {
                floatMode = false
                width = 800
                height = 1400
                x = application.screenWidth() / 2 - width / 2
                y = application.screenHeight() / 2 - height / 2
            }
    

    # 设置最大可运行的小程序个数

    该接口可以设置最大可运行的小程序个数,当打开的小程序超过最大可运行个数时,最先打开的小程序会被回收。

    注意

    最大可运行的小程序个数默认为5个,可设置的范围为1-5,设置<=0或>5的数字不生效

    val config = FinAppConfig.Builder()
        .setSdkKey("SDK Key")
        .setSdkSecret("SDK Secret")
        .setMaxRunningApplet(3) //设置最大可运行的小程序个数
        .build()
    
    FinAppClient.init(application, config, object : FinCallback<Any?> {})
    

    # 设置前台服务保持app运行

    当打开小程序后,app进入后台运行。这时app可能会被系统杀死。可以配置通过启动前台服务一直保持app运行而不被系统杀死

    val config = FinAppConfig.Builder()
        .setSdkKey(BuildConfig.SDK_KEY)
        .setSdkSecret(BuildConfig.SDK_SECRET)
        .setForegroundServiceConfig(
            FinAppConfig.ForegroundServiceConfig(
                true, //是否开启前台服务
                R.drawable.ic_launcher, //前台服务的icon
                "小程序正在运行", // 前台服务的标题
                "",
                notificationChannelId, // 通知channelId
                notificationChannelName, // 通知channel名称
                notificationChannelDesc, // 通知channel介绍
            )
        )
        .build()
    
    FinAppClient.init(application, config, object : FinCallback<Any?> {})
    

    # 设置当主进程关闭的时候小程序进程也关闭

    默认情况下,当app主进程关闭的时候,小程序依然可以独立运行。可以配合当app进程关闭或被杀死的时候小程序进程也被关闭

    val config = FinAppConfig.Builder()
                    .setSdkKey(BuildConfig.SDK_KEY)
                    .setSdkSecret(BuildConfig.SDK_SECRET)
                    .setBindAppletWithMainProcess(true) //当主进程关闭的时候小程序进程也关闭
                    .setKillAppletProcessNotice("APP已被关闭,小程序无法单独使用,请您重新打开APP再使用小程序。")
                    .build()
    
    FinAppClient.init(application, config, object : FinCallback<Any?> {})
    

    # 配置小程序调试模式

    val config = FinAppConfig.Builder()
    				// 其它配置项省略
    				.setEnableAppletDebug(true)
                    .build()
    
    FinAppClient.init(application, config, object : FinCallback<Any?> {})
    

    是否开启全局小程序debug模式,设置为true后所有小程序都会显示vconsole,如果设置为false,则开发版、体验版、IDE预览版可通过更多菜单内的调试按钮开启Debug模式

    © 2022 FinClip with ❤

    👋🏻 嘿,你好!

    「FinClip」是一套基于云原生框架设计的小程序容器。能够让任何移动应用在集成小程序SDK之后,获得可用、安全的小程序运行能力。

    >> 点我免费注册体验

    查看产品文档
    了解与 FinClip 相关的一切信息

    产品博客 👈  了解产品更新与核心功能介绍
    资源下载 👈  获取小程序 SDK 与开发工具
    文档中心 👈  查询 FinClip 小程序开发指南与答疑

    商务咨询热线
    预约 FinClip 产品介绍,咨询商务报价或私有化部署事宜

    400-066-00210755-86967467

    获取产品帮助
    联系 FinClip 技术顾问,获取产品资料或加入开发者社群

    联系线上
    人工客服

    或 👉  点击这里,提交咨询工单

    填写 FinClip 问卷抽缤纷夏日盲盒
    Hi,这里是我们为 FinClip 用户准备的一封调研问卷,期待您的参与,您的反馈和建议,将指引 FinClip 未来前进的方向。