# 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?>?)
# 调用示例
注意
- 从
2.13.102
版本开始,FinClip 小程序 SDK 支持配置多个服务器信息,可以同时打开多个不同服务器上的小程序,所以我们提供了配置多个服务器信息的方式。 - 以
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())
目前返回首页按钮出现的条件为(需同时满足):
使用了默认导航栏样式(非 custom)。
不是首页或 tabbar 页面(在 app.json 中定义的)。
是页面栈最底层页面。
小程序可在 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模式