Android hotpatching tutorial

This topic is divided into two parts that provide a complete introduction and demonstration of the hotpatching process: Integrate hotpatching and Hotpatching bug demo.

Integrate hotpatching

The process to integrate hotpatching is as follows:

1. Configure the development environment

2. Create an application in the console

3. Create a new project in the client

4. Signature

5. Configure encryption information

6. Write the code

7. Release a client version with the hotpatching feature

Configure the development environment

For more information, see Configure the development environment.

Create an application in the console

For more information, see Create an mPaaS application in the console. At this point, you do not have a signed APK locally. You can skip uploading the APK when you download the configuration file.

An example of a downloaded configuration file name is Ant-mpaas-4111111111005-default-Android.config.

Create a new project in the client

Follow the steps in Integration process to create a new project based on the mPaaS framework in the client. Make sure that you can successfully build the project by selecting mPaaS > Build.

Sign

Signing the application is a prerequisite for configuring encryption information.

Open the Portal project in Android Studio. Then, follow the instructions in the official Android documentation to sign your application and generate a signed APK.

The steps to sign the application are as follows:

1. Generate a key and keystore. If you already have a keystore, skip this step.

   1. In Android Studio, open the Portal project, select Build > Generate Signed APK, and then click Create new.

      

   2. Enter the required information and click OK. Remember the information you enter here for later use.

      

2. Generate a signed APK.

   1. Select the keystore, enter the required information, and click Next.

      

   2. As shown in the following figure, enter the required information and click Finish. After a moment, a signed APK is generated.

      Note

      • In Signature Versions, you must select V1 (Jar Signature). You can select V2 (Full APK Signature) as needed.

      • The signed APK is saved in the {APK Destination Folder}/{Build Type} directory. In the example shown in the figure, the directory is /Users/archer.zb/AndroidStudioProjects/Tutorials/Hotpatch/app/debug/.

      

3. Follow the instructions in the official Android documentation to add the signing configuration to your code. After the configuration is complete, the build.gradle file looks similar to the following:

    signingConfigs {
        release {
            keyAlias 'keyAlias'
            keyPassword 'keyPassword'
            storeFile file('/Users/archer.zb/Desktop/hotpatch/keystore.jks')
            storePassword 'storePassword'
        }
        debug {
            keyAlias 'keyAlias'
            keyPassword 'keyPassword'
            storeFile file('/Users/archer.zb/Desktop/hotpatch/keystore.jks')
            storePassword 'storePassword'
        }
    }

Configure encryption information

To ensure the security of the hotpatch package retrieval process on the client, you must encrypt the network content. The steps to configure encryption information are as follows:

1. Log on to the mPaaS console and navigate to the Overview > Download Android Code Configuration > Code Configuration page. Upload the signed APK that you generated in the previous step and download the configuration file again. A .zip package is downloaded.

2. Decompress the .zip package. Use the Ant-mpaas-xxx-xxx-Android.config file in the package to replace the file with the same name in the main module of the Portal project.

   Important

   After the replacement, the value of base64Code must not be empty.

   

3. Delete the yw_1222.jpg image from the src/main/res/drawable directory of the main module in the Portal project.

   

4. Rebuild the Bundle and Portal projects separately.

Write the code

At this point, hotpatching is integrated. You can write code as needed.

Example buttons

To try out hotpatching, you can add two buttons to the interface of your Bundle project.

• Toast: The code for this button contains a bug. Clicking it causes the application to crash.

• Hotfix: After you release a hotpatch package in the console, click this button to trigger the hotpatch. After you restart the application, the bug in the code for the Toast button is fixed.

Sample code

The corresponding layout code is as follows:

<Button
    android:id="@+id/toast"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Toast" />

<Button
    android:id="@+id/hotfix"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Hotfix" />

The corresponding Java code is as follows:

findViewById(R.id.toast).setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
    // When the button is clicked, perform a division and display the result in a toast message.
    int result = 1/0; // The divisor is 0. This is a bug that causes the application to crash.
    Toast.makeText(getApplicationContext(), "result = " + result, Toast.LENGTH_SHORT).show();
  }
});

findViewById(R.id.hotfix).setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
    // When the button is clicked, trigger hotpatching.
    // If the SDK version is 10.1.32 or later, call the following API:
    MPHotpatch.init();
  }
});

After you add the sample code, rebuild the Bundle and Portal projects. For a demonstration of the hotpatching process, see the Hotpatching bug demo section below.

Publishing a Client Version with Hotpatching

After you finish writing the client code, you can publish the generated APK to an application platform so that app users can download the update. For more information, see Android Release Management or iOS Release Management.

Hotpatching bug demo

An example flow for hotpatching a bug is as follows:

1. Back up the .jar package from the build that contains the bug.

2. Fix the bug in the code and generate a hotpatch package.

3. Add and publish the hotpatch package in the console.

4. The client calls the API to trigger hotpatching and retrieve the hotpatch package.

5. After the application restarts, the hotpatch is triggered and the bug is fixed.

Back up the .jar package from the bug version build

Generating a hotpatch package requires the build results of both the version with the bug and the fixed version. Therefore, you must first back up the .jar package generated by the build with the bug.

Path of the .jar package:

• For a debug package, the file is build/intermediates/bundle/xxxx-raw.jar in the main Bundle module.

• For a release package, the .jar file name does not have the -raw suffix. For example:

  

Fix the code

Modify the code to fix the bug and then rebuild the project. In the preceding example, you can change the divisor to 1.

Generating a hotpatching package

In Android Studio, use the mPaaS > Generate Hotpatch feature to generate a hotpatch package.

• New bundle: The `.jar` package generated by rebuilding the project after you fix the bug.

• Old bundle: The `.jar` package from the backed-up version that contains the bug. For more information, see Back up the .jar package from the build with the bug.

• Whitelist (Optional): A configuration file in `.txt` format that specifies the classes to fix. For the rules to create this configuration file, see Whitelist configuration file rules. This feature is highly recommended for native Android Archive (AAR) projects.

• Patch file dir: The storage path for the hotpatch package. Many files are generated in this directory. You will use the `.jar` file later.

• Use DexPatch: Select this option.

For more information, see Generating a hotpatching package.

Add and publish a hotpatch package in the console

Add a hotpatch package

1. Navigate to the Real-time Publish > Hotpatching Management page in the mPaaS console.

2. Click Add Hotpatch, enter the required information, and then click OK.

Create a Publication

1. Click Create Publish.

   

2. Select a publish type and other settings, then click OK to publish. For more information, see Hotpatch Management.

App-triggered hotpatching

1. Open Android Studio Logcat, enter DynamicRelease in the search box, and set the filter to No Filters.

   

2. Connect your phone to Android Studio, open the app with the bug on your phone, and click the Hotfix button. The following logs are displayed:

   

3. Shut down the application process and restart the application. Then, click the Toast button. A toast notification appears correctly, which confirms that the bug is fixed.

Related links

• Hotpatching scenarios: Learn about the scenarios and limitations of hotpatching.

• Introduction to connection types: Learn about the two connection types: native AAR and component-based (Portal&Bundle).

• Create a new client project: Create an Android project based on the mPaaS framework.

• Compile and package: Build the project using the mPaaS plugin.

• Generate a hotpatch package: Use the mPaaS plugin to generate a hotpatch package.

• Manage hotpatches: Add and release hotpatch packages in the console.