让你的应用记住数据：State SDK 使用指南

问题：一刷新就全没了

你用 AI 做了个很棒的应用 — 一个测验、一个游戏、一个实用工具。别人用得挺开心，然后关掉了标签页。再打开的时候，什么都没了。最高分？没了。设置？没了。写了一半的东西？也没了。

网页应用默认就是这样的。但不一定非得这样。

解决方案：gapp.so 的 State SDK

在 gapp.so 上发布的每个应用都自带云端存储系统 — 不用搭后端、不用配数据库、不用申请任何密钥。你的应用只要几行代码就能存取数据。

SDK 会自动注入到你的应用中，通过 gapp.state 就能调用。不需要安装任何东西。

怎么加到你的应用里

把下面这段话发给你的 AI 编程助手（Claude Code、Cursor、Gemini 等）：

> "用 gapp.so 的 state SDK 来保存和加载用户数据，文档在这里：https://gapp.so/ai-sdk-prompt.md"

就这一句话。AI 助手会读文档，然后帮你把存储功能接好。

想说得更具体一点？可以这样跟它说：

• *"保存用户偏好设置，关掉再打开还在"*
• *"加一个最高分系统，记住每个用户的最好成绩"*
• *"每隔几秒自动保存用户正在编辑的内容"*
• *"做一个所有用户都能看到的全局排行榜"*

能做什么？

给每个用户存私有数据

每个用户有自己独立的存储空间，适合存：

• 偏好设置 — 主题、语言、字体大小
• 进度 — 游戏存档、已完成的关卡、解锁的成就
• 个人内容 — 草稿、笔记、自定义配置

// 保存
await gapp.state.set('preferences', { theme: 'dark', lang: 'zh' })

// 读取
const prefs = await gapp.state.get('preferences')

所有用户共享的数据

需要排行榜？共享计数器？协作空间？用 global 作用域：

// 读取排行榜
const scores = await gapp.state.global.get('leaderboard') || []

// 加一条新记录
scores.push({ name: '玩家1', score: 9500 })
scores.sort((a, b) => b.score - a.score)
await gapp.state.global.set('leaderboard', scores.slice(0, 100))

零代码自动同步

最省事的办法：如果你的应用已经用了 localStorage（AI 助手大概率已经帮你用了），gapp.so 会自动把它同步到云端。用户换个设备登录，数据还在 — 你一行代码都不用改。

// 这就已经能用了 — gapp.so 会自动同步
localStorage.setItem('gameProgress', JSON.stringify(progress))

三种存储范围

默认情况下，SDK 会自动选择：登录用户用 User 范围，匿名用户用 Session 范围。除非你有特殊需求，否则不用操心这个。

实际例子

记住答题进度的测验应用

window.addEventListener('gapp:ready', async () => {
  // 加载上次做到哪了
  const progress = await gapp.state.get('quizProgress') || {
    currentQuestion: 0,
    correctAnswers: 0,
    totalAnswered: 0
  }
  startQuiz(progress)
})

// 每回答一题
async function onAnswer(isCorrect) {
  progress.totalAnswered++
  if (isCorrect) progress.correctAnswers++
  progress.currentQuestion++
  await gapp.state.set('quizProgress', progress)
}

自动保存的画板应用

// 改动后每 2 秒自动保存
let saveTimer
canvas.addEventListener('change', () => {
  clearTimeout(saveTimer)
  saveTimer = setTimeout(async () => {
    await gapp.state.set('canvas', canvas.toJSON())
  }, 2000)
})

// 打开时恢复
const saved = await gapp.state.get('canvas')
if (saved) canvas.loadFromJSON(saved)

容量限制

对大多数应用来说这些完全够用。如果数据量比较大，可以把数据拆分到多个键里存储。

获取用户信息

SDK 还能获取用户身份信息：

if (gapp.user.isAuthenticated()) {
  const name = gapp.user.getName()
  const avatar = gapp.user.getAvatarUrl()
  showWelcome(name, avatar)
}

可以用来做个性化体验 — 显示欢迎语、在排行榜上显示用户名、或者根据用户身份调整界面。

本地测试

想在发布前测试数据保存功能？用本地开发模式：

1. 在 管理后台 > 创作者工具 获取开发令牌
2. 把开发脚本加到 HTML 里
3. State SDK 在本地会用 localStorage 模拟 — 接口一样，不需要服务器

具体步骤在 AI SDK 文档 里。

快速参考

完整文档

• State SDK 文档 — 完整 API 参考和交互式示例
• AI SDK 参考文档 — AI 编程工具专用的精简版文档
• 创作者指南 — gapp.so 全部功能的总览