# 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 first. Only after successful initialization can you use the APIs provided by the SDK; otherwise, API calls will fail.
# 1. Initialization
# API
/**
* Initialize the Mini-Program SDK
*
* @param application [android.app.Application] instance
* @param finAppConfig [FinAppConfig] instance, configuration information for the Mini-Program framework
* @param finCallback Initialization status callback interface
*/
fun init(application: Application, finAppConfig: FinAppConfig, finCallback: FinCallback<Any?>?)
# Usage Example
Note
- Starting from version
2.13.102, the FinClip Mini-Program SDK supports configuring multiple server information, allowing simultaneous access to Mini-Programs on multiple servers. Therefore, we provide a way to configure multiple server information. - The method of initializing a single server using
Builder().setSdkKeyandBuilder().setSdkSecretmay be disabled in the future. Please prioritize using the multi-server initialization method.
# 2. Configuration Items
# FinAppConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| finStoreConfigs | List<FinStoreConfig> | Collection of Mini-Program server configuration information |
| userId | String | Unique identifier for the current user. Mini-Program cache information will be stored in directories named with userId. If you need to modify userId in subsequent logic, you can directly use FinAppClient.INSTANCE.getFinAppConfig().setUserId("newUserId"). |
| memberUserId | String | Member identifier, used to open experience or development versions. If not set, it will take userId, and must match the user identifier in the management platform's experience and development member list. |
| channel | NSString | Channel identifier. If not filled, it defaults to the project's AppliationId. It will be used in implementing getPhoneNumber and login in Mini-Program plugins. |
| phone | NSString | Phone number, or it could be a Token. Optional. It will be used in implementing getPhoneNumber in Mini-Program plugins. |
| encryptUserId | boolean | (Backend API) Whether to encrypt the transmission of userId. Ensure that the backend service is upgraded to version 1.4.1 or above; otherwise, encryption will cause API request failures. Default is false. |
| productIdentification | String | Product identifier. Configuring this will change identifiers like FinClip in folders and UserAgent to the configured value. After setting, you need to add the fin_applet_custom_provider_paths.xml file. For configuration instructions, see the following notes. |
| isDebugMode | boolean | Whether the application is currently in Debug mode. |
| isEnableLog | boolean | Whether to enable logging. |
| isEnableXLogConsole | boolean | Whether to enable XLog console logs. If false, logs will only be persisted and not displayed in the console. |
| apmExtendInfo | Map<String, Object> | Extended information for APM statistics. |
| disableRequestPermissions | boolean | Whether to disable the SDK from triggering permission requests. Default is false. If set to true, APIs within the SDK that use permissions will not actively request permissions. |
| needToRemoveCookiesDomains | List<String> | List of domain names whose cookies need to be removed when initializing the SDK. |
| disableTbs | boolean | Whether to disable the TBS SDK. |
| customWebViewUserAgent | String | Content to be added to the UserAgent. |
| webViewMixedContentMode | int | WebView mixed content loading mode. Options: -1, do not set WebView mixed content loading mode. 0, allow WebView to load mixed content. 1, disallow WebView from loading mixed content. 2, allow WebView to load some mixed content. Some unsafe content may be allowed to be loaded by secure sources, while other unsafe content will be blocked. The types of content allowed or blocked vary with WebView versions and are not explicitly defined. Suitable for scenarios where WebView content cannot be controlled but the application needs to run securely. For maximum security, it is recommended to set it to disallow loading mixed content. |
| allowWebViewCrossOrigin | boolean | Whether to allow WebView Cross-Origin Resource Sharing. Default is true. When enabled, some scenarios may encounter issues due to handling numerous long-unresponsive image resource requests, causing the WebView to enter a waiting state, leading to blank screens or lagging in Mini-Program pages. If such issues occur, try disabling this configuration. |
| appletIntervalUpdateLimit | int | Number of Mini-Programs automatically checked for updates in the background. Range: 0~50. 0 means no checks for updates; default is 3 if not set. |
| maxRunningApplet | int | Maximum number of Mini-Programs that can run simultaneously. Default is 5. |
| foregroundServiceConfig | ForegroundServiceConfig | Whether to enable the foreground service of the Host-App when running Mini-Programs. Enabling prevents the app process from being killed by the system. |
| bindAppletWithMainProcess | boolean | Whether the Mini-Program process is bound to the app main process. If set to true, when the main process is killed, the Mini-Program process will also close (Note: On some devices, clearing the main process in the task list does not actually kill the main process, so the Mini-Program process cannot be cleared simultaneously). |
| killAppletProcessNotice | String | Prompt text shown when closing Mini-Programs after the main app process is killed. |
| appletText | String | Mini-Program text. Default is "Mini-Program". You can set it to "Quick App" or "Lightweight Application". |
| enableApmDataCompression | boolean | Whether to compress data during APM data reporting. |
| disableGetSuperviseInfo | boolean | Whether to disable the SDK's regulatory interface API. Default is false. If set to true, the SDK disables the regulatory interface API (getSuperviseInfo). |
| appletAutoAuthorize | boolean | Whether to allow the SDK to automatically grant Mini-Program permissions. Default is false. If set to true, the permission popup will not be shown when permissions are triggered for the first time in the Mini-Program. |
| appletDebugMode | AppletDebugMode | Whether to enable vconsole debugging for Mini-Programs. |
| pageCountLimit | int | Maximum limit of page stack count in Mini-Programs. Default is 0, meaning no limit. |
| minAndroidSdkVersion | int | Minimum supported Android SDK version. |
| appletConfigFactory | IAppletConfigFactory | Implementation class for individual Mini-Program configurations. |
| enableScreenShot | boolean | Whether to allow screenshots and screen recording. Default is true. |
| screenShotPriority | FinAppConfigPriority | Priority of screenshot and screen recording configuration items. Default is GLOBAL. |
| enableWatermark | boolean | Whether to enable watermark. Default is false. |
| watermarkPriority | FinAppConfigPriority | Priority of watermark configuration items. Default is GLOBAL. |
| watermarkFactoryClass | String | Class name of the watermark View. |
| header | Map<String, String> | Header for network (request/uploadFile/downloadFile) requests in Mini-Programs. |
| headerPriority | FinAppConfigPriority | Priority of header configuration. Default is GLOBAL. |
| offlinePackageFactoryClass | String | Class name of the offline Mini-Program subpackage package file acquisition class. |
| navigateDelegate | NavigateDelegate | Delegate for opening other Mini-Programs in offline Mini-Programs. |
| logLevel | XLogLevel | Log level to be recorded. |
| logMaxAliveSec | long | Maximum cache time for log files, in seconds. Minimum cannot be less than 1 day, i.e., cannot be less than 1 * 24 * 60 * 60 seconds. |
| xLogDir | String | Custom storage path for log files. |
| offlineAccountInfoClass(废弃) | String | Class name of the offline Mini-Program AccountInfo implementation class. |
| schemes | String[] | Custom scheme array. The SDK internally supports WeChat, Alipay, FinClip App, tel, etc., by default. |
| enablePreNewProcess | boolean | Whether to create processes in advance. Default is true. |
| logDelegate | String | Class name of the delegate class receiving XLog log output. |
| performanceRecordDelegate | String | Class name of the delegate class receiving performance log output. |
| shareAppletHandlerClass | String | Class name of the delegate class for the share button event in the more menu. |
| appJsonHandlerClass | String | Class name of the delegate class receiving Mini-Program app.json. |
| locale | Locale | Language type for SDK public UI. Currently, only Chinese and English are supported. Default is Simplified Chinese. |
| logDelegate | String | Class name of the delegate class receiving XLog log output. |
| authRequestHandlerClass | String | Class name of the delegate class for pre-processing scope requests or system permission requests. |
| authResultHandlerClass | String | Class name of the delegate class for callback results of scope requests or system permission requests. |
| scopeSettingHandlerClass | Class name of the delegate class for the scope settings page. | |
| authInfoHandlerClass | String | Class name of the delegate class obtaining privacy agreement details pop-up title and text. |
| enableWebViewDownloadFile | boolean | Whether to allow web-view components to download files. Default is true. |
| backgroundFetchPeriod | int | Time interval (hours) for periodic updates. Setting to 0 will not initiate periodic updates or data prefetching requests. Acceptable range is 3-12 hours. |
| enableHoleRender | boolean | Enable WebView hole-punching same-layer rendering, supporting components (live-player, live-pusher) with priority higher than X5 same-layer rendering (see Initialization Integration (opens new window) section 3.6 for precautions). |
| privacyHandlerClass | String | Class name of the delegate class obtaining privacy agreement information. |
| showPrivacyInfoWhenRequestSystemPermission | boolean | Whether to display privacy information when requesting system permissions. |
| authDescStrategy | int | Mini-Program permission description configuration strategy (AUTH_DESC_STRATEGY_NONE: Default method, shows configured permission descriptions if available, otherwise does not show; AUTH_DESC_STRATEGY_SHOW_DEFAULT: Shows configured permission descriptions if available, otherwise shows built-in permission information; AUTH_DESC_STRATEGY_FORBIDDEN: Does not allow permission requests if no permission description is configured). |
| hideLandscapeStatusBar | boolean | Whether to hide the status bar in landscape mode. |
FinAppConfig Configuration Example:
Note
setProductIdentification: Added after version 2.38.1, it should be noted that productIdentification cannot contain whitespace or special characters. When using setProductIdentification to customize the product identifier, you need to create a custom paths file. For example, if the ProductIdentification value is happy, add an XML file named fin_applet_custom_provider_paths under the res/xml path. The filename must not be changed. The file content is as follows:
<!-- The filename must be fin_applet_custom_provider_paths.xml, used for replacement with the same name -->
<?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>
After the above configuration, a file with the path /internal storage/packageName/files/happy/hello.jpg will have its corresponding URI as content://com.finogeeks.finosprite.applet.provider/happy_uri/hello.jpg.
# FinStoreConfig Configuration Items
| Configuration Name | Type | Required | Description |
|---|---|---|---|
| sdkKey | String | Yes | SDK key generated when creating the application |
| sdkSecret | String | Yes | SDK secret generated when creating the application |
| apiServer | String | Yes | Server address, the backend address deployed by the customer |
| apmServer | String | No | APM event reporting server address; if not set, apiServer will be used |
| cryptType | String | No | Signature generation method for communication between the SDK and Mini-Program Management Console. Default is "MD5", can also be set to "SM" (National Cryptography) |
| fingerprint | String | No | SDK fingerprint, which must be passed in the Zhenglian environment, otherwise API access will fail |
| encryptServerData | Boolean | No | Default is false. Currently, it can only be set to false; setting it to true will cause API access failure |
| enablePreloadFramework | Boolean | No | Default is true. Whether to preload the Base Library; if set to false, the Base Library will not be pre-downloaded during SDK initialization |
# UIConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| isAlwaysShowBackInDefaultNavigationBar | boolean | Whether to always show the back button |
| navigationBarTitleTextLayoutGravity | int | Gravity of the Navigation Bar title relative to the parent control |
| navigationBarTitleLightColor | Integer | Light color of the Navigation Bar title text, used for Dark Mode |
| navigationBarTitleDarkColor | Integer | Dark color of the Navigation Bar title text, used for Light Mode |
| navigationBarBackBtnLightColor | Integer | Light color of the Navigation Bar back button, used for Dark Mode |
| navigationBarBackBtnDarkColor | Integer | Dark color of the Navigation Bar back button, used for Light Mode |
| isClearNavigationBarNavButtonBackground | boolean | Whether to clear the background of the Navigation Bar buttons |
| isHideFeedbackAndComplaints | boolean | Whether to hide the "Feedback and Complaints" button in the "More" menu |
| isHideBackHome | boolean | Whether to hide the "Back to Home" button on the Navigation Bar |
| isHideBackHomePriority | FinAppConfigPriority | Enum value, priority of the "Back to Home" button configuration item on the Navigation Bar, default is global priority |
| isHideForwardMenu | boolean | Whether to hide the "Forward" button in the "More" menu |
| isHideSettingMenu | boolean | Whether to hide the "Settings" button in the "More" menu |
| isHideRefreshMenu | boolean | Whether to hide the "Re-enter Mini-Program" button in the "More" menu |
| isHideShareAppletMenu | boolean | Whether to hide the "Share" button in the "More" menu, default is true |
| isHideAddToDesktopMenu | boolean | Whether to hide the "Add to Desktop" button in the "More" menu, default is true |
| isHideFavoriteMenu | boolean | Whether to hide the "Favorite" button in the "More" menu, default is true |
| hideDebugMenu | boolean | Whether to hide the debug button in the "More" menu |
| forwardMenuImageRes | int | Icon for the "Forward" button in the "More" menu |
| forwadMenuTitle | String | Title for the "Forward" button in the "More" menu |
| hideTransitionCloseButton | boolean | Whether to hide the close button on the Mini-Program loading page |
| disableSlideCloseAppletGesture | boolean | Whether to disable the swipe gesture to close the Mini-Program. Deprecated after version 2.43.5, please do not continue to use. |
| moreMenuStyle | int | Style of the "More" menu, options: MORE_MENU_DEFAULT, default style. MORE_MENU_NORMAL, normal style. MORE_MENU_PAGE, paginated style. |
| capsuleConfig | CapsuleConfig | Capsule configuration, see CapsuleConfig for details |
| floatWindowConfig | FloatWindowConfig | Floating window configuration in floating window mode, see FloatWindowConfig for details |
| loadingLayoutCls | String | Class of the custom loading view when customizing the loading view |
| autoAdaptDarkMode | boolean | Whether to automatically adapt to system Dark Mode (deprecated in version 2.44.5, use the new themeStyle property) |
| themeStyle | int | (Supported from version 2.44.5) Specifies the Mini-Program theme mode (follow system-THEME_STYLE_AUTO, dark-THEME_STYLE_DARK, light-THEME_STYLE_LIGHT) default value: THEME_STYLE_LIGHT |
| hideWebViewProgressBar | boolean | Whether to hide the progress bar when the web-view component loads H5 links |
| webViewProgressBarColor | int | Color of the progress bar when the web-view component loads H5 links |
| navHomeConfig | NavHomeConfig | Configuration of the Navigation Bar "Back to Home" button, see NavHomeConfig for details |
| navigateBarBackImageRes | int | Icon resource for the Navigation Bar back button |
| hideCapsuleCloseButton | boolean | Whether to hide the close button inside the capsule in the upper right corner of all Mini-Programs |
| authViewConfig | AuthViewConfig | Authorization popup configuration, see AuthViewConfig for details |
| commonUISupportOrientation | int | Orientation of common UI pages (e.g., About, Settings, etc.) |
| resizableOrientationLocked | boolean | Whether to lock the orientation (mainly for foldable screens) on devices where the screen size can change |
| moreMenuLogoConfig | ImageViewConfig | Logo-related configuration for the "More" button interface, see ImageViewConfig for details |
| hideClearCacheMenu | boolean | Whether to hide the "Clear Cache" button in the "More" menu |
UIConfig Example Code:
# CapsuleConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| capsuleWidth | float | Width of the top-right capsule view, default value is 88 |
| capsuleHeight | float | Height of the top-right capsule view, default value is 32 |
| capsuleRightMargin | float | Right margin of the top-right capsule view |
| capsuleCornerRadius | float | Corner radius of the top-right capsule view, default value is 5 |
| capsuleBorderWidth | float | Border width of the top-right capsule view, default value is 0.75 |
| capsuleBgLightColor | int | Light background color of the capsule, default is 0x33000000 |
| capsuleBgDarkColor | int | Dark background color of the capsule, default is 0x80ffffff |
| capsuleBorderLightColor | int | Light border color of the top-right capsule view, default is 0x80ffffff |
| capsuleBorderDarkColor | int | Dark border color of the top-right capsule view, default is 0x26000000 |
| moreLightImage | int | Light image for the "More" button inside the capsule; if not provided, the default icon will be used |
| moreDarkImage | int | Dark image for the "More" button inside the capsule; if not provided, the default icon will be used |
| moreBtnWidth | float | Width of the "More" button inside the capsule; height equals width, default is 32 |
| moreBtnLeftMargin | float | Left margin of the "More" button inside the capsule, default is 6 |
| closeLightImage | int | Light image for the "Close" button inside the capsule; if not provided, the default icon will be used |
| closeDarkImage | int | Dark image for the "Close" button inside the capsule; if not provided, the default icon will be used |
| closeBtnWidth | float | Width of the "Close" button inside the capsule; note: height equals width, default is 32 |
| closeBtnLeftMargin | float | Left margin of the "Close" button inside the capsule, default is 6 |
| redDotBtnWidth | float | Width of the red dot button inside the capsule, default is 6 |
| redDotBtnHeight | float | Height of the red dot button inside the capsule, default is 6 |
| redDotBtnRightMargin | float | Right margin of the red dot button inside the capsule, default is 6 |
| redDotBtnTopMargin | float | Top margin of the red dot button inside the capsule, default is 3 |
| redDotBtnDarkImage | int | Dark image object for the red dot button inside the capsule; if not provided, the default icon will be used (light mode) |
| redDotBtnLightImage | int | Light image object for the red dot button inside the capsule; if not provided, the default icon will be used (dark mode) |
CapsuleConfig Example Code
# NavHomeConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| lightImage | int | Light icon for the Navigation Bar "Back to Home" button; if not provided, the default icon will be used |
| darkImage | int | Dark icon for the Navigation Bar "Back to Home" button; if not provided, the default icon will be used |
| width | float | Width of the "Back to Home" button, default is 44 |
| height | float | Height of the "Back to Home" button, default is 32 |
| leftMargin | float | Left margin of the "Back to Home" button, default is 8 |
| cornerRadius | float | Corner radius of the "Back to Home" button border, default is 5 |
| borderWidth | float | Border width of the "Back to Home" button, default is 0.75 |
| borderLightColor | int | Light border color of the "Back to Home" button, default is 0X80FFFFFF |
| borderDarkColor | int | Dark border color of the "Back to Home" button, default is 0X26000000 |
| bgLightColor | int | Light background color of the "Back to Home" button, default is 0x33000000 |
| bgDarkColor | int | Dark background color of the "Back to Home" button, default is 0x80ffffff |
NavHomeConfig Example Code:
Note
The current conditions for the appearance of the "Return to Home" button are as follows (all must be met simultaneously):
- The default navigation bar style is used (not custom).
- It is neither the home page nor a tabbar page (as defined in app.json).
Additionally, Mini-Programs can call hideHomeButton() to hide the "Return to Home" button.
# AuthViewConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| appletNameTextSize | float | Font size of the Mini-Program name, default 16 |
| appletNameLightColor | int | Light color of the Mini-Program name, default #222222 |
| appletNameDarkColor | int | Dark color of the Mini-Program name, default #d0d0d0 |
| authorizeTitleTextSize | float | Font size of the authorization title, default 17 |
| authorizeTitleLightColor | int | Light color of the authorization title, default #222222 |
| authorizeTitleDarkColor | int | Dark color of the authorization title, default #d0d0d0 |
| authorizeDescriptionTextSize | float | Font size of the authorization description, default 14 |
| authorizeDescriptionLightColor | int | Light color of the authorization description, default #5c5c5c |
| authorizeDescriptionDarkColor | int | Dark color of the authorization description, default #5c5c5c |
| authorizeSelectedLightImage | int | Light icon when the agreement option is selected, size: 22x22dp |
| authorizeSelectedDarkImage | int | Dark icon when the agreement option is selected, size: 22x22dp |
| agreementLightImage | int | Light icon for the privacy agreement entry, size: 22x22dp |
| agreementDarkImage | int | Dark icon for the privacy agreement entry, size: 22x22dp |
| agreementTitleTextSize | float | Font size of the agreement title, default 16 |
| agreementTitleLightColor | int | Light color of the agreement title, default #222222 |
| agreementTitleDarkColor | int | Dark color of the agreement title, default #d0d0d0 |
| agreementDescriptionTextSize | float | Font size of the agreement description, default 14 |
| agreementDescriptionLightColor | int | Light color of the agreement description, default #222222 |
| agreementDescriptionDarkColor | int | Dark color of the agreement description, default #d0d0d0 |
| linkLightColor | int | Light color of links, default #4285f4 |
| linkDarkColor | int | Dark color of links, default #4285f4 |
| allowButtonLightConfig | AuthButtonConfig | Light configuration for the "Allow" button, see AuthButtonConfig for details |
| allowButtonDarkConfig | AuthButtonConfig | Dark configuration for the "Allow" button, see AuthButtonConfig for details |
| rejectButtonLightConfig | AuthButtonConfig | Light configuration for the "Reject" button, see AuthButtonConfig for details |
| rejectButtonDarkConfig | AuthButtonConfig | Dark configuration for the "Reject" button, see AuthButtonConfig for details |
# AuthButtonConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| cornerRadius | float | Corner radius of the button |
| normalBackgroundColor | int | Default background color of the button |
| pressedBackgroundColor | int | Background color of the button when pressed |
| normalBorderColor | int | Default border color of the button |
| pressedBorderColor | int | Border color of the button when pressed |
| normalTextColor | int | Default text color of the button |
| pressedTextColor | int | Text color of the button when pressed |
# FloatWindowConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| floatMode | boolean | Whether to enable floating window mode |
| x | int | X-coordinate of the origin of the floating window |
| y | int | Y-coordinate of the origin of the floating window |
| width | int | Width of the floating window |
| height | int | Height of the floating window |
On some large-screen devices, Mini-Programs can be configured to run in a floating window. When running in this mode, the position and size of the floating window can be configured, and the pages beneath the floating window will not be interactive.
After enabling the floating mode, you also need to override FinAppletTheme with FinAppletTranslucentTheme in the sample styles.xml.
<!--Floating mode requires overriding FinAppletTheme with FinAppletTranslucentTheme-->
<style name="FinAppletTheme" parent="@style/FinAppletTranslucentTheme" />
Example usage of FloatWindowConfig:
# ImageViewConfig Configuration Items
| Configuration Name | Type | Description |
|---|---|---|
| borderCornerRadius | float | Corner radius of the image border, default: 4.0 |
| borderWidth | float | Width of the image border, default: 0.5 |
| borderColor | int | Color of the image border, default: 0xffd8d8d8 |
| backgroundColor | int | Background color of the image, default: 0xffffffff |
Example usage of ImageViewConfig: