Generate a patch

Patch versioning

1. A patch is bound to a specific client version.

   For example, if the current app version is 1.1.0, you can only query patches published for version 1.1.0 in the console. You cannot find patches published for the previous 1.0.0 version.

2. A new patch for a specific version must be cumulative, containing all previous bug fixes. It cannot rely on incremental patching because an application can only load one patch at a time.

   For example, you publish patch 1 for app version 1.0.0 to fix bug1. Later, you discover that the fix is incomplete and the code contains a new issue, bug2. When you publish a new patch, patch 2, it must include the fixes for both bug1 and bug2. If patch 2 only contains the fix for bug2, the fix for bug1 becomes ineffective.

Download the patching tool

To generate a patch package, you must use the SophixPatchTool. If you have not downloaded the patching tool, download the Android patching tool.

You can download the patching tool from the following links:

• Download the patching tool for macOS

• Download the patching tool for Windows

• Download the patching tool for Linux

Generate a patch package

1. Double-click the patching tool to open its main dialog box.

   Parameter	Description
   Old package	Required: Select the path to the baseline package (the APK with the issue).
   New package	Required: Select the path to the new package (the APK where the issue is fixed).
   Log	Opens the log output window.
   Settings	• Patch output path: Required: The directory where the generated patch will be saved. This must be an existing directory. • Key Store Path: Optional: The path to your local key store file. If left blank, the patch is not signed. Only JKS format is supported. • Key Store Password: Optional: The password for the key store file. • Key Alias: Optional: The alias of the key. • Key Password: Optional: The password for the key. • AES Key: Optional: A custom AES key. It must be a 16-character string of letters and numbers and must match the key set in setAesKey. • Filter Class File: Optional: The path to the allowlist file. Classes listed in this file are excluded from patch calculation. The file format is one class name per line.
   Advanced	• Force cold start: If selected, forces the patch to require a cold start. By default, the tool automatically determines whether to use a hot fix or a cold start based on the code changes. • Do not compare resources: Excludes resource changes from the patch generation process. • Do not compare SO libraries: Excludes SO library changes from the patch generation process. • Check initialization: Verifies that the initialization code is written correctly. • Fast packaging: Speeds up the patch generation process. • Optimize resource patch: Compresses the size of patch resources.
   GO!	Starts the patch generation process.

2. Upload the old and new packages, configure the settings, and then click GO.

Generate a patch from the command line

Before using the command line, you must prepare a configuration file in JSON format as follows:

{
    "AesKey": "",
    "ClassFilterFilePath": "",
    "KeyAlias": "",
    "KeyPassword": "",
    "KeyStorePassword": "",
    "KeyStorePath": "",
    "NewApkPath": "/path/to/new.apk",
    "OldApkPath": "/path/to/old.apk",
    "OutputDirPath": "/path/to/output/dir/",
    "isForceColdFix": false,
    "isIgnoreRes": false,
    "isIgnoreSo": false
}

The required fields are NewApkPath, OldApkPath, and OutputDirPath. The other options map to the fields in the GUI. Save this content as a profiles.json file.

Then, run the following command to generate the patch package:

SophixPatchTool is SophixPatchTool.exe on the Windows platform and SophixPatchTool.app/Contents/MacOS/SophixPatchTool on the Mac platform.

SophixPatchTool --profiles profiles.json

After the command finishes, it generates the patch file in the directory specified by OutputDirPath.

Usage notes

• For multi-channel packages, you can use a patch generated from a single channel, provided the code changes are identical across all channels. However, thoroughly test the patch against each unique baseline package.

• Before release, strictly follow the recommended patch release process to ensure that the patch package works correctly on all supported Android versions and device models.

• If the macOS patching tool crashes on launch, move it to the Applications folder.

FAQ

• What is a baseline package?

• Does Sophix hot fix support app hardening?

• When does Sophix use a hot fix versus a cold start?

• How do I configure the obfuscation file to ensure consistent obfuscation between the old and new packages?