How to switch between static and dynamic environments - Mobile Platform as a Service

During application development, you often need to change an application's environment information or work with multiple environments in parallel. These environments are called workspaces.

mPaaS provides two methods to easily switch environments during development:

Static environment switch
Dynamic environment switch

Static environment switch

Prerequisites

You have an app developed on the mPaaS framework. For more information, see Getting Started with the mPaaS Framework.

You can use easyconfig to switch environments statically. This tool performs the following actions:

Modifies the meta properties related to the workspace in AndroidManifest.
Modifies the mpaas.properties file in the assets directory.
If the mPaaS project configuration file contains a non-empty base64 property, it generates the Security Guard encrypted image yw_1222.jpg.

Public cloud

To switch workspaces in a public cloud environment, follow these steps:

Ensure that the build.gradle file in the project's root directory has the following dependencies:

Note

The versions of these dependencies might change in future updates.

 classpath 'com.alipay.android:android-gradle-plugin:3.0.0.9.13'
 // The version number must be greater than 2.8.4
 classpath 'com.android.boost.easyconfig:easyconfig:2.8.4'

Ensure the build.gradle file of the main project (android main module) has the following configuration. Note the order:

 apply plugin: 'com.alipay.portal'
 // Place this after com.alipay.portal
 apply plugin: 'com.alipay.apollo.baseline.update'

Download the .config configuration file for the target workspace from the console. For more information, see Create an application in console > Download the configuration file.
Add the downloaded .config file to the main project path (android main module). The following figure shows an example:
Important
Keep only the configuration file for the current workspace.

Apsara Stack

In an Apsara Stack environment, follow these steps to switch workspaces:

Ensure that the build.gradle file in the project's root directory has the following dependencies:

Note

The versions of these dependencies might change in future updates.

 classpath 'com.alipay.android:android-gradle-plugin:3.0.0.9.13'
 // The version number must be greater than 2.8.4
 classpath 'com.android.boost.easyconfig:easyconfig:2.8.4'

Ensure the build.gradle file of the main project (android main module) has the following configuration. Note the order:

 apply plugin: 'com.alipay.portal'
 // Place this after com.alipay.portal
 apply plugin: 'com.alipay.apollo.baseline.update'

Download the .config configuration file for the target workspace from the console. For more information, see Download the configuration file.
Add the downloaded .config file to the main project path (android main module). The following figure shows an example:
Important
Keep only the configuration file for the current workspace.
Use the mPaaS plugin to generate the yw_1222.jpg encrypted image. For more information, see Encrypted images (Apsara Stack).

Dynamic environment switch

Dynamic environment switching lets you change an application's environment information by modifying environment options in the phone's settings without repackaging the client.

Note

The dynamic environment switch feature is only supported in Apsara Stack environments.
Dynamic environment switching is suitable for development scenarios where multiple environments exist and are switched frequently.
Because dynamic environment switching requires writing the new environment's configuration file to the application, you must request file storage permissions for the application.

Updating the environment configuration information modifies the Security Guard signature verification image (yw_1222.jpg). Due to the limitations of the mPaaS security signature verification mechanism, dynamic environment switching has the following two limitations:

This method is only applicable during the development phase. Before you publish the application, you must delete the corresponding configuration. Otherwise, the release package reports a RuntimeException.
You must turn off the network request signature verification switch in the mPaaS console. Otherwise, requests fail because of incorrect signature image information.

Add the dynamic environment switch SDK

Add dependencies.

For the native AAR connection type, add the following dependency to dependencies in the build.gradle file of the project's main module:
```
dependencies {
···
implementation 'com.mpaas.mocksettings:mocksettings-build:10.1.60a.1575@aar'
···
}
```

For the Portal & Bundle connection type, add the following dependency to dependencies in the build.gradle file of the Portal project's main module:

dependencies {
···
bundle 'com.mpaas.mocksettings:mocksettings-build:1.0.0.200421111458@jar'
manifest 'com.mpaas.mocksettings:mocksettings-build:1.0.0.200421111458:AndroidManifest@xml'
···
}

Use the SDK.

For the native AAR connection type, rewrite the getPackageManager method of the Application and replace PackageManager with MockSettingsPackageManager.

private MockSettingsPackageManager mockSettingsPackageManager;

@Override
public PackageManager getPackageManager() {
    if (mockSettingsPackageManager == null) {
        mockSettingsPackageManager = new MockSettingsPackageManager(this, super.getPackageManager());
    }
    return mockSettingsPackageManager;
}

For the Portal & Bundle connection type, modify the application in the AndroidManifest.xml file of the Portal project's main module to the following:
```
<application
     android:name="com.alipay.mobile.quinox.MockSettingsLauncherApplication"
     ···
     >
     ···
</application>
```

Add the following permission and ensure it is dynamically requested at runtime:
```
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```

Compile a debug package or enable the debug setting in AndroidManifest.xml:

<application
     android:debuggable="true"
     ···
     >
     ···
</application>

Dynamic switching

Scan the QR code to download the mPaaS Settings app.
After installation, the icon for the mPaaS Settings app appears as follows:
Copy the config file that you downloaded from the mPaaS console to your phone's SD card or internal storage.
Add an environment. Use the mPaaS Settings app to add the config file to the list.
1. Open the mPaaS Settings app.
2. On the Environment List page, tap Add Environment Configuration File at the bottom.
3. Find the environment configuration file you want to add.
4. Add the files for the production and staging environments to the environment list.
Switch the environment.
1. Select an environment from the list and tap Switch to set it as the current environment.
2. Start the app for this environment. If test requests are sent successfully, the environment switch is successful.
  If you switch to another environment and restart the app, the system may report a 3000 error. This error occurs because the operationType from the previous environment does not exist in the new environment, which confirms that the switch was successful.