HarmonyOS SDK integration

Foreword

This SDK is built on HarmonyOS API 12. The compatibleSdkVersion is 5.0.0(12).

Preparations

1. Set up the HarmonyOS application development environment. For more information, see the HarmonyOS Application Development Documentation.

2. Create a HarmonyOS application and obtain the AppKey and AppSecret from the application settings. For more information, see Integrate the SDK.

Step 1: Install the SDK

Run the following command in the root directory of your HarmonyOS application to install the SDK:

ohpm install @aliyun/feedback

For more information about the ohpm tool and installing third-party SDKs for OpenHarmony, see the OpenHarmony Third-party Library Central Repository Guide.

Step 2: Initialize the SDK

You do not need to initialize the SDK at application startup. Call the initialization method before you use the SDK, as shown in the following code:

import {FeedbackAPI,InitConfig} from '@aliyun/feedback';
let feedback_config: InitConfig = new InitConfig({
    appkey: 'Your AppKey',
    appSecret: 'Your AppSecret',
    backIconResource: $r('app.media.app_logo'),
    loadProgressColor: '#0DD0FF',
    isOpenLog: true,
    rightButtonFontSize: 16
  })
// getContext() is the Context of the Ability where the current component resides.
FeedbackAPI.init(getContext(), feedback_config) 

For more information, see HarmonyOS SDK API.

Step 3: Get the unread feedback message count (Optional)

The SDK lets you retrieve the count of unread feedback messages. To display this count, use the following code:

FeedbackAPI.getFeedbackUnreadCount((count : number) => {
     promptAction.showToast({ message: "Unread message count: " + count })
}, () => {
     promptAction.showToast({ message: "Failed to get unread message count" })
})

For more information, see HarmonyOS SDK API.

Step 4: Add callbacks for photo album, camera, and microphone permission requests (Optional)

When a user performs an action that requires authorization for the first time, the SDK directly requests the necessary permissions.

You can register a callback listener to explain why a permission is needed before the SDK requests it. Use the following code:

let albumCallback: IPermissionRequestInterrupt = {
      interrupt: (context: Context, action: string, permissions: Permissions[],
        callback: InterruptCallback): void => {
          showDialog("Sensitive permission authorization required", "Photo Album", "Select a photo of the issue for feedback", callback)
      }
    }
FeedbackAPI.setPermissionInterrupt(FeedbackAPI.ACTION_ALBUM, albumCallback)
let cameraCallback: IPermissionRequestInterrupt = {
      interrupt: (context: Context, action: string, permissions: Permissions[],
        callback: InterruptCallback): void => {
           showDialog("Sensitive permission authorization required", "Camera", "Take a photo of the issue for feedback", callback)
        }
    }
FeedbackAPI.setPermissionInterrupt(FeedbackAPI.ACTION_CAMERA, cameraCallback)
let microPhoneCallback: IPermissionRequestInterrupt = {
      interrupt: (context: Context, action: string, permissions: Permissions[],
        callback: InterruptCallback): void => {
           showDialog("Sensitive permission authorization required", "Microphone", "Record an audio description for feedback", callback)
       }
    }
FeedbackAPI.setPermissionInterrupt(FeedbackAPI.ACTION_MICROPHONE, microPhoneCallback)

// This is sample code that displays a dialog box to explain the purpose of the permission.
private showDialog(title: string, permission: string, message: string, callback: InterruptCallback) {
    AlertDialog.show({
      title: title,
      message: `${permission}: ${message}`,
      autoCancel: true,
      alignment: DialogAlignment.Center,
      gridCount: 4,
      primaryButton: {
        value: 'Cancel',
        action: () => {
          callback.stopRequest()
        }
      },
      secondaryButton: {
        enabled: true,
        defaultFocus: true,
        style: DialogButtonStyle.HIGHLIGHT,
        value: 'OK',
        action: () => {
          callback.goOnRequest()
        }
      },
      cancel: () => {
        callback.stopRequest()
      }
    }
    )
  }

If a user denies the permission request, the SDK provides a callback to request the permission again.

You can use this callback to display a text reminder or guide the user to the System Settings page, as shown in the following code:

let rationaleCallback: IPermissionRationale = {
  onPermissionDenied: (permissions: Permissions[]): Promise<void> => {
    // Redirect to the Settings page.
    return new Promise<void>((resolve, reject) => {
      let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
      let context: Context = getContext() as common.UIAbilityContext;
      atManager.requestPermissionOnSetting(context, permissions).then((result) => {
        resolve()
      }).catch((error: BusinessError) => {
        reject(error)
      })
    })
  }
}
FeedbackAPI.setPermissionRationale(rationaleCallback)

For more information, see HarmonyOS SDK API.

Step 5: Set custom extension parameters, a nickname, and contact information (Optional)

The SDK lets you dynamically configure a user's nickname, contact information, and extension parameters. Configure these settings as needed using the following code:

FeedbackAPI.setUserNick('nickname')
FeedbackAPI.setDefaultUserContactInfo('contact_information')
let ext = `{"key":"value"}`
FeedbackAPI.setAppExtInfo(ext)

For more information, see HarmonyOS SDK API.

Step 6: Open the user feedback page

After you complete the configuration, you can open the user feedback page.

Because loading the user feedback page is a time-consuming operation, you can add a loading component to improve the user experience.

@State progressStatus = false

// Specific implementation of LoadingProgress...  

this.progressStatus = true
FeedbackAPI.openFeedback(() => {
  // Opened successfully.
  this.progressStatus = false
}, (info, code) => {
  // Failed to open.
  this.progressStatus = false
})

For more information, see HarmonyOS SDK API.