SDK API
The initialize method
initialize(): <Required>
This method performs the required initialization and loads local patches if they exist. It does not automatically request new patches. To pull patches, call the `queryAndLoadNewPatch` method. We recommend that you call `initialize` as early as possible. This method must be called at the beginning of the `attachBaseContext` method in your Application class. Place the call after `super.attachBaseContext` and, if applicable, after `Multidex.install`. Before you call the `initialize()` method, you must call the following methods to set the required parameters:
setContext(application): <Required>
Passes the entry Application object.
setAppVersion(appVersion): <Required>
Specifies the version number of the application. This version number must correspond to the version that you create in the console when you pull a patch.
Examples:
If you pass 1.0.0 to `setAppVersion`, you must also create a version named 1.0.0 in the console and publish a patch for it. This allows the application to pull the patch for that specific version.
If you pass 1.0.0 to `setAppVersion` and load the corresponding patch, the patch for version 1.0.0 is automatically cleared after you upgrade to a new APK and pass 1.0.1.
setSecretMetaData(idSecret, appSecret, rsaSecret): <Optional, recommended>
These three secrets correspond to three parameters in the `AndroidManifest` file. You can use this method to set the secrets instead of declaring them in the `AndroidManifest` file. Setting the secrets in your code lets you use custom code obfuscation for better security. Settings from this method overwrite those in the `AndroidManifest` file. If you set a parameter to null, the SDK uses the corresponding value from the `AndroidManifest` file by default.
setEnableDebug(isEnabled): <Optional>
By default, the `isEnabled` parameter is `false`. This parameter enables or disables debug mode. In debug mode, logs are output and patch signature verification is skipped. This allows patches to load successfully even if they are unsigned or if signature verification fails. For offline debugging, set this parameter to `true`. To view logs, filter by the `Sophix` tag.
For production releases, you must set this parameter to `false`. Setting it to `false` enables patch signature verification. Otherwise, your application may be exposed to security vulnerabilities.
setAesKey(aesKey): <Optional>
Sets a user-defined AES key for symmetric encryption of the patch package. The value must be a 16-character string that consists of numbers and letters. This key must be identical to the AES key that you set in the patch tool. This ensures that the patch can be correctly decrypted and loaded. The platform is not aware of this key. Therefore, Alibaba Cloud cannot access your patches.
setPatchLoadStatusStub(new PatchLoadStatusListener()): <Optional>
Sets the listener for the patch loading status. The parameter for this method must implement the `PatchLoadStatusListener` interface. For more information, see the `PatchLoadStatusListener` interface section below.
setUnsupportedModel(modelName, sdkVersionInt): <Optional>
Adds unsupported devices to a blacklist. Hotpatching is disabled for devices on this list.
`modelName`: The value of `Build.MODEL` on the device. You can also retrieve this value by running the `adb shell getprop | grep ro.product.model` command.
`sdkVersionInt`: The Android version of the device, which is `Build.VERSION.SDK_INT`. If you set this parameter to 0, the setting applies to all Android versions for that device model.
You can also set the device blacklist directly in the console for more flexibility. For more information, see Filter devices.
The queryAndLoadNewPatch method
This method queries the server for new and available patches. The SDK limits consecutive calls to the `queryAndLoadNewPatch()` method to a minimum interval of 3 s. If you call the method more frequently, error code 19 is returned. If an available patch is found, the SDK downloads it to the local device. Then, the following occurs:
When packaging, you can use the patch tool to select whether to force a cold restart. If you do not select this option, the tool automatically determines whether to generate a cold-restart patch or a hotpatch based on the code changes.
A hotpatch does not always require an application restart to take effect. The requirement depends on the specific circumstances and the patch type. If the current patch is a cold-restart patch, the application must be restarted for the patch to take effect.
If an application already has a patch and a new one is found, the current session is not affected. When the application starts next, the old patch file is deleted, and the new patch is downloaded and preloaded. The new patch is then applied on the subsequent startup.
After a patch is published, it is not automatically pushed to the client. You must call the `queryAndLoadNewPatch` method to check if a new patch is available.
The SDK downloads only patches that have a version number higher than the existing patch on the application. For example, if the application has patch version 5, it downloads a new patch only if its version number is greater than 5.
The Mobile Hotfix console includes a feature that lets you roll back all patches. If this operation is performed, the method returns status code 18. When this status code is returned, the local patch is forcibly cleared. However, the local patch version number is not cleared.
The killProcessSafely method
After the `PatchLoadStatusListener` receives the `CODE_LOAD_RELAUNCH` code, you can call this method at an appropriate time to kill the process.
Do not kill the process directly using `Process.killProcess(Process.myPid())`. Doing so can disrupt the internal state of Sophix. Instead, you must use the `killProcessSafely` method. This method performs the required internal processing before it kills the process.
The cleanPatches() method
This method clears local patches. After the patches are cleared, the SDK no longer pulls patches of that version. You do not typically need to call this method because Sophix automatically clears patches that cause the application to crash.
The PatchLoadStatusListener interface
You must implement this interface and pass it to the `initialize` method. The patch loading status is sent to this interface through a callback. The callback includes the following parameters:
`mode`: This parameter has no practical use. For backward compatibility, its value is always 0.
`code`: The status code for patch loading. For more information, see the `PatchStatus` class description.
`info`: A detailed description of the patch loading status.
`handlePatchVersion`: The version number of the patch that is being processed. A value of 0 indicates that no patch is being processed. A value of -1 indicates a local patch. Other values indicate a patch from the server.
The setTags interface [New in v3.2.7]
This method sets tags for the client to use when it pulls patch packages. Tags support more complex conditions for phased releases. The following code provides some simple examples:
List<String> tags = new ArrayList<>();
tags.add("test");
// Call this method before the queryAndLoadNewPatch() method.
SophixManager.getInstance().setTags(tags)；List<String> tags = new ArrayList<>();
tags.add("production");
// Call this method before the queryAndLoadNewPatch() method.
SophixManager.getInstance().setTags(tags)；As shown in the preceding examples, you can set different tags to create multiple baseline packages for the same application version. For example, you can use a baseline package with the `production` tag for online releases and another baseline package with the `test` tag for the staging environment. This lets you test the same patch on the same application version in different environments without interference. You can add multiple tags. Each tag must be a non-empty string. When you generate a patch, you must use a baseline package and a fix package that have the same tags.