Use the SDK

After you add the SDK, complete the following steps to integrate the upgrade check feature into your HarmonyOS client:

1. Check for new versions: Call the SDK interface method in your code to check if a new version is available.

2. Configure a grayscale whitelist: Set options such as update notifications and grayscale release.

3. Publish online: Package the .app installation file and publish the new version.

Check for new versions

The upgrade check SDK provides an interface to check for application updates. The code is as follows:

export enum AliUpdateTypeEnum {
 AliUpgradeNewVersion = 201, /*The current version is the latest.*/
 AliUpgradeOneTime = 202, /*A new version is available on the client. Remind once.*/
 AliUpgradeForceUpdate = 203, /*A new version is available on the client. Force upgrade (deprecated).*/
 AliUpgradeEveryTime = 204, /*A new version is available on the client. Remind multiple times.*/
 AliUpgradeRejectLogin = 205, /*Restrict logon (deprecated).*/
 AliUpgradeForceUpdateWithLogin = 206 /*A new version is available on the client. Force upgrade.*/
}

interface upgradeRes{
 resultStatus:AliUpdateTypeEnum, // Upgrade type
 memo:string, //
 downloadURL:string, // New package download URL
 newestVersion:string, // Version number of the new package
 guideMemo:string, // Update description for the new package
 fullMd5:string, // MD5 of the new package
 fileSize:string, // Size of the new package
 upgradeVersion:string, // Version number of the new package
 netType:string, // Network type for this request
 userId:string, // User ID for this request
 error:Error
}

export default class MPUpgradeService {
 /**
 * The time interval for a single reminder, in days. The default is 3.
 */
 public static defaultUpdateInterval:number=3

 /**
 * Actively checks for updates and returns the remote procedure call (RPC) request result of the update interface.
 */
 public static async checkNewVersion():Promise<upgradeRes|null>

 /**
 * Actively checks for updates. If a new version is found, a pop-up notification is displayed.
 */
 public static checkNewVersionAndShow()

}

After the application starts, call the appropriate interface to check for updates. To avoid slowing down the application's startup speed, call the interface after the home page is displayed. The following two methods are available, depending on whether you want to automatically display a pop-up notification for the upgrade:

• Use the default mPaaS pop-up to display the upgrade notification. The code is as follows:

  import {MPUpgradeService} from '@mpaas/upgrade'
  
  MPUpgradeService.checkNewVersionAndShow()

• If the default mPaaS pop-up style does not meet your requirements, call the following interface to retrieve the upgrade information and display it using a custom UI:

  import {MPUpgradeService} from '@mpaas/upgrade'
  
  MPUpgradeService.checkNewVersion().then((response)=>{
      let str = JSON.stringify(response)
      AlertDialog.show(
        {
          title: 'Upgrade Check Result',
          message: str,
          autoCancel: true,
          offset: { dx: 0, dy: -20 },
          gridCount: 3,
          confirm: {
            value: 'Confirm',
            action: () => {
              console.info('upgrade result',response)
            }
          },
          cancel: () => {
            console.info('Closed callbacks')
          }
        }
      )
    })
  })

Configure a grayscale whitelist

To use the grayscale release feature with a whitelist, ensure that the server can obtain a unique identifier for the client. Before calling the upgrade check interface, the client must call the framework interface to set this unique user identifier. Return the application's unique identifier, such as a username, phone number, or email address, in the userId method.

MPFramework.instance.userId = 'hexi'

For more information about how to configure a whitelist in the mPaaS console, see Whitelist management.

Publish online

You can use the release management feature to publish a new version. For detailed instructions, see the HarmonyOS release management manual.

Upgrade modes

When you create a release task in the mPaaS console, you can select one of the following three upgrade modes:

• Single reminder: After you publish a new version in the mPaaS console, the client shows a pop-up notification only once during the cool-down period to avoid disturbing the user. This mode is useful for encouraging users to upgrade immediately after a new version is released.

  • The default cool-down period is 3 days. This means the user is reminded only once every 3 days.

  • To change the default value, set the following property before you call the upgrade check interface:

  MPUpgradeService.defaultUpdateInterval = 1

• Multiple reminders: After you publish a new version in the mPaaS console, a pop-up notification appears every time the client calls the version upgrade interface. This mode is useful for encouraging users to upgrade to a new version that has been available for some time.

• Forced reminder: After you publish a new version in the mPaaS console, a pop-up notification appears without a cancel button. The user cannot use the application unless they upgrade. This mode is useful for unpublishing old application versions and forcing users to upgrade.