安全存储

SecureStorage 提供加密的本地安全存储服务，适用于存储敏感数据（如认证 token、密钥等）。数据经过加密后存储在设备上。通过 Telegram.WebApp.SecureStorage 访问。Bot API 8.0+

限制

项目	限制
最大条目数	10
键名最大长度	128 字符
值最大长度	2048 字符
键名字符	A-Z、a-z、0-9、_、-

方法

setItem

Telegram.WebApp.SecureStorage.setItem(key, value, callback)

安全存储一个键值对。

参数	类型	必填	描述
key	String	是	键名，1-128 字符
value	String	是	值，0-2048 字符
callback	Function	否	回调函数，参数 (error, success)

Telegram.WebApp.SecureStorage.setItem('auth_token', 'eyJhbGciOi...', (error, success) => {
  if (error) {
    console.error('安全存储失败:', error);
  } else {
    console.log('Token 已安全存储');
  }
});

getItem

Telegram.WebApp.SecureStorage.getItem(key, callback)

从安全存储中读取指定键的值。

参数	类型	必填	描述
key	String	是	键名
callback	Function	是	回调函数，参数 (error, value)

Telegram.WebApp.SecureStorage.getItem('auth_token', (error, value) => {
  if (error) {
    console.error('读取失败:', error);
  } else if (value) {
    // 使用 token
    apiClient.setToken(value);
  }
});

removeItem

Telegram.WebApp.SecureStorage.removeItem(key, callback)

从安全存储中删除指定键。

参数	类型	必填	描述
key	String	是	键名
callback	Function	否	回调函数，参数 (error, success)

clear

Telegram.WebApp.SecureStorage.clear(callback)

清除安全存储中的所有数据。

参数	类型	必填	描述
callback	Function	否	回调函数，参数 (error, success)

三种存储对比

特性	CloudStorage	DeviceStorage	SecureStorage
存储位置	云端	本地	本地（加密）
数据同步	跨设备	仅本地	仅本地
容量	1024 键 × 4KB	5 MB	10 键 × 2KB
安全性	普通	普通	加密
适用场景	用户偏好	缓存数据	敏感数据
最低版本	—	Bot API 8.0+	Bot API 8.0+

使用示例

const secureStorage = Telegram.WebApp.SecureStorage;

// 安全存储登录凭据
function saveCredentials(token, refreshToken) {
  secureStorage.setItem('access_token', token, (err) => {
    if (!err) {
      secureStorage.setItem('refresh_token', refreshToken);
    }
  });
}

// 读取登录凭据
function loadCredentials(callback) {
  secureStorage.getItem('access_token', (err, token) => {
    if (err || !token) {
      callback(null);
      return;
    }
    secureStorage.getItem('refresh_token', (err, refreshToken) => {
      callback({ token, refreshToken });
    });
  });
}

// 登出时清除凭据
function logout() {
  secureStorage.clear((err) => {
    if (!err) {
      console.log('凭据已清除');
      redirectToLogin();
    }
  });
}