# 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

  1. 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.
  2. The method of initializing a single server using Builder().setSdkKey and Builder().setSdkSecret may 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

          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):

            1. The default navigation bar style is used (not custom).
            2. 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:

                © FinClip with ❤ , Since 2017