Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

Use environment variables

Environment variables help you manage your mini program's configuration safely and effectively. This feature offers the following benefits:

  • Security: Keep sensitive data (e.g., API keys) out of your codebase.
  • Flexibility: Easily change configuration for different environments without rewriting code.
  • Maintainability: Simplify your code and reduce environment-specific errors.

Note: This topic is intended for merchants. If you are the super app, refer to Enable and use environment variables (for super apps).

How environment variables work

The environment variable workflow consists of the following stages:

  • Development: Use the my.getEnvironmentVariables JSAPI in your code to retrieve environment variables and reference them based on your needs.
  • Release: Each time you start a version release to a specific target app and environment, set the environment variable names and values that are specific to the current release.
  • Runtime: When your mini program runs within the target app and environment, it calls my.getEnvironmentVariables to access your configuration.

Note:

  • The my.getEnvironmentVariables JSAPI requires authorization via a super app feature. You must add the specific feature to your mini program to enable the JSAPI access.
  • For security, the environment variable details are encrypted in the JSAPI response. The mini program's runtime environment handles decryption automatically and makes the values available to your code.

Before you begin

Ensure the following things:

  • Your mini program type is DSL.
  • The super app has enabled the environment variable feature (you will see the Environment Variables field when configuring a release if it is enabled).
  • Identify up to five environment variables and their corresponding values per environment.
  • Obtain from the super app the name of the feature that is required to enable access to the my.getEnvironmentVariables JSAPI. Then, add the specific feature to your mini program. For instructions, see Add features.

Procedure

To use environment variables, take the following steps:

Step 1: Use environment variables during development

In your mini program project in Mini Program Studio (the IDE):

  1. Open your project's details page and check the Use Lib v2.0 option to enable the appX2 basic library for environment variable support.
  2. In your mini program code, call the my.getEnvironmentVariables JSAPI to retrieve the environment variable values you will set later.
  3. Reference the environment variables based on your business needs.

Note:

  • Fallback implementation: The my.getEnvironmentVariables JSAPI call fails if an end-user is running an older version of the super app that does not support the environment variable feature. It is recommended to implement fallback logic to ensure your mini program functions properly.
  • IDE preview limit: Environment variables cannot be previewed in the IDE. They are injected only when your mini program runs within the target app and environment after release. However, you can test fallback logic in the IDE.

Step 2: Set environment variables during release

  1. Upload your mini program code as a new version to Mini Program Platform. For detailed instructions, see Upload mini program code and version.
  2. In Mini Program Platform, start the release process for your new version. For detailed instructions, see Release a mini program.
  3. In the release-specific configuration dialog, locate the Environment Variables field and enter the variable names and their values specific to the target app and environment. For more information, see the following topics: