# 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
- 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.
configWithAppSecret:appKey:will be deprecated in the future. Please replace it with theconfigWithStoreConfigsmethod to construct FATConfig as soon as possible.- 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. |