# SDK Initialization
# 1. Initialization
TIP
Before using the Mini-Program API, you need to initialize the Mini-Program SDK. Only after successful initialization can you use the APIs provided by the SDK; otherwise, API calls will fail.
# API
/**
* Initialize the FinAppClient instance.
* If the instance already exists, update the context.
* @param finAppConfig - Configuration for FinAppClient.
* @param entryContext - UIAbilityContext.
* @param entryInfo - The name of the Ability that the Mini-Program needs to open.
* @param startMode - Configuration item for IFinAppStartMode startup mode.
* @returns A singleton instance of FinAppClient; returns null if all server configuration validations fail.
*/
FinAppClient.init(finAppConfig: IFinAppConfig.IFinAppConfig, entryContext: common.UIAbilityContext,entryInfo: string, startMode?: IFinAppStartMode): FinAppClient | null
# 2. Configuration Items
The following types are all under the IFinAppConfig namespace, for example, IFinAppConfig.IFinAppConfig, IFinAppConfig.IStoreConfig.
# 2.1 IFinAppConfig Configuration Items
| Configuration Name | Type | Required | Description |
|---|---|---|---|
| finStoreConfigs | Array<IStoreConfig> | Yes | Collection of Mini-Program server configuration information |
| currentUserId | string | No | Unique identifier for the current user |
| appletDebugMode | 'default' | 'enable' | 'forbidden' | 'forbiddenRelease' | No | Mini-Program debug mode setting. Default is default; enable forces vConsole on for all Mini-Programs; forbidden forces vConsole off for all versions; forbiddenRelease forces vConsole off for the release version. |
| productIdentification | string | No | Product identifier; configuration will change identifiers like FinClip in folders and UserAgent to the configured value |
| uiConfig | IUIConfig | No | UI-related configuration items |
| finKey | string | No | SDK internal configuration key. |
| verifyHandler | IVerifyHandler | No | External verification handler function. |
| pageCountLimit | number | No | Maximum limit for the page stack in a Mini-Program. Default value is 0, meaning no limit. |
| memberUserId | string | No | Current member identifier. |
| phone | string | No | Current user's phone number. |
| appletAutoAuthorize | boolean | No | Whether a dialog box will pop up for user confirmation when applying for permissions. Default is false. If set to true, permissions are automatically requested from the SDK without showing a dialog box. |
| isApp | boolean | No | Whether to run in App mode. |
| pickerRegionPath | string | No | File path for the custom region picker, must be placed in the rawfile folder |
| logLevel | 'none' | 'info' | 'debug' | 'warn' | 'error' | No | Log level. Default is 'none', meaning no logs are output. |
| enableNativeComponent | boolean | string[] | No | Whether to enable same-layer rendering of native components. Default is true. Array supports input, textarea, video, camera, picker, webview. |
| channel | string | No | Channel identifier; if not filled, defaults to the project's BundleID. Used in plugin login implementation. |
| schemes | string[] | No | Custom scheme array. |
| header | Record<string, string> | No | Header for network requests in Mini-Programs |
| ignoreWebviewCertAuth | boolean | No | Whether to ignore SSL certificate verification. Default is false; when set to true, the Mini-Program's web-view component can load untrusted https links and http links. |
| authDescStrategy | IFinAppConfig.EAuthDescStrategy | No | Mini-Program permission description configuration strategy. None: Displays configured content when the Mini-Program has configuration; ShowDefault: Displays built-in permission information when not configured; Forbidden: Does not allow applying for permissions without configured descriptions. |
| enableScreenShot | boolean | No | Whether to allow screenshots and screen recording, default is true |
| screenShotPriority | IFinAppConfig.EFinAppConfigPriority | No | Priority for screenshot/screen recording configuration items, default is IFinAppConfig.EFinAppConfigPriority.Global. |
| enableWatermark | boolean | No | Whether to display a watermark, default is false |
| watermarkPriority | IFinAppConfig.EFinAppConfigPriority | No | Priority setting for displaying watermark, default is IFinAppConfig.EFinAppConfigPriority.Global. |
| enableWebviewDebug | boolean | No | Whether to enable webview debugging, default is false |
| language | string | No | Language type for the SDK. Currently only supports Chinese and English. Default is Chinese; unsupported types will also display as Chinese. |
| backgroundFetchPeriod | number | No | Time interval for periodic updates (in hours). Setting it to 0 will not initiate periodic updates or data pre-fetch requests. The accepted setting range is 3-12 hours. |
# 2.2 IStoreConfig Configuration Items
| Configuration Name | Type | Required | Description |
|---|---|---|---|
| sdkKey | string | Yes | sdkKey generated when creating the application |
| sdkSecret | string | Yes | sdkKey generated when creating the application |
| apiServer | string | Yes | Server address, the backend address deployed by the customer |
| apmServer | string | No | Server address for APM event reporting; uses apiServer if not set |
| cryptType | "sm" | "md5" | No | Encryption type for network interfaces. Default is "sm" (national encryption), can also be set to "md5" |
| requestTimeout | number | No | Unit is ms, default is 60s. Request timeout duration |
| encryptUserId | boolean | No | (Backend interface) Whether to encrypt and transmit userId. Ensure the backend service is upgraded to version 1.4.1 or above; otherwise, encryption will cause interface request failures. Default is false |
| enablePreloadFramework | boolean | No | Default is true. Whether to pre-download the Base Library; if set to false, the Base Library will not be pre-downloaded when initializing the SDK |
# 2.3 IUIConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| capsuleConfig | ICapsuleConfig | No | Style configuration for the capsule button in the top right corner; see ICapsuleConfig table for specific parameters |
| navHomeConfig | INavHomeConfig | No | Style configuration for the return-to-home button; see INavHomeConfig table for specific parameters |
| navBackConfig | INavBackConfig | No | Style configuration for the back button; see INavBackConfig table for specific parameters |
| navTitleConfig | INavTitleConfig | No | Navigation bar title style; see INavTitleConfig table for specific parameters |
| forwardConfig | IForwardConfig | No | Style configuration for the forward button; see IForwardConfig table for specific parameters |
| imageViewConfig | IImageViewConfig | No | Logo-related configuration for the more button interface; see IImageViewConfig table for details |
| webviewComponentProgressBarStyle | IWebviewComponentProgressBarConfig | No | Style configuration for the webview loading progress bar; see IWebviewComponentProgressBarConfig table for specific parameters |
| authViewConfig | IAuthViewConfig | No | Style configuration for the authorization dialog box; see IAuthViewConfig table for specific parameters |
| navigationBarHeight | number | No | Navigation bar height, default value is 44 |
| navigationBarTitleLightColor | string | No | Light color for the navigation bar title. |
| navigationBarTitleDarkColor | string | No | Dark color for the navigation bar title. |
| hideBackToHome | boolean | No | Whether to hide the return-to-home button in the navigation bar, default is false |
| hideShareAppletMenu | boolean | No | Whether to hide the share button in the Mini-Program more menu, default is true |
| hideAddToDesktopMenu | boolean | No | Whether to hide the add-to-desktop button in the Mini-Program more menu, default is true |
| hideForwardMenu | boolean | No | Whether to hide the forward button in the more menu, default is false |
| hideRefreshMenu | boolean | No | Whether to hide the re-enter button in the more menu, default is false |
| hideSettingMenu | boolean | No | Whether to hide the settings button in the Mini-Program more menu, default is false |
| hideDebugMenu | boolean | No | Whether to hide the open/close debug button in the more menu, default is false |
| hideFavoriteMenu | boolean | No | Whether to hide the favorite/unfavorite button in the more menu, default is true |
| hideFeedbackMenu | boolean | No | Whether to hide the feedback/complaint button in the more menu, default is false |
| hideClearCacheMenu | boolean | No | Whether to hide the clear cache button in the more menu, default is false |
| appletText | string | No | Mini-Program copy text, default is "Mini-Program"; you can set it to "Quick App", "Lightweight Application" |
| themeStyle | IFinApplet.IThemeStyle | No | Theme mode, default is Light |
| appendingCustomUserAgent | string | No | Content to append to the userAgent. |
| navigationBackImage | INavigationBackImage | No | Image configuration for the navigation bar back button. |
| isAlwaysShowBackInDefaultNavigationBar | boolean | No | Whether to always show the back button when the navigation bar is the default navigation bar, default value is false. |
| moreMenuStyle | 'default' | 'normal' | 'page' | No | Style of the more menu, default value is 'default'. |
| mapAlphaOnBackground | boolean | No | Whether the alpha value in the Hex color for the map is at the end, e.g., true means #RRGGBBAA, false means #AARRGGBB. |
IFinApplet.IThemeStyle
| Name | Description |
|---|---|
| Auto | Follow the application |
| Light | Light mode |
| Dark | Dark mode |
# 2.4 ICapsuleConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| hideCapsuleCloseButton | boolean | No | Hide the close button in the Mini-Program capsule |
| hideCapsuleMoreButton | boolean | No | Hide the more button in the Mini-Program capsule |
| hideCapsuleMaxButton | boolean | No | Whether to hide the maximize button in the capsule. |
| hideCapsuleMinButton | boolean | No | Whether to hide the minimize button in the capsule. |
| hideTransitionCloseButton | boolean | No | Whether to hide the close button on the Mini-Program loading page |
| capsuleWidth | number | No | Width of the capsule |
| capsuleHeight | number | No | Height of the capsule |
| capsuleRightMargin | number | No | Distance from the right edge of the capsule to the right edge of the screen |
| capsuleCornerRadius | number | No | Corner radius of the capsule |
| capsuleBorderWidth | number | No | Border width of the capsule |
| moreBtnWidth | number | No | Width of the more button in the capsule |
| moreBtnLeftMargin | number | No | Left margin of the more button |
| closeBtnWidth | number | No | Width of the close button in the capsule |
| closeBtnLeftMargin | number | No | Left margin of the close button in the capsule |
| maximizeBtnWidth | number | No | Width of the maximize button in the capsule. |
| maximizeBtnLeftMargin | number | No | Left margin of the maximize button in the capsule. |
| minimizeBtnWidth | number | No | Width of the minimize button in the capsule. |
| minimizeBtnLeftMargin | number | No | Left margin of the minimize button in the capsule. |
| moreLightImage | ResourceStr | No | Light mode image for the more button in the capsule. |
| moreDarkImage | ResourceStr | No | Dark mode image for the more button in the capsule. |
| closeLightImage | ResourceStr | No | Light mode image for the close button in the capsule. |
| closeDarkImage | ResourceStr | No | Dark mode image for the close button in the capsule. |
| maximizeLightImage | ResourceStr | No | Light mode image for the maximize button in the capsule. |
| maximizeDarkImage | ResourceStr | No | Dark mode image for the maximize button in the capsule. |
| normalizeLightImage | ResourceStr | No | Light mode image for the restore button in the capsule. |
| normalizeDarkImage | ResourceStr | No | Dark mode image for the restore button in the capsule. |
| minimizeLightImage | ResourceStr | No | Light mode image for the minimize button in the capsule. |
| minimizeDarkImage | ResourceStr | No | Dark mode image for the minimize button in the capsule. |
| capsuleBorderLightColor | string | No | Light mode border color of the capsule |
| capsuleBorderDarkColor | string | No | Dark mode border color of the capsule |
| capsuleBgLightColor | string | No | Light mode background color of the capsule |
| capsuleBgDarkColor | string | No | Dark mode background color of the capsule |
| capsuleDividerLightColor | string | No | Light mode divider line color in the capsule |
| capsuleDividerDarkColor | string | No | Dark mode divider line color in the capsule |
# 2.5 INavHomeConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| width | number | No | Width of the return-to-home button |
| height | number | No | Height of the return-to-home button |
| leftMargin | number | No | Distance from the left side of the return-to-home button to the left edge of the screen |
| cornerRadius | number | No | Corner radius of the return-to-home button |
| borderWidth | number | No | Border width of the return-to-home button |
| borderLightColor | string | No | Light mode border color of the return-to-home button |
| borderDarkColor | string | No | Dark mode border color of the return-to-home button |
| bgLightColor | string | No | Light mode background color of the return-to-home button |
| bgDarkColor | string | No | Dark mode background color of the return-to-home button |
| lightImage | ResourceStr | No | Light mode image resource address for the return-to-home button |
| darkImage | ResourceStr | No | Dark mode image resource address for the return-to-home button |
# 2.6 INavBackConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| width | number | No | Width of the back button |
| height | number | No | Height of the back button |
| leftMargin | number | No | Distance from the left side of the back button to the left edge of the screen |
| lightImage | ResourceStr | No | Light mode image resource address for the back button |
| darkImage | ResourceStr | No | Dark mode image resource address for the back button |
# 2.6 INavTitleConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| fontSize | number | No | Font size of the navigation bar title |
| fontWeight | number | string | No | Font weight of the navigation bar title |
| textAlign | string | No | Text alignment of the navigation bar title, only supports left and center. |
# 2.7 IImageViewConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| borderCornerRadius | number | No | Image border corner radius, default: 20 |
| borderWidth | number | No | Image border width, default: 0.5 |
| borderColor | string | No | Image border color, default: #D8D8D8 |
| backgroundColor | string | No | Image background color, default: #FFF |
# 2.8 IForwardConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| label | string | Yes | Text for the forward button |
| icon | ResourceStr | Yes | Icon resource address for the forward button |
| disableIcon | ResourceStr | No | Disabled icon resource address for the forward button |
| darkIcon | ResourceStr | No | Dark mode icon resource address for the forward button |
| disableDarkIcon | ResourceStr | No | Disabled dark mode icon resource address for the forward button |
# 2.9 IWebviewComponentProgressBarConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| enable | boolean | No | Whether to enable the loading progress bar |
| width | number | No | Width of the loading progress bar |
| color | string | No | Background color of the loading progress bar |
| activeColor | string | No | Progress color of the loading progress bar |
# 2.10 IAuthViewConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| appletNameTextSize | number | No | Font size of the Mini-Program name, default 16 |
| appletNameLightColor | ResourceColor | No | Light color of the Mini-Program name, default #222222 |
| appletNameDarkColor | ResourceColor | No | Dark color of the Mini-Program name, default #d0d0d0 |
| authorizeTitleTextSize | number | No | Font size of the permission title, default 17 |
| authorizeTitleLightColor | ResourceColor | No | Light color of the permission title, default #222222 |
| authorizeTitleDarkColor | ResourceColor | No | Dark color of the permission title, default #d0d0d0 |
| authorizeDescriptionTextSize | number | No | Font size of the permission description, default 14 |
| authorizeDescriptionLightColor | ResourceColor | No | Light color of the permission description, default #666666 |
| authorizeDescriptionDarkColor | ResourceColor | No | Dark color of the permission description, default #5c5c5c |
| authorizeSelectedLightImage | ResourceStr | No | Light mode icon when the protocol option is selected, size: 22x22 |
| authorizeSelectedDarkImage | ResourceStr | No | Dark mode icon when the protocol option is selected, size: 22x22 |
| agreementLightImage | ResourceStr | No | Light mode icon for the privacy agreement entry, size: 22x22 |
| agreementDarkImage | ResourceStr | No | Dark mode icon for the privacy agreement entry, size: 22x22 |
| agreementTitleTextSize | number | No | Font size of the agreement title, default 16 |
| agreementTitleLightColor | ResourceColor | No | Light color of the agreement title, default #222222 |
| agreementTitleDarkColor | ResourceColor | No | Dark color of the agreement title, default #d0d0d0 |
| agreementDescriptionTextSize | number | No | Font size of the agreement description, default 14 |
| agreementDescriptionLightColor | ResourceColor | No | Light color of the agreement description, default #222222 |
| agreementDescriptionDarkColor | ResourceColor | No | Dark color of the agreement description, default #d0d0d0 |
| linkLightColor | ResourceColor | No | Light color of the link, default #4285f4 |
| linkDarkColor | ResourceColor | No | Dark color of the link, default #4285f4 |
| allowButtonLightConfig | IAuthButtonConfig | No | Light mode configuration for the allow button |
| allowButtonDarkConfig | IAuthButtonConfig | No | Dark mode configuration for the allow button |
| rejectButtonLightConfig | IAuthButtonConfig | No | Light mode configuration for the reject button |
| rejectButtonDarkConfig | IAuthButtonConfig | No | Dark mode configuration for the reject button |
# 2.11 IAuthButtonConfig Configuration Items
| Configuration Name | Type | Required | Configuration Description |
|---|---|---|---|
| cornerRadius | number | Yes | Corner radius of the button |
| normalBackgroundColor | ResourceColor | Yes | Default background color of the button |
| pressedBackgroundColor | ResourceColor | Yes | Background color of the button when pressed |
| normalBorderColor | ResourceColor | Yes | Default border color of the button |
| pressedBorderColor | ResourceColor | Yes | Border color of the button when pressed |
| normalTextColor | ResourceColor | Yes | Default text color of the button |
| pressedTextColor | ResourceColor | Yes | Text color of the button when pressed |