Step‑by‑Step Guide to Building a Hybrid Android‑Harmony (HAP) Package for Youku

To achieve the effect of sliding the Youku main‑client icon upward to invoke a Youku HarmonyOS card, the card code must be mixed‑packaged with the Android client. This guide outlines the complete workflow for creating an Android/Harmony mixed package.

Because rewriting a large Android app entirely with Harmony APIs is unrealistic, Huawei proposes an evolution path: gradually replace Android modules with Harmony FA/PA modules and mix‑package them for distribution, ultimately reaching a 100% pure Harmony app.

Currently, Youku's Android client and Harmony HAPs (desktop widget and multi‑screen interaction) are mixed‑packaged into a single product, representing the intermediate state of "smooth Android‑to‑Harmony evolution and interoperability".

Packaging Scheme Battle

1. Sub‑package Scheme

Package the original Android APK and the Harmony HAP (the compiled Harmony application) as separate products in the app market.

Advantages: APK and HAP can have different package names and be version‑controlled independently.

Disadvantages: Users must install both packages to experience the full functionality.

2. Mixed‑Package Scheme

Combine the original Android APK and the Harmony HAP into a single app for market distribution.

Advantages: Users install only one package and get the complete feature set without version mismatch concerns.

Disadvantages: The packaging process is more complex and imposes a same‑package‑name restriction on APK and HAP.

Compared with the sub‑package approach, the mixed‑package scheme provides a better user experience despite the extra effort on the development side, so it is the chosen solution.

What Is a Mixed Package?

In Android, the product is an APK; in Harmony, it is a HAP. Merging an APK and a HAP into a single bundle creates a mixed package (APP).

Mixed‑Package Use Cases

Scenario 1

When the Harmony version of an app provides only supplemental or enhanced capabilities to the existing Android app, the APK and HAP should be packaged together as a single application.

Scenario 2

If the Android app cannot be fully migrated to Harmony in a short period, the mixed‑package allows gradual migration while keeping the app runnable on Harmony OS.

Mixed‑Package Build Process

1. What Is a Mixed Package?

Android produces an APK; Harmony produces a HAP. Merging them yields a mixed package (APP).

2. Mixed‑Package Requirements and Constraints

The Harmony entry module must act only as a container; all code and resources must be moved to features.

Config.json files of entry and all features must keep the same versionCode and versionName as the Android APK.

The Android APK (legacyApk) must be a 64‑bit package without any 32‑bit native libraries.

The Harmony app must share the same package name as the original Android app.

HAP version must be >= 2.4.2.2 and apiVersion compatible >= 5.

The entry’s config.json label and icon must match the Android app to preserve branding.

3. Generation Steps

Step 1: Modify the Original Android APK Side

To inject a Harmony entry point, replace the application’s base class with AceHarmonyApplication (ohos.ace.ability.AceHarmonyApplication) and add Harmony compatibility attributes in the AndroidManifest:

<!--鸿蒙兼容性属性-->
<uses-feature android:name="zidane.software.ability" android:required="false" />
<meta-data android:name="permZA" android:value="true" />
<meta-data android:name="multiFrameworkBundle" android:value="true" />

Compile the modified Android project to obtain the legacyApk product.

Step 2: Modify the Harmony Project Side

Configure the build parameters:

Set compileSdkVersion and compatibleSdkVersion to 5 in all build.gradle files.

Update apiVersion in each config.json to compatible:5 and target:5.

Add originalName (same as bundleName) and synchronize version.code and version.name with the Android APK.

Ensure the vendor field is consistent across entry and features.

{
  "app": {
    "bundleName": "<package_name>", // must match Android APK package name
    "vendor": "xxx",
    "version": {
      "code": xxx, // Android versionCode, derived from name
      "name": "xxx" // Android versionName
    },
    "apiVersion": {
      "compatible": 5,
      "target": 5,
      "releaseType": "Release"
    }
  }
}

Add legacyApkOptions to the entry module to reference the processed Android APK:

apply plugin: 'com.huawei.ohos.hap'
ohos {
    // ... other settings
    legacyApkOptions {
        legacyApk "..\\..\\legacy_entry.apk" // must end with entry.apk
        legacyVersionCode "499" // must match AndroidManifest versionCode
        legacyVersionName "9.15.2" // must match AndroidManifest versionName
    }
}

Move all code and resources from the entry module to feature modules, add an empty Ability page, and keep the icon and label identical to the Android app.

Step 3: Signing

The mixed package must be signed with the same credentials as the original Android APK. Harmony requires an EC algorithm and a strong password (minimum 8 characters, mixed case, numbers, special symbols).

If the original signing material does not meet these requirements, you can either configure a separate shell‑APK signature or generate a new p12 and CSR using the same alias and EC algorithm:

// Generate p12
keytool -genkey -alias [keyname] -keystore [p12.file] -storetype pkcs12 -keyalg EC -keypass [password] -storepass [password]

// Generate CSR
keytool -certreq -alias [keyname] -keystore [p12.file] -storetype pkcs12 -file [csr.file]

After obtaining the .cer and .p7b files from Huawei, configure them in DevEco Studio and build the final APP.

Final Product and Release

The resulting mixed package can run on Harmony OS but cannot be installed directly; it must be signed through Huawei’s platform and then provided to Youku for testing.

Once testing is complete, the mixed package can be submitted to the Huawei AppGallery.

Key takeaways:

Hybrid packages must be 64‑bit.

Versioning and release cadence should align with the original Android app.

Avoid class name conflicts between APK and HAP to prevent runtime issues.

If the Android app uses restricted permissions (e.g., contacts, phone), ensure they are requested when applying for the Huawei p7b certificate.

The next article in the "Youku Harmony Development Practice" series will dive deeper into core capabilities such as normal flow, free view, and zoom on Harmony OS.