Debug a patch

Overview

The debugging tool is used to debug patches before they are published. Two testing methods are available:

• Scan a QR code: You can download a patch that you uploaded to the console to your local device by scanning a QR code. Then, you can attempt to load the patch.

• Apply a local patch: You can enter the absolute path of a local patch and then attempt to load it. For this method, make sure that `setEnableDebug` is set to `true` during Sophix initialization. For security reasons, you cannot load local patches on packages where `setEnableDebug` is `false`. Therefore, use the QR code method to test packages where `setEnableDebug` is `false`.

Debugging methods

1. Download the debugging tool

   You can download the Android debugging tool. Install the tool on your Android phone.

2. Application connection test

   Open the debugging tool on your phone. In the text box at the top, enter the package name of the test application, and then click Connect Application.

   Note

   The tool connects to the test application. After a successful connection, the tool displays the application information. The tool connects to the original application using Android Interface Definition Language (AIDL). This may cause the connection to fail on some phone models. For example, on the latest MIUI systems, cross-application AIDL is disabled by default. You can change the settings on MIUI to remove this restriction. The process is similar for other systems.

3. Apply the patch

   • Scan a QR code

     1. Log on to the EMAS console and select Mobile Hotfix.

     2. Find your project and select the corresponding application.

     3. In the navigation pane on the left, select Patch Management.

     4. On the Patch Management page, select the application Version.

     5. In the version list, click Publish next to the patch that you want to debug. This opens the patch publishing page.

     6. In the mobile debugging tool, click Scan QR Code and scan the QR code for Test Patch. This sends a request to the application to pull the patch.

     7. The patch pull and load status is displayed on the debugging application interface. After the patch is successfully downloaded and loaded, open the application to verify it.

   • Apply a local patch

     1. Save the generated patch package to your phone. You can save it in any folder in local storage.

     2. Open the debugging tool. In the text box above the Apply Local Patch button, enter the absolute path of the patch, and click Apply Local Patch.

     3. The patch load status is displayed on the debugging application interface. After the patch is successfully loaded, open the application to verify it.

4. Disconnected Applications

   After debugging is complete, click Disconnect Application in the mobile debugging tool.

5. Complete the debugging

   If the patch works as expected, click Test Passed on the Upload Patch tab.

Debugging example

1. Build the application from the Android demo project and install it on your phone.

2. Install and open the Android debugging tool.

3. On the debugging tool page, enter the package name of the demo application in the text box at the top and click Connect Application. A Connection Successful message is displayed.

   Note

   If the message "The application package name is incorrect. Please enter it again." is displayed, you can debug the patch using the Create Release - Canary Release operation.

4. Example of applying a local patch

   • Push the `sophix-patch.jar` package generated by the patch tool to the `/sdcard/Download` folder on your local device. Then, in the debugging tool, enter the absolute path of the patch package and click Apply Local Patch.

   • `Mode:2` indicates the local patch mode. `Code:1` indicates that the patch was loaded successfully. `HandlePatchVersion:-1` indicates a local patch.

5. Example of scanning a QR code

   • Upload the `sophix-patch.jar` package generated by the patch tool to the Mobile Hotfix console.

   • Click Scan QR Code and scan the patch QR code from the console.

   • `Mode:1` indicates the QR code scanning mode. `Code:12` indicates that the application already has a patch, so the new patch will not be loaded immediately. It will be loaded after the next restart. `HandlePatchVersion:89` indicates that the version of the patch pulled from the console is 89.

6. Complete the debugging

   If the patch works as expected, click Test Passed on the Upload Patch tab.

For more information about status codes, see Common status codes.