---
title: MiniApp Custom Configuration
---

## Overview

The capability configuration feature allows developers to separate business and technical configurations from the miniapp code and manage them centrally in the cloud. This approach solves the maintenance difficulties and compliance issues caused by hardcoded configurations in the code, enabling centralized management and dynamic updates of configurations.

## Key Features

- **Cloud-based Configuration Management**: Configuration information is stored in the cloud and supports dynamic updates
- **Multiple Configuration Types**: Supports four configuration types: links, booleans, numbers, and strings
- **Hierarchical Configuration**: Supports template configurations and instance configurations, with instance configurations having higher priority
- **Multi-region Support**: Supports differentiated configuration management for different regions
- **Cross-platform Support**: Applicable to panel miniapps, industry miniapps, and smart miniapps

## Feature Modules

### Developer Console Configuration Management

In the Tuya Developer Platform console, you can perform the following configuration management operations:

#### 1. Template Configuration Creation

- **Permission Restrictions**: Only templates can create configurations; instances cannot create configurations directly
- **Configuration Parameters**: Each configuration item needs to set the following parameters:
  - `code`: Unique identifier for the configuration item
  - `Description`: Detailed description of the configuration item
  - `Type`: Data type of the configuration item
  - `Default Value`: Default value of the configuration item
  - `Instance Editable`: Controls whether the configuration can be edited in instances

#### 2. Configuration Types

The system supports the following four configuration types:

| Type | Description | Example |
|------|-------------|---------|
| Link | URL address configuration | `https://example.com/api` |
| Boolean | Switch-type configuration | `true` or `false` |
| Number | Numeric type configuration | `100`, `3.14` |
| String | Text type configuration | `"Hello World"` |

#### 3. Configuration Exposure Mechanism

- **Exposure Conditions**: Only configurations set as "Instance Editable" will be displayed in instances
- **Applicable Scope**: Panel miniapps and industry application miniapps cannot be exposed to instances
- **Priority**: Instance configuration > Template configuration (instance configuration takes precedence, template configuration serves as fallback)

#### 4. Multi-region Configuration

- **Region Support**: Supports differentiated configurations for different regions
- **Configuration Method**: Currently does not support one-click synchronization across multiple regions; manual configuration for each region is required
- **Management Convenience**: Different configuration values can be set for different regions

## Configuration Management Guide

### 1. Creating Configurations

1. Log in to [Tuya Developer Platform](https://platform.tuya.com/miniapp/)
2. Go to the miniapp management page
3. Select the corresponding template miniapp
4. Enter the "Capability Configuration" management page
5. Click the "Add Configuration" button
6. Fill in the configuration information:
   - **Configuration Code**: English identifier, recommended to use underscore naming convention
   - **Configuration Description**: Detailed description of the configuration's purpose and function
   - **Configuration Type**: Select the appropriate data type
   - **Default Value**: Set a reasonable default value
   - **Instance Editable Switch**: Choose whether to enable editing functionality for instances based on requirements

### 2. Managing Configurations

#### 2.1 Modifying Configurations
- Template configurations can be modified directly
- Instance configurations have higher priority and will override template configurations
- Configuration changes take effect the next time the miniapp is opened

#### 2.2 Deleting Configurations
- Ensure that relevant references have been removed from the miniapp code before deleting configurations
- Deletion cannot be undone; please operate with caution

#### 2.3 Multi-region Management
- Different regions can have different configuration values
- Each region needs to be configured separately
- It is recommended to establish configuration documentation to record configuration differences across regions

### 3. Usage Methods

For details, please refer to the [Custom Configuration API](/en/miniapp/develop/ray/api/base/container/getCustomConfig) documentation.

#### Ray

```javascript
// @ray-js/ray (version >= 1.7.22) provides the getCustomConfig API for obtaining custom configuration information
import { getCustomConfig } from '@ray-js/ray';
 
getCustomConfig({
  success: (res) => {
    console.log('Get configuration success:', res);
    
    // Use configuration directly
    const timeout = res.timeout || 5000;
    const enableDebug = res.enableDebug || false;
    const helpUrl = res.helpUrl || '';
  },
  fail: (err) => {
    console.error('Get configuration failed:', err);
  }
});
```

#### Native MiniApp

```javascript
// Base library (version >= 2.29.0) provides the ty.getCustomConfig method for obtaining custom configuration information
ty.getCustomConfig({
  success: (res) => {
    console.log('Get custom configuration success:', res);
    const customConfigs = res || {};
    
    // Use configurations
    const apiEndpoint = customConfigs.api_endpoint || 'https://default-api.com';
    const enableDebug = customConfigs.enable_debug || false;
    const maxRetryCount = customConfigs.max_retry_count || 5;
    
    // Apply to business logic
    this.setData({
      apiUrl: apiEndpoint,
      debugMode: enableDebug,
      retryLimit: maxRetryCount
    });
  },
  fail: (err) => {
    console.error('Get custom configuration failed:', err);
    // Use default configurations
    this.setData({
      apiUrl: 'https://default-api.com',
      debugMode: false,
      retryLimit: 5
    });
  }
});
```

## Important Notes

### 1. Compatibility
- Base library version must be >= 2.29.0
- Older versions of miniapps may not support this feature

### 2. Performance Optimization
- Configuration data should be loaded and cached when the application starts
- Avoid frequent calls to the `ty.getCustomConfig()` interface
- Set reasonable default values for configurations to ensure the miniapp can run normally even when network exceptions occur

### 3. Security Considerations
- Sensitive information (such as keys, passwords) should not be passed through custom configurations
- Configuration values are transmitted in plain text; please pay attention to data security
- It is recommended to encrypt important configurations