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

# SDK 初始化

注意

小程序、小游戏、H5应用都是用的是同一个SDK,所以初始化SDK的逻辑都是一样的。

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

# 1. 初始化

初始化SDK的API有两个:

/// 初始化SDK
/// @param config 配置对象
/// @param error 初始化失败时返回的error
- (BOOL)initWithConfig:(FATConfig *)config error:(NSError **)error;

/// 初始化SDK
/// @param config 配置对象
/// @param uiConfig UI配置对象
/// @param error 初始化失败时返回的error
- (BOOL)initWithConfig:(FATConfig *)config uiConfig:(FATUIConfig *)uiConfig error:(NSError **)error;

初始化示例:

FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
storeConfig.sdkKey = @"这里填上的SDK Key";
storeConfig.sdkSecret = @"这里填上SDK secret";
storeConfig.apiServer = @"这里填上你们的服务器地址"; // 例如:https://api.finclip.com;
FATConfig *config = [FATConfig configWithStoreConfigs:@[storeConfig]];
    
[[FATClient sharedClient] initWithConfig:config error:nil];

注意

  1. 从2.13.109版本开始,FinClip 小程序 SDK 支持配置多个服务器信息,这样就可以打开A服务器上的小程序,又可以打开B服务器上的小程序,所以我们提供了配置多个服务器信息的方式。
  2. configWithAppSecret:appKey:未来会弃用,请尽早替换为configWithStoreConfigs的方式构造FATConfig。
  3. 自2.34.1开始,不再需要配置apiPrefix,内部已经在接口上配置好了apiPrefix。

以下是配置多个服务器初始化SDK的示例:

NSString *plistPath = [[NSBundle mainBundle] pathForResource:@"servers" ofType:@"plist"];
NSArray *array = [NSArray arrayWithContentsOfFile:plistPath];
NSMutableArray *storeArrayM = [NSMutableArray array];
for (NSDictionary *dict in array) {
    FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
    storeConfig.sdkKey = dict[@"sdkKey"];
    storeConfig.sdkSecret = dict[@"sdkSecret"];
    storeConfig.apiServer = dict[@"apiServer"];
    storeConfig.apmServer = dict[@"apmServer"];
    if ([@"SM" isEqualToString:dict[@"cryptType"]]) {
        storeConfig.cryptType = FATApiCryptTypeSM;
    } else {
        storeConfig.cryptType = FATApiCryptTypeMD5;
    }
    
    [storeArrayM addObject:storeConfig];
}
FATConfig *config = [FATConfig configWithStoreConfigs:storeArrayM];
[[FATClient sharedClient] initWithConfig:config error:nil];

# 2. 配置项

初始化SDK时的配置项分FATConfigFATUIConfigFATConfig中主要是与UI不相关的配置项;而FATUIConfig主要都是与UI相关的配置项。

# 2.1 FATConfig配置项

配置名称 类型 配置描述
currentUserId NSString 当前用户唯一标识,小程序缓存信息会存储在以userId命名的不同目录下
encryptUserId BOOL (后台接口)是否对userId进行加密传输,需要确保后台服务升级至1.4.1以上,否则加密会导致接口请求失败,默认为false
productIdentification NSString 产品的标识,配置会将文件夹、UserAgent里的FinClip 等标识改为配置后的值
disableAuthorize BOOL 是否禁止SDK触发权限申请,默认为NO,如果设置为YES,则SDK内使用权限的api,不会主动申请权限。
appletAutoAuthorize BOOL 是否允许SDK自动授予小程序权限。默认为NO,如果设置为YES,则小程序里首次触发权限时不会展示权限弹框
disableGetSuperviseInfo BOOL 是否禁用SDK的监管接口API,默认为NO,如果设置为YES,则SDK禁用监管接口API(getSuperviseInfo)
appletIntervalUpdateLimit NSInteger 后台自动检查更新的小程序个数,取值范围:0~50。0代表不检查更新;不设置默认是3。
apmExtension NSDictionary apm统计的扩展信息。
startCrashProtection BOOL 是否开启Crash防崩溃。UnrecognizedSelector、KVO、Notification、Timer、Container(数组越界,字典插入nil等)、String (越界、nil等)
enableApmDataCompression BOOL apm数据上报时,是否压缩数据
appletDebugMode FATAppletDebugMode 小程序debug模式设置。 默认为default,非正式版可通过api或者更多菜单开启;enable为强制所有小程序开启vConsole,方便开发阶段调试;forbidden强制所有版本关闭vConsole;forbiddenRelease 仅强制所有正式版关闭vConsole,其他版本同defatult
webViewInspectable boolean iOS 16.4 以后是否支持WebView调试,默认为NO
enableWatermark BOOL 是否显示水印,默认为NO
watermarkPriority FATConfigPriority 显示水印优先级设置,默认全局配置优先
baseLoadingViewClass NSString 自定义loading视图的class名称
baseLoadFailedViewClass NSString 自定义失败视图的class名称
header NSDictionary 小程序中网络请求的header
headerPriority FATConfigPriority header优先级设置
enableH5AjaxHook BOOL 是否开启小程序中加载的H5页面hook功能,非必填。详情见api中的注释
h5AjaxHookRequestKey NSString 开启enableH5AjaxHook后,会hook request请求,可设置requestKey
pageCountLimit NSUInteger 小程序中页面栈的最大限制。默认值为0,表示不限制。
schemes NSArray<NSString> 自定义的scheme数组,例如@[@"tel",@"music"]。 SDK内部默认支持微信、支付宝、 FinClip App 、tel这些scheme
language FATPreferredLanguage SDK的语言类型。 目前仅支持中文和英文,默认情况下为中文,不支持的类型也会显示为中文
customLanguagePath NSString 自定义SDK语言的相对路径。优先级高于 language 属性。(仅 iOS 平台生效)
pickerRegionPath NSString 文件路径可以是应用的沙盒目录中的路径,也可以是包含在应用Bundle中的文件名,如果此属性为空或未设置,picker组件将加载默认的区域数据。
backgroundFetchPeriod NSInteger 周期性更新的时间间隔(小时), 设置为0不会发起周期性更新请求和触发预拉取请求,接收设置范围为3-12小时,默认是12小时。

# 2.2 FATStoreConfig配置项

配置名称 类型 是否必填 说明
sdkKey NSString 创建应用时生成的sdkKey
sdkSecret NSString 创建应用时生成的sdkKey
apiServer NSString 服务器地址,客户部署的后台地址
apmServer NSString apm事件上报的服务器地址,不设置时使用apiServer
cryptType FATApiCryptType 枚举值,网络接口加密类型。默认为md5,也可以设置为SM(国密)
fingerprint NSString SDK指纹,在证联环境时必须传,否则接口访问不通
encryptServerData BOOL 默认为NO。目前只能设置为NO,设置为YES会导致接口访问失败
enablePreloadFramework BOOL 默认为YES。是否预下载基础库,如果设置为NO,则在初始化SDK时关闭预下载基础库

# 2.3 FATUIConfig配置项

配置名称 类型 配置描述
navigationTitleTextAttributes NSDictionary<NSAttributedStringKey, id> 导航栏标题的样式,目前仅支持字体的配置。
navigationBarHeight CGFloat 导航栏高度,默认值为44
navigationBarTitleLightColor UIColor 导航栏的浅色标题的颜色,用在暗黑模式下
navigationBarTitleDarkColor UIColor 导航栏的深色标题的颜色,用在明亮模式下
navigationBarBackBtnLightColor UIColor 导航栏浅色返回按钮的颜色,用在暗黑模式下
navigationBarBackBtnDarkColor UIColor 导航栏深色返回按钮的颜色,用在明亮模式下
capsuleConfig FATCapsuleConfig 右上角胶囊的样式配置,具体参数见FATCapsuleConfig
navHomeConfig FATNavHomeConfig 返回首页按钮的配置的样式配置,具体参数见FATNavHomeConfig
authViewConfig FATAuthViewConfig 权限弹框视图的样式配置,具体参数见FATAuthViewConfig
shareItemConfig FATShareItemConfig 转发按钮配置,具体参数见FATShareItemConfig
navigationBackImage UIImage 导航栏返回按钮的图片对象
progressBarColor UIColor 小程序中的 WebView 组件加载链接时的进度条颜色
hideWebViewProgressBar BOOL 是否隐藏小程序中的 WebView 组件加载链接时的进度条
moreMenuStyle FATMoreViewStyle 胶囊里更多按钮弹出的菜单视图的样式
hideBackToHome BOOL 是否隐藏导航栏中回到首页按钮。
hideBackToHomePriority FATConfigPriority 隐藏回到首页按钮的优先级设置
hideShareAppletMenu BOOL 是否隐藏小程序更多菜单中的分享按钮,默认是YES。
hideForwardMenu BOOL 是否隐藏更多菜单中的转发按钮。
hideClearCacheMenu BOOL 是否隐藏更多菜单中的 【清理缓存】 的菜单,默认为NO。
hideRefreshMenu BOOL 是否隐藏更多菜单中的重新进入按钮。
hideSettingMenu BOOL 是否隐藏小程序更多菜单中的设置按钮。
hideDebugMenu BOOL 是否隐藏更多菜单中打开/关闭调试按钮。
hideFavoriteMenu BOOL 是否隐藏更多菜单中收藏/取消收藏按钮,默认是YES
hideAddToDesktopMenu 是否隐藏更多菜单中添加到桌面按钮,默认是YES
hideFeedbackMenu BOOL 是否隐藏更多菜单中的投诉反馈按钮。
autoAdaptDarkMode boolean 是否自适应系统深色模式(2.44.5版本废弃,使用新的themeStyle属性)
themeStyle FATUserInterfaceStyle 主题模式
appendingCustomUserAgent NSString 您需要添加至userAgent中的内容。
appletText NSString 默认为“小程序”,您需要替换展示的名称。比如设置会"轻应用",所有显示"小程序"的地方,都会变为"轻应用"
transtionStyle FATTranstionStyle 打开小程序时的默认动画方式。不设置时,默认为FATTranstionStyleUp。可设置如下场景:1. scheme 打开小程序;2. universal link 打开小程序;3. navigateToMiniprogram的动画方式
hideTransitionCloseButton BOOL 是否隐藏转场页的关闭按钮。默认为NO
disableSlideCloseAppletGesture BOOL 是否禁用侧滑关闭小程序的手势。默认为NO
commonUISupportOrientaion FATInterfaceOrientation 公共UI界面的方向,默认为固定竖屏
useNativeLiveComponent BOOL 是否使用内置的live组件。默认为NO,当设置为YES时,还需要依赖FATAppletLive扩展SDK
moreMenuLogoConfig FATImageViewConfig 弹出的菜单视图的logo配置,具体参数见FATImageViewConfig

# 2.4 FATCapsuleConfig配置项

配置名称 类型 配置描述
hideCapsuleCloseButton BOOL 隐藏小程序胶囊里的关闭按钮
capsuleWidth CGFloat 胶囊的宽度
capsuleHeight CGFloat 胶囊的高度
capsuleRightMargin CGFloat 胶囊的右边框距离屏幕右边框的距离
capsuleCornerRadius CGFloat 胶囊的圆角半径
capsuleBorderWidth CGFloat 胶囊的边框宽度
moreBtnWidth CGFloat 胶囊的更多按钮宽度
moreBtnLeftMargin CGFloat 更多按钮的左边距
closeBtnWidth CGFloat 胶囊里关闭按钮的宽度
closeBtnLeftMargin CGFloat 胶囊里关闭按钮的左边距
locationLightImage UIImage 胶囊里的浅色定位按钮的图片对象,如果不传,会使用默认图标
locationDarkImage UIImage 胶囊里的深色定位按钮的图片对象,如果不传,会使用默认图标
microphoneLightImage UIImage 胶囊里的浅色麦克风按钮的图片对象,如果不传,会使用默认图标
microphoneDarkImage UIImage 胶囊里的深色麦克风按钮的图片对象,如果不传,会使用默认图标
moreLightImage UIImage 胶囊的浅色更多按钮图片
moreDarkImage UIImage 胶囊的深色更多按钮图片
closeLightImage UIImage 胶囊里的深色关闭按钮图片
closeDarkImage UIImage 胶囊里的深色关闭按钮图片
capsuleBorderLightColor UIColor 胶囊的浅色边框颜色
capsuleBorderDarkColor UIColor 胶囊的深色边框颜色
capsuleBgLightColor UIColor 胶囊的浅色下背景颜色
capsuleBgDarkColor UIColor 胶囊的深色下背景颜色
capsuleDividerLightColor UIColor 胶囊里浅色分割线颜色
capsuleDividerDarkColor UIColor 胶囊里的深色分割线颜色

我们的默认胶囊是这样:

那么,我们只需要这样设置,就可以变成圆角:

FATUIConfig *uiConfig = [[FATUIConfig alloc] init];
uiConfig.capsuleConfig.capsuleCornerRadius = 15.5;

效果如下:

# 2.5 FATNavHomeConfig配置项

配置名称 类型 配置描述
width CGFloat 返回首页按钮的宽度
height CGFloat 返回首页按钮的高度
leftMargin CGFloat 返回首页按钮的左侧距离屏幕左边框的距离
cornerRadius CGFloat 返回首页按钮的圆角半径
borderWidth CGFloat 返回首页按钮的边框宽度
lightImage UIImage 返回首页按钮的浅色按钮图片
darkImage UIImage 返回首页按钮的深色按钮图片
borderLightColor UIColor 返回首页按钮的浅色边框颜色
borderDarkColor UIColor 返回首页按钮的深色边框颜色
bgLightColor UIColor 返回首页按钮的浅色背景颜色
bgDarkColor UIColor 返回首页按钮的深色背景颜色

# 2.6 FATAuthViewConfig配置项

权限弹框视图的配置项。

配置名称 类型 配置描述
appletNameFont UIFont 小程序名称字体大小,默认字体为PingFangSC-Regular,默认大小16
appletNameLightColor UIColor 小程序名称的浅色颜色(明亮模式),默认#202020
appletNameDarkColor UIColor 小程序名称的深色颜色(暗黑模式),默认#D0D0D0
agreementLightImage UIImage 隐私协议入口icon(明亮模式),大小:22pt
agreementDarkImage UIImage 隐私协议入口icon(暗黑模式),大小:22pt
authorizeTitleFont UIFont 权限标题字体大小,默认字体为PingFangSC-Medium,默认大小17
authorizeTitleLightColor UIColor 权限标题的浅色颜色(明亮模式),默认#202020
authorizeTitleDarkColor UIColor 权限标题的深色颜色(暗黑模式),默认#D0D0D0
authorizeDescriptionFont UIFont 权限描述字体大小,默认字体为PingFangSC-Regular,默认大小14
authorizeDescriptionLightColor UIColor 权限描述的浅色颜色(明亮模式),默认#666666
authorizeDescriptionDarkColor UIColor 权限描述的深色颜色(暗黑模式),默认#8C8C8C
agreementTitleFont UIFont 协议标题字体大小,默认字体为PingFangSC-Regular,默认大小16
agreementTitleLightColor UIColor 协议标题的浅色颜色(明亮模式),默认#202020
agreementTitleDarkColor UIColor 协议标题的深色颜色(暗黑模式),默认#D0D0D0
agreementDescriptionFont UIColor 协议描述字体大小,默认字体为PingFangSC-Regular,默认大小14
agreementDescriptionLightColor UIColor 协议描述的浅色颜色(明亮模式),默认#202020
agreementDescriptionDarkColor UIColor 协议描述的深色颜色(暗黑模式),默认#D0D0D0
authorizeSelectedLightImage UIImage 权限选项选中时的icon(明亮模式),大小:22pt
authorizeSelectedDarkImage UIImage 权限选项选中时的icon(暗黑模式),大小:22pt
linkLightColor UIColor 链接的浅色颜色(明亮模式),默认#409EFF
linkDarkColor UIColor 链接的深色颜色(暗黑模式),默认#368CE4
allowButtonLightConfig FATAuthButtonConfig 同意按钮配置(明亮模式)
allowButtonDarkConfig FATAuthButtonConfig 同意按钮配置(暗黑模式)
rejectButtonLightConfig FATAuthButtonConfig 拒绝按钮配置(明亮模式)
rejectButtonDarkConfig FATAuthButtonConfig 拒绝按钮配置(暗黑模式)

# 2.7 FATAuthButtonConfig配置项

权限弹框授权按钮的配置项。

配置名称 类型 配置描述
cornerRadius CGFloat 按钮的圆角半径
normalBackgroundColor UIColor 按钮默认背景颜色
pressedBackgroundColor UIColor 按钮按下背景颜色
normalTextColor UIColor 按钮默认文字颜色
pressedTextColor UIColor 按钮按下文字颜色
normalBorderColor UIColor 按钮默认边框颜色
pressedBorderColor UIColor 按钮按下边框颜色

# 2.8 FATShareItemConfig配置项

配置名称 类型 配置描述
shareItemImage UIImage 右上角更多菜单的转发按钮icon,如果不传,会使用默认图标
shareItemString NSString 右上角更多菜单的转发按钮名称,如果不传,默认为转发。如进行配置,请注意进行多语言适配。

# 2.9 FATImageViewConfig配置项

更多面板中的logo配置项。

配置名称 类型 配置描述
borderCornerRadius CGFloat 圆角半径,默认值为4
borderWidth CGFloat 边框宽度,默认值为0.5
borderColor UIColor 边框颜色,默认#D8D8D8
backgroundColor UIColor 背景颜色,默认为白色
© FinClip with ❤ , Since 2017