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方式初始化单服务器的方法未来可能会禁用,请优先使用多服务器初始化的方式。
val config = FinAppConfig.Builder()
    .setAppKey("SDK Key")
    .setAppSecret("SDK Secret")
    .setApiUrl("服务器地址")
    .setApiPrefix("服务器接口请求路由前缀")
    .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?) {
    }
})
FinAppConfig config = new FinAppConfig.Builder()
        .setAppKey("SDK Key")
        .setAppSecret("SDK Secret")
        .setApiUrl("服务器地址")
        .setApiPrefix("服务器接口请求路由前缀")
        .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) {

    }
});

// 服务器信息集合
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();

# 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调试按钮。
     */
    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;

    /**
     * 自定义scheme列表
     */
    private String[] schemes = 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)
            .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)
            .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();

    }

# 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 产品介绍,咨询商务报价或私有化部署事宜

0755-86967467

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

联系线上
人工客服

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