Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

Enable and use environment variables

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

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

This guide helps you understand how environment variables work within mini programs, enable the environment feature for your platform, and use the feature in your own mini program development.

Note: This topic is intended for super apps. To guide merchants in using the feature, refer to Use environment variables (for merchants).

How environment variables work

The environment variable workflow within a mini program consists of three stages:

  • Development: Use the my.getEnvironmentVariables JSAPI in the mini program code to retrieve environment variables and reference them as needed.
  • Release: In Mini Program Platform, for each release to a specific target app and environment, users set the environment variable names and values that are specific to the current release.
  • Runtime: When the mini program runs within the target app and environment, it calls my.getEnvironmentVariables to access your configuration.

Note: 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.

Enable environment variables for your platform

This section helps you make the environment variable feature available for both your internal use and merchant use.

Before you begin

Download the following SDKs from our Download Center based on the opearting system your app runs on:

  • Android IAP MiniProgram SDK version 2.71.0 or later
  • iOS IAPMiniProgram SDK version 2.71.1 or later

Procedure

To enable the feature, take the following steps:

Step 1: Request the feature enablement and updated resource files

Contact our technical support to complete the following actions:

  • Enable the environment variable feature for your platform.
  • Update the resource files that are essential for your app's integration with the IAPMiniProgram SDK.

Step 2: Upgrade SDK integration

To make your app support this feature, follow these steps to upgrade your app's SDK integration:

  1. Download the updated resource files in Mini Program Platform. For detailed instructions, see Download app resources.
  2. Integrate the obtained SDKs into your app. For integration details, see the IAPMiniProgram SDK integration guide.
  3. During the SDK integration, add the updated resource files to your project. For detailed instructions, see the following quickstart guides:

Step 3: Enable merchant access

Merchants must be authorized first to access the my.getEnvironmentVariables JSAPI that retrieves the environment variable configuration. To grant merchants the authorization, follow these steps:

  1. In Mini Program Platform, click Features in the left navigation panel.
  2. Click Add Feature to create a new feature that includes the my.getEnvironmentVariables JSAPI. Set the feature's activation access according to your preferred approval process:
    • Select Direct access to let merchants add the feature to their mini program without requiring your approval.
    • Select Activation needed to require merchants to submit an activation request for your approval before they can add the feature.

For detailed instructions, see Create a feature.

  1. Share the feature name with merchants so they can add the correct feature to their mini program to enable the JSAPI access. You can share the name by updating the Use environment variables (for merchants) topic.

Use environment variables in your mini program

This section helps you use environment variables in your own mini program.

Before you begin

Ensure the following things:

  • Your mini program type is DSL.
  • You have enabled the environment variable feature.
  • Identify up to five environment variables and their corresponding values per environment.

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: