位置与生物识别

Mini App 提供位置信息获取和生物识别认证功能。

LocationManager

位置管理器，用于获取用户的地理位置。通过 Telegram.WebApp.LocationManager 访问。Bot API 8.0+

属性

属性	类型	描述
isInited	Boolean	位置管理器是否已初始化
isLocationAvailable	Boolean	设备是否支持位置服务
isAccessRequested	Boolean	是否已请求位置权限
isAccessGranted	Boolean	位置权限是否已授予

方法

init

Telegram.WebApp.LocationManager.init(callback)

初始化位置管理器。

参数	类型	必填	描述
callback	Function	否	初始化完成回调

getLocation

Telegram.WebApp.LocationManager.getLocation(callback)

获取当前位置。

参数	类型	必填	描述
callback	Function	是	回调函数，参数为 LocationData 对象，失败时为 null

openSettings

Telegram.WebApp.LocationManager.openSettings()

打开位置权限设置页面，引导用户授权。

示例

const locationMgr = Telegram.WebApp.LocationManager;

locationMgr.init(() => {
  if (locationMgr.isLocationAvailable) {
    locationMgr.getLocation((location) => {
      if (location) {
        console.log(`纬度: ${location.latitude}`);
        console.log(`经度: ${location.longitude}`);
        console.log(`精度: ${location.accuracy}m`);
      } else {
        console.log('无法获取位置');
      }
    });
  } else {
    console.log('设备不支持位置服务');
  }
});

LocationData

位置数据对象，由 LocationManager.getLocation() 返回。

字段	类型	描述
latitude	Float	纬度
longitude	Float	经度
altitude	Float | null	海拔高度（米），不可用时为 null
course	Float | null	移动方向（0-360°），不可用时为 null
speed	Float | null	移动速度（m/s），不可用时为 null
horizontal_accuracy	Float | null	水平精度（米）
vertical_accuracy	Float | null	垂直精度（米）
course_accuracy	Float | null	方向精度（度）
speed_accuracy	Float | null	速度精度（m/s）

BiometricManager

生物识别管理器，提供指纹和面部识别认证功能。通过 Telegram.WebApp.BiometricManager 访问。Bot API 7.2+

属性

属性	类型	描述
isInited	Boolean	管理器是否已初始化
isBiometricAvailable	Boolean	设备是否支持生物识别
biometricType	String	生物识别类型："finger"（指纹）、"face"（面部）或空字符串
isAccessRequested	Boolean	是否已请求生物识别权限
isAccessGranted	Boolean	生物识别权限是否已授予
isBiometricTokenSaved	Boolean	是否已保存生物识别 token
deviceId	String	设备唯一标识

方法

init

Telegram.WebApp.BiometricManager.init(callback)

初始化生物识别管理器。

参数	类型	必填	描述
callback	Function	否	初始化完成回调

requestAccess

Telegram.WebApp.BiometricManager.requestAccess(params, callback)

请求生物识别权限。

参数	类型	必填	描述
params	Object	否	参数
params.reason	String	否	请求权限的原因描述
callback	Function	否	回调函数，参数 (granted)

authenticate

Telegram.WebApp.BiometricManager.authenticate(params, callback)

发起生物识别认证。

参数	类型	必填	描述
params	Object	否	参数
params.reason	String	否	认证原因描述
callback	Function	否	回调函数，参数 (authenticated, token)

updateBiometricToken

Telegram.WebApp.BiometricManager.updateBiometricToken(token, callback)

更新存储在设备上的生物识别 token。

参数	类型	必填	描述
token	String	是	新的 token 值，传空字符串可删除
callback	Function	否	回调函数，参数 (updated)

openSettings

Telegram.WebApp.BiometricManager.openSettings()

打开生物识别权限设置页面。

示例

const bioMgr = Telegram.WebApp.BiometricManager;

bioMgr.init(() => {
  if (!bioMgr.isBiometricAvailable) {
    console.log('设备不支持生物识别');
    return;
  }

  console.log('生物识别类型:', bioMgr.biometricType);

  // 请求权限
  bioMgr.requestAccess({ reason: '用于身份验证' }, (granted) => {
    if (granted) {
      // 发起认证
      bioMgr.authenticate({ reason: '请验证身份' }, (authenticated, token) => {
        if (authenticated) {
          console.log('认证成功');
          if (token) {
            console.log('Token:', token);
          }
        } else {
          console.log('认证失败');
        }
      });
    }
  });
});

// 保存 token 以供下次使用
bioMgr.updateBiometricToken('my-secure-token', (updated) => {
  if (updated) {
    console.log('Token 已保存');
  }
});