Our smartphones have become all-in-one devices for everything from shopping to streaming. However, the constant need to open and close apps for simple tasks can be a frustrating user experience. To solve this problem, HarmonyOS provides Form Kit for you to develop widgets that can display important information or operations specific to an app, so that users can directly access a desired app service, without the need to open the app first.

Push Kit helps make user experience even better by allowing you to update your widget content in real time. After integrating Push Kit, your app can obtain a push token and push updated widget content via widget update messages at the right moment to engage users.

Constraints

The function of widget update messages supports phones, tablets, and PCs/2-in-1 devices. Starting from version 6.1.0(23), it is also supported on wearables and TVs.

Frequency Control

During the debugging phase, the maximum number of test messages that can be pushed for each project every day is 1000. To send test messages, you need to set testMessage to true.

After formal release, the total number of messages that each app can push to a single device each day is subject to the device-based message frequency control policy. The message sending frequency is governed based on service scenarios and traffic. In cases where message sending is unnecessary or unreasonable, frequency limits will be applied.

The update limits are set on the single widget basis. The number of update messages allowed for a single service widget is determined by the app category. For details about the frequency control rules, please refer to Push Updates for ArkTS Widgets.

NOTE

Regardless of whether it is a test message or a formal message, a widget update message can carry only one push token per push.

Development Procedure

Before pushing widget update messages, you need to complete widget development locally.

Create a local service widget by referring to Creating an ArkTS Widget.

Set the dataProxyEnabled field to true in src/main/resources/base/profile/form_config.json at the module level to enable the proxy-based widget update function.

Collapse
Word wrap
Dark theme
Copy code
{
  "forms": [
    {
      "name": "widget",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "updateDuration": 1,
      "scheduledUpdateTime": "10:30",
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2"],
      "dataProxyEnabled": true
    }
  ]
}

Obtain formId in the onAddForm() method of the widget lifecycle management file (EntryFormAbility is used as an example), and define the fields to be updated in the widget page file (WidgetCard is used as an example) and the fields to be updated through Push Kit. The following code uses fields textKey and imageKey as examples:

Collapse
Word wrap
Dark theme
Copy code
import { formBindingData, FormExtensionAbility, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
// ...

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    // Obtain formId.
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY] as string;
    // ...
    // Define the fields to be updated in WidgetCard.
    class CreateFormData {
      public formId: string = '';
      public textKey: string = '';
      public imageKey: string = '';
    }

    const obj: CreateFormData = {
      formId: formId,
      textKey: 'Default text',
      imageKey: ''
    }
    const bindingData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);

    // Define the fields to be updated through Push Kit. The key of each field must be defined in bindingData.
    const textKey: formBindingData.ProxyData = {
      key: 'textKey',
      subscriberId: formId
    };
    const imageKey: formBindingData.ProxyData = {
      key: 'imageKey',
      subscriberId: formId
    };
    bindingData.proxies = [textKey, imageKey];
    return bindingData;
  }

  // ...
}

Create LocalStorage variables in the widget page file (src/main/ets/widget/pages/WidgetCard.ets is used as an example), and bind them to the @Entry decorator. Use the @LocalStorageProp decorator to create key-value pairs for the variables.

In this section, three variables, formId, text, and image are created, corresponding to keys formId, textKey, and imageKey respectively. Note that image in the widget page layout indicates the Image component. Any variable transferred by the Image component must start with memory://.

Collapse
Word wrap
Dark theme
Copy code
// Define LocalStorage that stores the page-level UI state.
const storage = new LocalStorage();

// Complete binding.
@Entry(storage)
@Component
struct WidgetCard {
  @LocalStorageProp('formId') formId: string = '';
  @LocalStorageProp('textKey') text: string = '';
  @LocalStorageProp('imageKey') image: string = '';

  build() {
    Flex({ direction: FlexDirection.Column }) {
      Row() {
        Text() {
          // Span is a subcomponent of the Text component and is used to display the inline text.
          Span('formID:')
          Span(this.formId)
        }
        .fontSize(10)
      }

      Row() {
        Text() {
          Span('Text:')
          Span(this.text)
        }
        .fontSize(10)
      }

      Row() {
        if (this.image) {
          Image('memory://' + this.image).height(80)
        }
      }
    }
    .padding(10)
    .onClick(() => {
      postCardAction(this, {
        action: 'router',
        abilityName: 'MainAbility', // Set this parameter to the actual ability name of the app.
      });
    })
  }
}

Obtain a push token.

(Optional) Report information such as formId and pushToken to your app server in order to send a widget update message to your app.

Collapse
Word wrap
Dark theme
Copy code
// The pseudo-code is as follows:
import { Want } from '@kit.AbilityKit';
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { formInfo } from '@kit.FormKit';

const DOMAIN = 0x0000;

async function saveFormInfo(want: Want): Promise<void> {
  try {
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY] as string;
    const moduleName = want.moduleName;
    const abilityName = want.abilityName;
    const formName = want.parameters![formInfo.FormParam.NAME_KEY] as string;
    const pushToken: string = await pushService.getToken();

    // Report formId, moduleName, abilityName, formName, and pushToken to the app server.
  } catch (err) {
    let e: BusinessError = err as BusinessError;
    hilog.error(DOMAIN, 'testTag', 'Failed to save form info: %{public}d %{public}s', e.code, e.message);
  }
}

Call the REST API provided by Push Kit on your app server to push a widget update message. For details, please refer to the function description for the API used to push scenario-specific messages. The following is a request example:
Collapse
Word wrap
Dark theme
Copy code
```
// Request URL
POST "https://push-api.cloud.huawei.com/v3/[projectId]/messages:send"

// Request header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 1

// Request body
{
    "payload": {
    "moduleName": "entry",
    "abilityName": "EntryFormAbility",
    "formName": "widget",
    "formId": 423434262,
    "version": 123456,
    "formData": {
      "textKey": "Text to be updated"
    },
    "images": [
      {
        "keyName": "imageKey",
        "url": "https://***.png",
        "require": 1
      }
    ]
  },
  "target": {
    "token": [
      "MAMzLg**********lPW"
    ]
  },
  "pushOptions": {
     "testMessage": true
  }
}
```
- [projectId]: project ID. To obtain the value, sign in to AppGallery Connect, click Development and services, click the desired project, and go to Project settings.
- Authorization: a character string in JWT format. Obtain the value by referring to Authorization.
- push-type: The value 1 indicates the service widget update message type.
- moduleName: value of name in the module section in src/main/module.json5 at the module level.
- abilityName: ability name of the service widget in the extensionAbilities section in src/main/module.json5 at the module level.
- formName: name of the service widget in the forms section in src/main/resources/base/profile/form_config.json at the module level. The following figure uses the widget configuration file form_config as an example.
- version: version number of the current widget update message. A new message must have a higher version number than the current message. Otherwise, the update will fail. For details, please refer to version.
- formId: instance ID of a service widget, which is obtained when the onAddForm() method is called (a user adds the widget to the home screen). The maximum value is 2³¹-1.
- formData: service data of the service widget to be updated. The data comes from the declarative paradigm component name in src/main/ets/widget/pages/WidgetCard.ets at the module level. The following figure uses the widget page file WidgetCard as an example.
- images: image data in the service data of the service widget to be updated. keyName indicates the key value of the image control in the widget, and url indicates the image URL. The following figure uses the widget page file WidgetCard as an example.
  
  NOTE
  
  Do not push images that contain sensitive content.
  
  The supported image formats are PNG, JPG, JPEG, and WEBP. The image size cannot exceed 512 KB. Images exceeding this limit will not be displayed.
- require: image update control policy. The value 0 indicates that only text is updated if the image fails to be downloaded, and 1 indicates that the widget is not updated if the image fails to be downloaded.
- token: push token. Obtain the value by referring to Obtaining a Push Token.
- testMessage (optional): indicates whether a message is a test message. The value true indicates a test message. In each project, a maximum of 1000 test messages can be sent every day. Each push can carry only one token. For details, please refer to testMessage.

Pushing a Badge Update Message

Pushing a Text-to-Speech Message

Send feedback

Was this page helpful?

Send feedback

Reach out to us through the community for any other questions.

Community Q&A Intelligent Assistant