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().setSdkKey和Builder().setSdkSecret方式初始化单服务器的方法未来可能会禁用，请优先使用多服务器初始化的方式。

var storeConfigs = listOf<FinStoreConfig>(
    FinStoreConfig(
        "服务器1 的sdk Key",
        "服务器1 的 sdk secrect",
        "服务器1 的 服务器地址",
        "服务器1 的 apm 上报地址",
        "/api/v1/mop/",
        "",
        FinAppConfig.ENCRYPTION_TYPE_SM
    ),
    FinStoreConfig(
        "服务器2 的sdk Key",
        "服务器2 的 sdk secrect",
        "服务器2 的 服务器地址",
        "服务器2 的 apm 上报地址",
        "/api/v1/mop/",
        "",
        FinAppConfig.ENCRYPTION_TYPE_SM
    )
);
val config = FinAppConfig.Builder()
    .setFinStoreConfigs(storeConfigs)
    .build()
FinAppClient.init(application, config, object : FinCallback<Any?> {
    override fun onSuccess(result: Any?) {
    }

    override fun onProgress(status: Int, info: String?) {
    }

    override fun onError(code: Int, error: String?) {
    }
})

// 服务器信息集合
List<FinStoreConfig> storeConfigs = new ArrayList<>();

// 服务器1的信息
FinStoreConfig storeConfig1 = new FinStoreConfig(
        "SDK Key信息",   // SDK Key
        "SDK Secret信息",   // SDK Secret
        "服务器1的地址",   // 服务器地址
        "服务器1的数据上报服务器地址",   // 数据上报服务器地址
        "/api/v1/mop/",   // 服务器接口请求路由前缀
        "", // SDK指纹
        "加密方式"   // 加密方式，国密:SM，md5: MD5
);
storeConfigs.add(storeConfig1);

// 服务器2的信息
FinStoreConfig storeConfig2 = new FinStoreConfig(
        "SDK Key信息",   // SDK Key
        "SDK Secret信息",   // SDK Secret
        "服务器2的地址",   // 服务器地址
        "服务器2的数据上报服务器地址",   // 数据上报服务器地址
        "/api/v1/mop/",   // 服务器接口请求路由前缀
        "",  // SDK指纹
        "加密方式"   // 加密方式，国密:SM，md5: MD5
);
storeConfigs.add(storeConfig2);

FinAppConfig config = new FinAppConfig.Builder()
        .setFinStoreConfigs(storeConfigs) // 服务器信息集合
        .build();
        
FinAppClient.INSTANCE.init(this, config, new FinCallback<Object>() {
    @Override
    public void onSuccess(Object result) {
    }

    @Override
    public void onError(int code, String error) {
        Toast.makeText(SampleApplication.this, "SDK初始化失败", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onProgress(int status, String info) {

    }
});

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;

    /**
     * 自定义的产品标识
     */
    private String productIdentification = "";

    /**
     * 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调试按钮。
     * @deprecated  使用appletDebugMode代替
     */
    @Deprecated
    private Boolean enableAppletDebug;

     /**
     * 小程序vConsole调试开关模式
     */
    private AppletDebugMode appletDebugMode;

    /**
     * 截屏录屏配置项的优先级，默认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;

    /**
     * 自定义scheme列表
     */
    private String[] schemes = null;

    /**
     * 是否提前创建进程
     */
    private boolean enablePreNewProcess = true;

    /**
     * 性能统计级别
     */
    @IAppletPerformanceManager.Companion.PerformanceLevel
    private int performanceLevel;

    /**
     * 接管XLog日志输出的代理类名
     */
    private String logDelegate = null;

    /**
     * 接管性能日志输出的代理类名
     */
    private String performanceRecordDelegate = null;
    
    /**
     * 语言配置
     */
    private Locale locale = Locale.SIMPLIFIED_CHINESE;
}

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)
            .setSchemes(arrayOf("cctvvideo","sinaweibo"))
            .setBindAppletWithMainProcess(true)
            .setWebViewMixedContentMode(MIXED_CONTENT_NEVER_ALLOW)
            .setFinStoreConfigs(finStoreConfigs)
            .setEnableApmDataCompression(true)
            .setDisableGetSuperviseInfo(true)
            .setCustomWebViewUserAgent("android 7.1.1")
            .setUserId("13286836062")
            .setProductIdentification("happy")
            .setMinAndroidSdkVersion(Build.VERSION_CODES.LOLLIPOP)
            .setLocale(Locale.SIMPLIFIED_CHINESE)
            .build()

        FinAppClient.init(application, config, object : FinCallback<Any?> {

setProductIdentification在2.38.0版本后key使用，需要注意的是，productIdentification中不能使用空白字符以及特殊字符，当使用了setProductIdentification进行自定义产品标识时，需要自定义paths文件，以ProductIdentification值为happy为例，在res/xml路径下，新增名为fin_applet_custom_provider_paths的xml文件，文件名不能更改。文件内容如下：

<!-- 文件名必须为fin_applet_custom_provider_paths.xml, 用于同名替换 --/>
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path
        name="happy_uri"
        path="happy"
        />
</paths>

经过以上设置，一个路径为/internal storeage/packageName/files/happy/hello.jpg的文件，其对应的uri为content://com.finogeeks.finosprite.applet.provider/happy_uri/hello.jpg。

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;
        
        /**
         * 是否隐藏“更多”菜单中的“重新进入小程序”按钮
         */
        private boolean isHideRefreshMenu;

        /**
         * 加载小程序过程中（小程序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();
        
        /**
         * 是否隐藏更多菜单中的调试按钮
         */
        private boolean hideDebugMenu;

    }

UiConfig配置示例

        val uiConfig = UIConfig()
        uiConfig.isHideBackHome = true
        uiConfig.isHideForwardMenu = false
        uiConfig.isHideFeedbackAndComplaints = false
        uiConfig.isHideSettingMenu = false
        uiConfig.navigationBarTitleTextAppearance
        uiConfig.isHideDebugMenu = false

        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")
}

NavHomeConfig配置项

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) 此配置项已废弃
                .setAppletDebugMode(FinAppConfig.AppletDebugMode.appletDebugModeEnable)
                .build()

FinAppClient.init(application, config, object : FinCallback<Any?> {})

    public enum AppletDebugMode {

        /**
         * 未设置状态
         */
        appletDebugModeUndefined,

        /**
         * 不展示vconsole，更多菜单可以打开调试
         */
        appletDebugModeDisable,

        /**
         * 展示vconsole，更多菜单不展示关闭调试选项
         */
        appletDebugModeEnable,

        /**
         * 不展示vconsole，更多菜单不展示打开调试按钮，且不允许小程序调用setEnableDebug
         */
        appletDebugModeForbidden
    }

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