Dashboard Card SDK Usage

Revision History

1. Overview

This document describes how to integrate the pages, navigation callbacks, resource extension capabilities, and Aqara Spec data notification and control capabilities provided by the Dashboard Card SDK based on the host project's MainActivity, initHome(), and host callback and strategy implementations.

2. Prerequisites

1. Complete the preparation work
2. Complete the environment setup
3. Complete the integration of the Dashboard Card SDK

3. Usage

3.1 Open the Dashboard Card Page

The host entry page usually determines the current device form first, initializes the Home module, and then loads the home homepage HomeMainFragment:

class MainActivity : BaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. Set phone / tablet mode
        LumiRouterManager.instance.isTablet =
            resources.configuration.orientation == Configuration.ORIENTATION_LANDSCAPE

        // 2. Initialize the home capability
        initHome()

        // 3. Load the home homepage
        startHome()
    }

    open fun startHome() {
        loadRootFragment(R.id.fl_container, HomeMainFragment())
    }
}

Key Parameters

If you need to navigate to other pages such as the Service Square or card list, you can follow the host implementation pattern of ARouter.build(...).withString(PATH_KEY, ...).navigation() and replace the target path as needed.

3.2 Dashboard Navigation Callback

3.2.1 Callback Overview

Capabilities such as card click handling, page navigation, offline handling, and web page opening are recommended to be provided to the host through IHomeConfigurationCallback.

The recommended approach is:

1. The host implements a callback class, for example HomeCallBack
2. The callback class implements IHomeConfigurationCallback
3. The callback is exposed to the dashboard module through ARouter

IHomeConfigurationCallback is the unified navigation interface exposed by the dashboard module to the host. Card clicks, page transitions, offline handling, web page opening, and theme changes are eventually passed back through this interface.

3.2.2 IHomeConfigurationCallback Interface

The key characteristics of this interface are:

1. It inherits from IProvider and is discovered through ARouter
2. Most business entities are passed through as Any, and the host must cast them to the actual types
3. The dashboard module calls this interface through a unified routing layer without directly depending on host business pages

Common methods and parameter conventions are as follows:

Additional notes:

1. The dashboard module determines which callback method to invoke based on the card type
2. For example, device cards call gotoDeviceHomePage(...) and scene cards call gotoSceneHomePage(...)
3. The host must correctly recognize the real type behind each Any parameter in order to retrieve the passed business data

3.2.3 Integration Recommendations

1. Review the host's existing pages and confirm the paths and parameters for device detail, home management, scenes, automations, and web containers
2. Implement the actual navigation logic in the IHomeConfigurationCallback implementation using ARouter or the host routing system
3. If the current project is display-oriented only, start with basic device, scene, and web navigation, and keep the remaining callbacks as placeholders

3.3 IALinkCallBack Interface

3.3.1 Interface Responsibilities

The Dashboard Card SDK connects to the host device link layer through IALinkCallBack to handle Aqara Spec related data notifications and control capabilities. The host usually needs to implement the following types of methods in this interface:

1. Push callback methods for receiving real-time trait change notifications
2. Data read proxy methods for reading current values by device, function, or trait
3. trait write methods for modifying trait property values
4. Command dispatch methods for executing device commands that are independent of trait write

3.3.2 Key Methods

3.3.3 Integration Recommendations

1. Ensure that IALinkCallBack is registered correctly and can be invoked through the unified device link layer
2. Use onTraitPush(...) as the real-time update entry and prioritize it for passive refreshes triggered by device reports
3. Reuse the host's existing device cache, device center, or query APIs for read proxy methods whenever possible
4. Route trait write methods through the host's existing write path so permission checks, throttling, logging, and retries can be handled consistently
5. Route command dispatch methods through an independent command control path and keep the implementation separate from trait write to avoid semantic confusion
6. If trait changes are frequent, add deduplication, throttling, or device-level merge refresh logic to reduce UI jitter and repeated rendering

3.3.4 Usage Notes

1. IALinkCallBack is the core interface for integrating Aqara Spec data notifications and control capabilities in the dashboard module
2. Push callbacks, data reads, trait write, and command dispatch should be planned uniformly by the host, but implemented as separate paths
3. trait write is used for property updates, while command dispatch is used for independent device commands, and they are not the same control mode
4. If this interface is not implemented correctly, card refreshes may fail, first-screen status may be inaccurate, or control behavior may become inconsistent

3.4 Dashboard Feature Switches

3.4.1 IPanelPermissionStrategy Overview

Whether dashboard capabilities are shown, clickable, or editable is recommended to be controlled through IPanelPermissionStrategy.

This interface controls which features are visible or available on the Home Configuration pages, and the host can inject its own strategy during initialization.

LMHomeManager.getInstance().setPanelPermissionStrategy(object : IPanelPermissionStrategy {
    override fun supportVoice() = false
    override fun supportAddDeviceSceneAutomation() = true
    override fun supportCardClick() = false
    override fun supportEditCard() = true
    override fun supportSwitchHome() = true
    override fun supportStatistics() = true
    override fun supportThemePanel() = false
    override fun supportLAN() = true
    override fun supportCardType() = getSupportCardType()
})

3.4.2 Common Strategy Items

3.4.3 Recommendations

If the project mainly focuses on dashboard content, the following switches should be confirmed first:

1. supportCardClick() decides whether cards can open details or trigger navigation
2. supportEditCard() decides whether users can edit cards
3. supportSwitchHome() decides whether switching across homes is allowed
4. supportCardType() decides which card types can be displayed on the dashboard

If your goal is display only with no navigation, you can set supportCardClick() to false and selectively keep editing and home switching enabled.

3.5 Resource Extension

3.5.1 Local Resource Extension (Optional)

If you need to override the default skins, images, or copywriting, you can place custom resources in the Demo resources or assets directories and inject them through extension points such as ThemeStyle.getInstance().getBaseThemePack() or ResourcesWrapper.

3.5.2 Remote Resources (Optional)

The Dashboard Card SDK supports delivering card skins, copywriting, and related resources through remote configuration. The current version is maintained by the internal configuration center. If you need external access, please contact business support.

The examples above are based on the Demo structure of the host project. You can trim them as needed, and by keeping the onCreate -> initHome -> startHome call chain, you can quickly launch the home homepage and the core dashboard card capabilities.