HarmonyOS Beta Distribution

Pgyer supports uploading, validating, and distributing HarmonyOS apps (.hap files) so testers can download and install them easily. This page covers the HarmonyOS signing model, the Pgyer distribution flow, and troubleshooting for common problems.

Prerequisites

• A Huawei Developer account with access to AppGallery Connect.
• A release certificate (.p12) created in AppGallery Connect — not a debug certificate.
• A Profile (.p7b) of type Specified Device Release, containing the UDIDs of your test devices.
• A .hap signed in DevEco Studio using that .p12, producing an xxx-signed.hap file.

HarmonyOS Apps and the Signing Model

HarmonyOS is Huawei's multi-device operating system, covering phones, tablets, wearables, and more. Native HarmonyOS apps are written in ArkTS and packaged as .hap, signed via Huawei's official certificate flow:

• .hap is HarmonyOS's installable app bundle (analogous to Android's .apk);
• Every .hap must be signed before it can install on a HarmonyOS device;
• The signing certificate is a .p12 issued through your Huawei Developer account.

A complete signature has three parts, and all three must match for a .hap to install correctly:

Distributing a HarmonyOS App on Pgyer

Upload the Signed .hap

Sign the .hap locally with your developer certificate — the file you upload to Pgyer must already be signed. Before uploading, confirm that:

• The .hap has been signed with a signing tool such as Huawei's DevEco Studio. A correctly signed output is named XXXX-signed.hap; see Huawei: Build and Package an App;
• The .p12 used to sign the .hap is identical to the .p12 you'll upload to Pgyer;
• Only HarmonyOS .hap files are supported at the moment.

Fill in App Information (Optional)

To help testers identify the app, you can optionally fill in:

• App name and version number (Pgyer parses and displays these automatically)
• Release notes
• Screenshots
• Beta notes

These fields show up on the app's distribution page.

Upload the .p12 and Set the Password

In the HarmonyOS beta flow, Pgyer generates and signs the manifest.json5 to produce valid install metadata, so you need to provide the .p12 certificate and password that match the .hap:

• Download the .p12 from Certificate, App ID and Profile in AppGallery Connect;
• The certificate must be the same one used to sign the .hap, otherwise install will fail;
• Pgyer does not sign the .hap itself — the .p12 is used only to sign manifest.json5.

When uploading the P12, enter the certificate password and key alias in the popup. The alias defaults to the first one; if the P12 contains multiple keys, enter the alias actually used when packaging the app.

Why the .p12 Is Required

This is one of Huawei's verification checks: HarmonyOS devices validate the manifest.json5 signature at install time to ensure the app comes from a trusted source. See Huawei's documentation for details.

Share the Download Link

Once the upload finishes, Pgyer generates a download link and QR code:

• Install via the link or by scanning the QR code;
• Shareable through WeChat, email, DingTalk, and other channels;
• Installation is only supported from a browser on a pure HarmonyOS NEXT device.

Because .hap installs are constrained by system security policy, using Huawei's built-in browser to open the download page is recommended.

Common Questions

The .hap Uploads but Fails to Install, Saying "XXXXXX" Cannot Be Installed

This usually points to a signing or configuration issue. Walk through the checklist below.

Signing

• The .hap must be signed, not unsigned. For the entry module, DevEco Studio produces both xxx-signed.hap and xxx-unsigned.hap under /entry/build/default/outputs/default — use the former:

  

• The .p12 used to sign the .hap must be the same one uploaded to Pgyer;

• After uploading the .p12, double-check the password (the platform surfaces a message if it's wrong);

• The .p12 must be a release certificate, not a debug certificate. How to apply for a release certificate

Profile (.p7b)

• The Profile used to sign the .hap must be of type Specified Device Release. If not, the console reports Profile type error after upload. See Apply for a Specified Device Release Profile:

  

• The Profile must include the UDID of the test device. How to collect a UDID

Digging Deeper

If none of the above explains the failure, look up the error code shown at install time in the Huawei error code reference, or consult the Error Reference section below.

Can One Link Serve Multiple Testers?

Yes. A download link can be shared with any number of testers, and the platform provides install analytics and device identification.

Does Pgyer Modify the .hap File?

No. Pgyer does not modify the .hap itself — it only signs manifest.json5 so the app can install correctly.

Is API Upload Supported?

Yes. Pgyer exposes an API for uploading app files. For HarmonyOS apps, after the first upload you'll also need to call the API to upload the .p12. See the API docs.

Can .hsp Files Be Uploaded?

Yes. Upload the .hap first, then look for the .hsp upload entry in App Management.

• The entry only appears for apps that need .hsp dependencies, and shows how many are required;
• Only internal .hsp dependencies are supported — external ones are not.

Unsupported Scenarios

• .app files;
• Uploading multiple .hap files under the same app;
• HarmonyOS Atomic Services. If the icon disappears right after download, it's likely an atomic service, which is not supported at the moment.

Error Reference

Common Error Codes

Other Common Messages

Further Reading

• Huawei: HarmonyOS App Beta Distribution Guide