Web inside SafeW

把 Web 应用，放进聊天界面

Mini App 是运行在 SafeW 客户端内的轻量 Web 应用。它保留 Web 开发效率，同时通过 JavaScript SDK 使用原生按钮、主题、存储、传感器与生物识别。

30+ WebApp 只读属性

30+ 界面、导航与数据方法

40+ 生命周期与交互事件

3 层 云端、设备与安全存储

01 / Experience model

Web 技术，原生体验

用户无需跳出聊天应用。Mini App 在 SafeW 内打开，并自动获得当前主题、视口与用户上下文。

SafeW Mini App •••

新建服务请求

在聊天中完成选择、填写与提交。

主题适配原生按钮安全存储触觉反馈

提交请求

原生控件

调用返回按钮、底部主按钮、设置按钮、弹窗与触觉反馈。

THEME

自动适配主题

读取明暗模式、15 个主题色参数、视口和安全区域。

DATA

可信上下文

使用签名后的 initData 获取用户、聊天与启动信息。

DEVICE

设备能力

按客户端支持情况使用传感器、定位与生物识别。

02 / Initialize

最小初始化只需要三步

引入 SDK、读取全局对象，再尽早调用 ready() 通知客户端页面已经准备完成。

引入 WebApp SDK

在 HTML 中加载 SafeW Web App JavaScript 文件。

获取 window.SafeW.WebApp

所有属性、方法、UI 组件和事件都从这个对象进入。

调用 ready() 与 expand()

通知客户端显示应用，并根据需要展开到最大可用高度。

HTML + JavaScript · initialize

<script src="https://oauth.safew.bot/js/safew-web-app.js"></script>
<script>
  const sw = window.SafeW.WebApp;

  sw.ready();
  sw.expand();

  sw.setHeaderColor("#171021");
  sw.enableClosingConfirmation();

  console.log(sw.initData);
  console.log(sw.colorScheme);
</script>

先检查版本，再调用新能力

全屏、方向锁定、分享与下载等能力存在最低客户端版本要求。调用前可使用 isVersionAtLeast(version) 判断。

03 / Native capabilities

客户端能力按场景组合

不需要一次使用全部能力。优先选择能缩短用户路径、减少跳转或增强安全性的模块。

界面与反馈

BackButton、BottomButton、SettingsButton、HapticFeedback 与原生弹窗。

VIEW

视口与外观

主题参数、CSS 变量、安全区域、全屏、展开与屏幕方向控制。

EVENT

事件系统

监听主题、视图、按钮和生命周期变化，用 onEvent 与 offEvent 管理订阅。

NAV

链接与分享

打开外部链接、SafeW 内链接，分享消息、故事或下载文件。

SENSOR

传感器

在支持的设备上使用加速度计、陀螺仪和设备方向。

BIO

位置与生物识别

在用户授权后使用位置、指纹或面部识别相关能力。

04 / Storage

三类存储，解决不同问题

不要用同一种存储承载所有数据。跨设备状态、本地缓存和敏感信息应分别处理。

CloudStorage 最多 1024 个键值对

适合需要跨设备同步的轻量偏好与业务状态。

DeviceStorage 5 MB 本地持久化

适合设备缓存、草稿和无需跨设备同步的数据。

SecureStorage 最多 10 项加密存储

适合少量敏感值；仍应避免把 Bot Token 放入前端。

05 / Data flow

Mini App、Bot 与服务端如何协作

Mini App 负责交互，Bot 负责聊天消息，你的服务端负责业务逻辑和安全验证。

01 / MINI APP

收集用户操作

表单、按钮、主题与设备能力

02 / SERVER

验证与处理

校验 initData 并执行业务逻辑

03 / BOT

回到聊天

发送结果、通知或下一步操作

JavaScript · events and sendData

const sw = window.SafeW.WebApp;

sw.onEvent("themeChanged", () => {
  document.documentElement.dataset.theme = sw.colorScheme;
});

sw.MainButton.setText("提交");
sw.MainButton.onClick(() => {
  sw.sendData(JSON.stringify({ action: "submit" }));
});
sw.MainButton.show();

sendData 有启动场景限制

该方法发送 1–4096 字节字符串，调用后 Mini App 会关闭，并通过 web_app_data 服务消息传递给 Bot。它仅适用于支持该方式的启动入口。

06 / Trust boundary

客户端数据必须由服务端验证

initDataUnsafe 适合界面展示，不应直接作为可信身份依据。真正的授权判断应使用原始 initData 在服务端验签。

STEP 01 提取 hash 与参数

STEP 02 字段按字母排序

STEP 03 生成 data_check_string

STEP 04 HMAC-SHA256 计算

STEP 05 常量时间比对

HMAC

Bot 服务端验证

先以 “WebAppData” 对 Bot Token 做 HMAC-SHA256 得到 secret_key，再验证数据 hash。

第三方验证

较新客户端可使用 Ed25519 平台公钥验证签名，适合无法持有 Bot Token 的第三方服务。

✓

安全检查

在服务端验证；检查 auth_date，建议有效期不超过 1 小时；使用常量时间比较；保护 Bot Token；注意 Base64 中 “+” 被错误解码为空格的问题。