# SDK Initialization

Note

Mini-Programs, Mini-Games, and H5 applications all use the same SDK, so the logic for initializing the SDK is identical.

Before using the Mini-Program API, you need to initialize the Mini-Program SDK. Only after the SDK is successfully initialized can you use the APIs provided by the SDK; otherwise, all API calls will fail.

# 1. Initialization

There are two APIs for initializing the SDK:

/// Initialize the SDK
/// @param config Configuration object
/// @param error Error returned when initialization fails
- (BOOL)initWithConfig:(FATConfig *)config error:(NSError **)error;

/// Initialize the SDK
/// @param config Configuration object
/// @param uiConfig UI configuration object
/// @param error Error returned when initialization fails
- (BOOL)initWithConfig:(FATConfig *)config uiConfig:(FATUIConfig *)uiConfig error:(NSError **)error;

Initialization example:

FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
storeConfig.sdkKey = @"Fill in your SDK Key here";
storeConfig.sdkSecret = @"Fill in your SDK secret here";
storeConfig.apiServer = @"Fill in your server address here"; // e.g., https://api.finclip.com;
FATConfig *config = [FATConfig configWithStoreConfigs:@[storeConfig]];
    
[[FATClient sharedClient] initWithConfig:config error:nil];

Note

  1. Starting from version 2.13.109, the FinClip Mini-Program SDK supports configuring multiple server information, allowing you to open Mini-Programs from server A as well as from server B. Therefore, we provide a method to configure multiple server information.
  2. configWithAppSecret:appKey: will be deprecated in the future. Please replace it with the configWithStoreConfigs method to construct FATConfig as soon as possible.
  3. Starting from version 2.34.1, it is no longer necessary to configure apiPrefix, as it is already configured internally in the interface.

The following is an example of initializing the SDK with multiple server configurations:

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. Configuration Items

The configuration items when initializing the SDK are divided into FATConfig and FATUIConfig. FATConfig mainly contains configuration items unrelated to the UI; while FATUIConfig mainly contains UI-related configuration items.

# 2.1 FATConfig Configuration Items

Configuration Name Type Configuration Description
currentUserId NSString Current user unique identifier. Mini-Program cache information will be stored in directories named after the userId.
memberUserId String Member identifier, used for opening trial and development versions. If not set, it will take the userId. Needs to match the user identifier in the management platform's trial/development member list.
channel NSString Channel identifier. If not filled, defaults to the project's BundleID. Used in plugins implementing getPhoneNumber and login.
phone NSString Phone number can also be a Token. Optional. Used in plugins implementing getPhoneNumber.
encryptUserId BOOL (Backend interface) Whether to encrypt the userId for transmission. Ensure the backend service is upgraded to version 1.4.1 or above, otherwise encryption will cause interface request failures. Default is false.
productIdentification NSString Product identifier. Configuration will change the FinClip and other identifiers in folders and UserAgent to the configured value.
disableAuthorize BOOL Whether to disable the SDK from triggering permission requests. Default is NO. If set to YES, the SDK will not actively request permissions when using permission-related APIs.
appletAutoAuthorize BOOL Whether to allow the SDK to automatically grant Mini-Program permissions. Default is NO. If set to YES, the first time a permission is triggered in the Mini-Program, the permission popup will not be displayed.
disableGetSuperviseInfo BOOL Whether to disable the SDK's supervision interface API. Default is NO. If set to YES, the SDK disables the supervision interface API (getSuperviseInfo).
appletIntervalUpdateLimit NSInteger Number of Mini-Programs automatically checked for updates in the background. Valid range: 0~50. 0 means no update check; if not set, default is 3.
apmExtension NSDictionary Extension information for APM statistics.
startCrashProtection BOOL Whether to enable Crash protection. Includes UnrecognizedSelector, KVO, Notification, Timer, Container (array out-of-bounds, dictionary inserting nil, etc.), String (out-of-bounds, nil, etc.).
enableApmDataCompression BOOL Whether to compress data when reporting APM data.
appletDebugMode FATAppletDebugMode Mini-Program debug mode setting. Default is default, non-release versions can enable vConsole via API or more menu; enable forces all Mini-Programs to enable vConsole for debugging during development; forbidden forces all versions to disable vConsole; forbiddenRelease only forces all release versions to disable vConsole, other versions same as default.
webViewInspectable boolean Whether to enable WebView debugging (required for debugging on iOS 16.4 and later versions). Default is NO.
enableWatermark BOOL Whether to display watermark. Default is NO.
watermarkPriority FATConfigPriority Watermark display priority setting. Default is global configuration priority.
enableScreenShot BOOL Whether to allow screenshots. Default is YES.
screenShotPriority FATConfigPriority Screenshot permission priority setting. Default is global configuration priority.
baseLoadingViewClass NSString Class name for the custom loading view.
baseLoadFailedViewClass NSString Class name for the custom failure view.
header NSDictionary Header for network requests in the Mini-Program.
headerPriority FATConfigPriority Header priority setting.
enableH5AjaxHook BOOL Whether to enable the hook function for H5 pages loaded in the Mini-Program. Optional. See comments in the API for details.
h5AjaxHookRequestKey NSString After enabling enableH5AjaxHook, request requests will be hooked. You can set the requestKey.
pageCountLimit NSUInteger Maximum limit for the page stack in the Mini-Program. Default value is 0, meaning no limit.
schemes NSArray<NSString> Custom scheme array, e.g., @[@"tel",@"music"]. The SDK internally supports schemes like WeChat, Alipay, FinClip App, and tel by default.
language FATPreferredLanguage Language type for the SDK. Currently only Chinese and English are supported. Default is Chinese. Unsupported types will also display as Chinese.
customLanguagePath NSString Relative path for custom SDK language. Priority higher than the language property. (Only effective on iOS platform.)
pickerRegionPath NSString File path can be a path in the application's sandbox directory or a filename included in the application Bundle. If this property is empty or not set, the picker component will load the default region data.
backgroundFetchPeriod NSInteger Time interval (in hours) for periodic updates. Setting to 0 will not initiate periodic update requests and preload requests. Acceptable range is 3-12 hours. Default is 12 hours.
authDescStrategy FATAuthDescStrategy FATAuthDescStrategyNone: Default case, if detailed description is not configured in the management console, it is not displayed; FATAuthDescStrategyShowDefault: If detailed description is not configured, the default detailed description is displayed; FATAuthDescStrategyForbidden: If detailed description is not configured, the API call fails.

# 2.2 FATStoreConfig Configuration Items

Configuration Name Type Required Description
sdkKey NSString Yes sdkKey generated when creating the application.
sdkSecret NSString Yes sdkSecret generated when creating the application.
apiServer NSString Yes Server address, the backend address deployed by the customer.
apmServer NSString No Server address for APM event reporting. If not set, apiServer is used.
cryptType FATApiCryptType No Enumeration value, signature generation method for communication between the SDK and the management platform interface. Default is md5, can also be set to SM (SM cryptographic algorithm).
fingerprint NSString No SDK fingerprint. Must be provided in the certificate-linked environment, otherwise interface access will fail.
encryptServerData BOOL No Default is NO. Currently can only be set to NO. Setting to YES will cause interface access failure.
enablePreloadFramework BOOL Yes Default is YES. Whether to pre-download the Base Library. If set to NO, pre-downloading the Base Library is disabled during SDK initialization.

# 2.3 FATUIConfig Configuration Items

Configuration Name Type Configuration Description
navigationTitleTextAttributes NSDictionary<NSAttributedStringKey, id> Navigation bar title style. Currently only supports font configuration.
navigationBarHeight CGFloat Navigation bar height. Default value is 44.
navigationBarTitleLightColor UIColor Navigation bar light title color, used in Dark Mode.
navigationBarTitleDarkColor UIColor Navigation bar dark title color, used in Light Mode.
navigationBarBackBtnLightColor UIColor Navigation bar light back button color, used in Dark Mode.
navigationBarBackBtnDarkColor UIColor Navigation bar dark back button color, used in Light Mode.
hideLoadingAndHomeBackButtonWhenPushStyle BOOL When opening a Mini-Program in Push style, supports hiding the loading and home back buttons. Default is NO.
capsuleConfig FATCapsuleConfig Capsule button style configuration in the upper right corner. Specific parameters see FATCapsuleConfig table.
navHomeConfig FATNavHomeConfig Back to home button style configuration. Specific parameters see FATNavHomeConfig table.
authViewConfig FATAuthViewConfig Permission popup view style configuration. Specific parameters see FATAuthViewConfig table.
shareItemConfig FATShareItemConfig Forward button configuration. Specific parameters see FATShareItemConfig table.
navigationBackImage UIImage Navigation bar back button image object.
progressBarColor UIColor Progress bar color when the WebView component in the Mini-Program loads a link.
hideWebViewProgressBar BOOL Whether to hide the progress bar when the WebView component in the Mini-Program loads a link.
moreMenuStyle FATMoreViewStyle Style of the menu view popped up by the more button in the capsule. FATMoreViewStyleDefault, FATMoreViewStyleNormal, FATMoreViewStylePage (menu displayed in pages, added in 2.43.9).
hideBackToHome BOOL Whether to hide the back to home button in the navigation bar.
hideBackToHomePriority FATConfigPriority Priority setting for hiding the back to home button.
hideShareAppletMenu BOOL Whether to hide the share button in the Mini-Program more menu. Default is YES.
hideForwardMenu BOOL Whether to hide the forward button in the more menu.
hideClearCacheMenu BOOL Whether to hide the [Clear Cache] menu item in the more menu. Default is NO.
hideRefreshMenu BOOL Whether to hide the re-enter button in the more menu.
hideSettingMenu BOOL Whether to hide the settings button in the Mini-Program more menu.
hideDebugMenu BOOL Whether to hide the enable/disable debug button in the more menu.
hideFavoriteMenu BOOL Whether to hide the favorite/unfavorite button in the more menu. Default is YES.
hideAddToDesktopMenu BOOL Whether to hide the add to desktop button in the more menu. Default is YES.
hideFeedbackMenu BOOL Whether to hide the complaint feedback button in the more menu.
autoAdaptDarkMode boolean Whether to automatically adapt to system Dark Mode (deprecated in version 2.44.5, use the new themeStyle property).
themeStyle FATUserInterfaceStyle Theme mode.
appendingCustomUserAgent NSString Content you need to add to the userAgent.
appletText NSString Default is "Mini-Program", the name you want to replace for display. For example, if set to "Lightweight Application", all places showing "Mini-Program" will change to "Lightweight Application".
transtionStyle FATTranstionStyle Default animation method when opening a Mini-Program. If not set, defaults to FATTranstionStyleUp. Can be set for the following scenarios: 1. Opening a Mini-Program via scheme; 2. Opening a Mini-Program via universal link; 3. Animation method for navigateToMiniprogram.
hideTransitionCloseButton BOOL Whether to hide the close button on the transition page. Default is NO.
disableSlideCloseAppletGesture BOOL Whether to disable the swipe gesture to close the Mini-Program. Default is NO.
commonUISupportOrientaion FATInterfaceOrientation Orientation of public UI interfaces. Default is fixed portrait.
useNativeLiveComponent BOOL Whether to use the built-in live component. Default is NO. When set to YES, the FATAppletLive Extension SDK is also required.
moreMenuLogoConfig FATImageViewConfig Logo configuration for the popped-up menu view. Specific parameters see FATImageViewConfig table.

# 2.4 FATCapsuleConfig Configuration Items

Configuration Name Type Configuration Description
hideCapsuleCloseButton BOOL Hide the close button in the Mini-Program capsule.
capsuleWidth CGFloat Capsule width.
capsuleHeight CGFloat Capsule height.
capsuleRightMargin CGFloat Distance from the capsule's right border to the screen's right border.
capsuleCornerRadius CGFloat Capsule corner radius.
capsuleBorderWidth CGFloat Capsule border width.
moreBtnWidth CGFloat More button width in the capsule.
moreBtnLeftMargin CGFloat Left margin of the more button.
closeBtnWidth CGFloat Close button width in the capsule.
closeBtnLeftMargin CGFloat Left margin of the close button in the capsule.
locationLightImage UIImage Light location button image object in the capsule. If not provided, the default icon is used.
locationDarkImage UIImage Dark location button image object in the capsule. If not provided, the default icon is used.
microphoneLightImage UIImage Light microphone button image object in the capsule. If not provided, the default icon is used.
microphoneDarkImage UIImage Dark microphone button image object in the capsule. If not provided, the default icon is used.
moreLightImage UIImage Light more button image for the capsule.
moreDarkImage UIImage Dark more button image for the capsule.
closeLightImage UIImage Light close button image in the capsule.
closeDarkImage UIImage Dark close button image in the capsule.
capsuleBorderLightColor UIColor Light border color of the capsule.
capsuleBorderDarkColor UIColor Dark border color of the capsule.
capsuleBgLightColor UIColor Light background color of the capsule.
capsuleBgDarkColor UIColor Dark background color of the capsule.
capsuleDividerLightColor UIColor Light divider line color in the capsule.
capsuleDividerDarkColor UIColor Dark divider line color in the capsule.
redDotBtnWidth CGFloat Red dot button width in the capsule. Default value is 6.
redDotBtnHeight CGFloat Red dot button height in the capsule. Default value is 6.
redDotBtnRightMargin CGFloat Right margin of the red dot button in the capsule. Default value is 6.
redDotBtnTopMargin CGFloat Top margin of the red dot button in the capsule. Default value is 3.
redDotBtnDarkImage UIImage Dark image object for the red dot button in the capsule. If not provided, the default icon is used (Light Mode).
redDotBtnLightImage UIImage Light image object for the red dot button in the capsule. If not provided, the default icon is used (Dark Mode).

Our default capsule looks like this:

Then, we only need to set it like this to make it rounded:

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

The effect is as follows:

# 2.5 FATNavHomeConfig Configuration Items

Configuration Name Type Configuration Description
width CGFloat Back to home button width.
height CGFloat Back to home button height.
leftMargin CGFloat Distance from the left side of the back to home button to the left border of the screen.
cornerRadius CGFloat Back to home button corner radius.
borderWidth CGFloat Back to home button border width.
lightImage UIImage Light button image for the back to home button.
darkImage UIImage Dark button image for the back to home button.
borderLightColor UIColor Light border color of the back to home button.
borderDarkColor UIColor Dark border color of the back to home button.
bgLightColor UIColor Light background color of the back to home button.
bgDarkColor UIColor Dark background color of the back to home button.

# 2.6 FATAuthViewConfig Configuration Items

Configuration items for the permission popup view.

Configuration Name Type Configuration Description
appletNameFont UIFont Mini-Program name font size. Default font is PingFangSC-Regular, default size 16.
appletNameLightColor UIColor Light color of the Mini-Program name (Light Mode). Default #202020.
appletNameDarkColor UIColor Dark color of the Mini-Program name (Dark Mode). Default #D0D0D0.
agreementLightImage UIImage Privacy agreement entry icon (Light Mode). Size: 22pt.
agreementDarkImage UIImage Privacy agreement entry icon (Dark Mode). Size: 22pt.
authorizeTitleFont UIFont Permission title font size. Default font is PingFangSC-Medium, default size 17.
authorizeTitleLightColor UIColor Light color of the permission title (Light Mode). Default #202020.
authorizeTitleDarkColor UIColor Dark color of the permission title (Dark Mode). Default #D0D0D0.
authorizeDescriptionFont UIFont Permission description font size. Default font is PingFangSC-Regular, default size 14.
authorizeDescriptionLightColor UIColor Light color of the permission description (Light Mode). Default #666666.
authorizeDescriptionDarkColor UIColor Dark color of the permission description (Dark Mode). Default #8C8C8C.
agreementTitleFont UIFont Agreement title font size. Default font is PingFangSC-Regular, default size 16.
agreementTitleLightColor UIColor Light color of the agreement title (Light Mode). Default #202020.
agreementTitleDarkColor UIColor Dark color of the agreement title (Dark Mode). Default #D0D0D0.
agreementDescriptionFont UIFont Agreement description font size. Default font is PingFangSC-Regular, default size 14.
agreementDescriptionLightColor UIColor Light color of the agreement description (Light Mode). Default #202020.
agreementDescriptionDarkColor UIColor Dark color of the agreement description (Dark Mode). Default #D0D0D0.
authorizeSelectedLightImage UIImage Icon when the permission option is selected (Light Mode). Size: 22pt.
authorizeSelectedDarkImage UIImage Icon when the permission option is selected (Dark Mode). Size: 22pt.
linkLightColor UIColor Light color of the link (Light Mode). Default #409EFF.
linkDarkColor UIColor Dark color of the link (Dark Mode). Default #368CE4.
allowButtonLightConfig FATAuthButtonConfig Allow button configuration (Light Mode).
allowButtonDarkConfig FATAuthButtonConfig Allow button configuration (Dark Mode).
rejectButtonLightConfig FATAuthButtonConfig Reject button configuration (Light Mode).
rejectButtonDarkConfig FATAuthButtonConfig Reject button configuration (Dark Mode).

# 2.7 FATAuthButtonConfig Configuration Items

Configuration items for the authorization buttons in the permission popup.

Configuration Name Type Configuration Description
cornerRadius CGFloat Button corner radius.
normalBackgroundColor UIColor Button default background color.
pressedBackgroundColor UIColor Button pressed background color.
normalTextColor UIColor Button default text color.
pressedTextColor UIColor Button pressed text color.
normalBorderColor UIColor Button default border color.
pressedBorderColor UIColor Button pressed border color.

# 2.8 FATShareItemConfig Configuration Items

Configuration Name Type Configuration Description
shareItemImage UIImage Forward button icon in the upper right corner more menu. If not provided, the default icon is used.
shareItemString NSString Forward button name in the upper right corner more menu. If not provided, defaults to "Forward". If configured, please note to adapt for multiple languages.

# 2.9 FATImageViewConfig Configuration Items

Logo configuration items in the more panel.

Configuration Name Type Configuration Description
borderCornerRadius CGFloat Border corner radius. Default value is 20.
borderWidth CGFloat Border width. Default value is 0.5.
borderColor UIColor Border color. Default is #D8D8D8.
backgroundColor UIColor Background color. Default is white.
© FinClip with ❤ , Since 2017