Widget

A widget is an extension of miniapp development. You can build a widget in a similar development mode to miniapps. After a miniapp is distributed to an app, the widget is displayed on the app. Compared with a miniapp, a widget is more lightweight, convenient, and suitable to be displayed.

Features

Widgets can be integrated with miniapps and native apps. Widgets for miniapps are displayed as dialog boxes. Widgets for native apps are displayed as dialog boxes, components, and page elements. The specific pattern of a widget is subject to your customization.

APIs

Create widget dialog box

Similar to Dialog, a widget dialog box is overlaid on top of a page.

/**
     * Creates and displays a dialog box widget.
     * @param context The context.
     * @param url The URL of the widget. For more information about the format, see the descriptions of parameters in the subsequent section.
     * @param callback The callback to invoke.
     */
    fun showWidgetDialog(context: Context, url : String, callback : IMiniAppWidgetDialogCB)

Example

ThingMiniAppClient
                .widgetClient()
                .showWidgetDialog(this, url, new IMiniAppWidgetDialogCB() {

                    @Override
                    public void result(Dialog result) {
                        // The trigger after the dialog box appears.
                    }

                    @Override
                    public void unSupport(Dialog dialog) {
                        // The callback to invoke when a scene is not supported.
                    }
                });

Create widget view

Similar to View, a widget view can be displayed as a component and a page element of a native app. The specific pattern of the widget is subject to your customization.

/**
     * Creates a widget view.
     * @param creator The builder parameter.
     */
    fun createWidgetView(creator : WidgetCreatorBuilder)

Example

ThingMiniAppClient
                .widgetClient()
                .createWidgetView(
                        WidgetCreatorBuilder.newInstance()
                                .addDeployCreatorBuilder(
                                        WidgetDeployCreatorBuilder.newInstance()
                                                .build(url)

                                )
                                .build(context));

Preload widget

Preloads a widget at the right time to accelerate the startup of the widget.

/**
     * Preloads a widget.
     * @param appId The widget ID.
     */
    fun preloadWidget(appId : String)

Example

ThingMiniAppClient.widgetClient().preloadWidget("tydhopggfziofo1h9h");

Parameters

When you create a widget, set a URL for the widget in the format of godzilla://miniprogramId/widget/card/index?miniWidgetStyle=large&miniVersionType=release.

The URL is a standard path format that includes basic information about the widget. The following parameters are used:

• scheme: Set it to godzilla.
• host: The appId of the miniapp.
• path: The path through which the widget page is opened. If you do not set the value, the page indicated by entryPagePath in the widget configuration file will be opened.
• query: The parameters that are required for opening the widget. For more information, see query.

query

• miniWidgetStyle: The style of the widget. Valid values:

  • small: The aspect ratio is 1:1 and the width is half of the screen width.
  • middle (default value): The aspect ratio is 1:2, and the width is the same as the screen width.
  • large: The aspect ratio is 2:2, which simplifies to 1:1, meaning the height and width are equal. Both the width and height are equal to the screen dimensions.
  • custom: The custom aspect ratio, based on the screen width. The height is the screen width multiplied by custom.

• miniAppVersion: The version number of the widget. It defaults to the latest version number.

• miniVersionType: The type of version for the widget. Valid values:

  • release (default value): The official version that is used by the widget running in a production environment.
  • preview: The preview version that is used by the widget to be previewed during the development stage.

• miniPosition: The location of the widget dialog box to be displayed on the screen. Valid values:

  • bottom (default value): Bottom of the screen.
  • top: Top of the screen.

• miniAutoDismiss: Specifies whether the widget dialog box automatically disappears after users tap the overlay. Valid values:

  • true (default value): The widget dialog box automatically disappears after users tap the overlay.
  • false: The widget dialog box does not automatically disappear after users tap the overlay. It can disappear only after you make a certain API request.

• miniAutoCache: Specifies whether the widget is automatically cached. Valid values:

  • true (default value): The widget is automatically cached. Thus, the snapshot is displayed in priority when the widget appears next time.
  • false: The widget is not automatically cached. Thus, the widget is loaded to be displayed next time.

• Other parameters: In addition to the preceding parameters, you can set more business parameters. The widget gets the following parameters from Widget.onLoad.

  Parameter name	Required	Description	Example
  miniWidgetStyle	Yes	When you set the value to custom, the aspect ratio of the widget is required.	miniWidgetStyle=1.5
  miniAppVersion	No	This parameter is not required when the latest value is pulled.	miniAppVersion=2.0.0
  miniVersionType	No	Set the value to release or leave it empty when you launch the widget.	miniVersionType=release
  miniPosition	No	Set the location of the widget dialog box to be displayed on the screen. It defaults to bottom.	miniPosition=bottom
  miniAutoDismiss	No	This parameter is required if the widget dialog box does not disappear after users tap the overlay.	miniAutoDismiss=false
  miniAutoCache	No	This parameter is required if the cached snapshot is not displayed in priority for the widget.	miniAutoCache=false