丹木双语输入法开发复盘:iOS 键盘扩展、离线学习、广告接入与上架后的问题处理
丹木双语输入法的核心体验,是在用户输入拼音时,把英语释义放在中文候选旁边,让日常打字顺带成为一次词汇接触。要把这个想法做成可以上架的 iOS 产品,需要同时处理输入引擎、Keyboard Extension、主 App、广告和隐私声明。
项目最初围绕青简的 iOS 移植展开,随后逐步形成自己的名称、配色、图标和主 App。开发过程中出现过模拟器连接超时、候选汉字顶部遮挡、TestFlight 广告短暂出现后消失,以及审核要求补充追踪说明等问题。这些问题分属不同层面,处理时需要先把边界分清楚。
本文中的应用标识、广告标识、域名和本机路径均使用占位符。配置示例中的 <APP_BUNDLE_ID>、<PUBLISHER_ID> 等内容,需要替换为自己项目的实际值。
输入法在其他 App 中到底怎样运行?
在微信、Safari、备忘录等 App 中,丹木通过 iOS 的 Keyboard Extension 显示。主 App 负责设置、词库管理和使用引导,实际打字发生在键盘扩展区域。
这个边界直接决定了产品结构。用户在微信聊天时,上方仍然是微信的聊天界面,下方才是丹木键盘。键盘可以展示拼音、候选和释义,也可以把选中的中文插入当前输入框,但宿主 App 的聊天布局不属于键盘能够修改的范围。
工程可以分成两个入口:
丹木双语输入法
│
├── iOS 主 App
│ ├── 键盘启用引导与输入体验
│ ├── 设置
│ ├── 学习
│ ├── 词库管理
│ ├── 生词本
│ └── 隐私与数据管理
│
└── Keyboard Extension
├── 拼音输入
├── 中文候选
├── 候选英语释义
├── 中文上屏与退格
├── 英文直输
└── 本地学习
例如,用户在主 App 中体验输入 kaifa,键盘出现“开发”等候选,并在候选旁显示英语释义。点选候选后,输入框得到中文,释义继续留在键盘界面中,帮助用户理解词义。
主 App 的输入体验页只是一个测试入口。键盘还需要在不同宿主 App、不同输入框之间保持正确行为,因此验收不能停留在主 App 的单个页面上。
为什么要先做最小键盘,再开发完整功能?
最小 Keyboard Extension 用于验证真实输入路径能否走通。双语候选、中文上屏、退格和英文直输能够运行之后,才有基础继续加入词库、学习和管理功能。
最初的技术路线是:
Rust 输入核心
↓
最小 iOS FFI 桥接原型
↓
Swift
↓
UIKit Keyboard Extension
其中容易被低估的工作,是确认桌面项目的源码结构是否适合移动端。仓库里存在平台无关的核心模块,并不等于整个 Cargo workspace 都能直接构建到 iOS。
P0 阶段需要回答的问题很具体:
| 检查对象 | 需要回答的问题 | 对后续开发的影响 |
|---|---|---|
| Cargo workspace | 实际包含哪些成员,各成员如何依赖 | 决定需要构建哪些模块 |
qingjian-core |
如何创建引擎、输入拼音和取得候选 | 决定 Swift 侧调用方式 |
qingjian-dictionary |
词库如何加载、查询和管理 | 影响资源打包与启动过程 |
| 平台依赖 | 是否依赖桌面系统能力 | 决定哪些代码需要隔离 |
| iOS 构建 | 能否针对目标架构完成检查和构建 | 判断移植路线是否成立 |
| FFI 边界 | 参数、字符串和结果如何跨语言传递 | 影响稳定性与维护成本 |
验证目标包含 aarch64-apple-ios,也包含模拟器环境。设备目标构建、模拟器构建和模拟器中的实际输入,应当分别记录结果。
我更看重这个阶段留下的证据。源码检查、构建输出和真实输入结果,各自应该对应明确结论。没有实际完成的构建,就不应写成“已经通过”。
最小集成阶段已经报告完成的模拟器测试,覆盖了双语候选、中文上屏、退格和英文直输,并报告零失败。这个结果支持继续开发输入能力,后续仍需随着功能扩展增加测试范围。
P2 的完整输入能力应该补哪些部分?
P2 的重点是让输入能力能够持续使用,包括生产词库与释义表、后台串行引擎,以及本地学习和自动用户词库。候选列表是用户看到的结果,背后还要有稳定的状态管理和持久化过程。
项目选择先做键盘自己的本地学习,自动用户词库也保存在键盘本地容器中。用户启用键盘后,可以先使用基础输入和学习能力,无需为了这些功能开启“完全访问”。
主 App 管理用户词库,需要单独处理。键盘本地保存了学习记录,并不意味着主 App 已经能够读取和编辑同一份记录。主 App 管理或导入用户词库,需要另接共享容器。
一个容易混淆的使用场景是:
-
用户在键盘中多次选择某个候选。 -
键盘把学习结果保存在自己的本地容器。 -
用户打开主 App 的生词本。 -
生词本是否自动出现这个词,需要看两端是否已经建立数据共享关系。
产品文案因此需要分别描述“键盘本地学习”和“主 App 生词本”。两者都与词汇有关,实际的数据入口和保存位置却可能不同。
输入状态也要围绕具体操作检查。用户输入一半拼音后切换输入框,再返回原输入框,需要观察拼音和候选是否符合预期;选择中文后连续退格,则需要检查是否存在漏删、重复删除或状态残留。
只在一个输入框里反复输入同一个词,很难覆盖这些问题。
汉字候选顶部被遮挡,该怎样定位?
候选汉字顶部遮挡,需要结合汉字、英语释义和容器边界一起检查。截图能够证明显示异常,但不能直接确定是哪一条布局约束或绘制逻辑造成的。
丹木的候选卡片同时承载中文与英文。出现问题时,中文候选上方被遮挡,下面仍然能够看到英语释义。双层内容比单行候选更需要仔细检查可见范围。
复现时可以沿用出现问题的输入方式:
输入拼音:ni
检查内容:
中文候选是否完整
英语释义是否可读
候选区顶部是否存在覆盖
横向滚动后是否仍然遮挡
修复后的检查范围也应该扩大。需要继续观察不同候选、候选滚动、更多候选内容,以及中英文切换后的界面。
双语候选是丹木最显眼的差异,中文和英文都必须看得清楚。候选区一旦为了容纳释义而压缩中文,用户最基本的选词动作就会受到影响。
模拟器提示 DeviceKitError 4002,是键盘崩溃吗?
DeviceKitError 4002 的报错描述指向模拟设备的实时画面连接超时。仅凭这条错误,无法认定输入引擎或键盘扩展发生了崩溃。
当时出现的关键信息如下:
title:
Live device view took longer than expected to connect.
errorClass:
DeviceKitError
errorCode:
4002
TimeoutDuration:
60.0
FramebufferProviderStates:
none
错误信息中的设备标识与本次排查没有直接关系,公开记录时可以省略。
恢复建议要求确认设备已解锁、已连接并且屏幕处于点亮状态。错误中的交互状态仍然是连接中,也没有取得可用的画面提供状态。
遇到这种情况,应当分层验证:
| 观察项 | 要确认的内容 |
|---|---|
| 设备画面连接 | 模拟设备是否能够正常显示和交互 |
| 主 App 运行 | App 能否启动,输入体验页能否打开 |
| 键盘运行 | 能否切换到丹木,显示拼音和候选 |
| 输入结果 | 选词、退格和英文直输是否正确 |
例如,实时画面连接失败时,先处理连接状态;能够重新操作设备后,再重现键盘输入。若恢复画面后仍有丢字或闪退,再把问题收敛到输入逻辑。
这样可以避免在没有键盘故障证据时,反复修改输入引擎。
用户安装以后,怎样真正启用丹木软键盘?
安装主 App 后,还需要在 iOS 设置中添加丹木键盘,再通过输入框切换过去。主 App 的启用引导应当把这两个操作解释清楚。
项目中的引导路径是:
设置 → 通用 → 键盘 → 键盘 → 添加新键盘
添加“丹木双语输入法”后,回到 App 的输入体验页,点进输入框,长按地球键选择丹木。
完整体验流程可以这样组织:
-
启动主 App,阅读首次使用的隐私说明。 -
按照引导进入系统设置,添加丹木键盘。 -
回到输入体验页,点击第一个输入框。 -
长按地球键切换到丹木。 -
输入 kaifa,检查候选及英语释义。 -
选择“开发”,确认中文进入输入框。 -
使用退格,再切换英文直输。 -
点击第二个输入框,继续检查输入状态。
第二个输入框有实际用途。它让用户和开发者都能观察切换输入位置后的行为,帮助发现只在单个文本框里不容易遇到的问题。
启用引导也不宜只放一个“打开设置”按钮。用户需要知道打开设置后去哪里,以及返回 App 后怎样选中键盘,否则很容易把“键盘还没启用”理解成“输入法无法使用”。
主 App 应该放哪些功能,哪些可以暂时隐藏?
主 App 应当优先承载已经可用的设置、学习和词汇管理能力。尚未完成的功能入口,应当在发布版本中隐藏,避免用户进入后才发现无法操作。
早期产品设计包含学习语言、双拼方案、词库管理、生词本、输入统计和 AI 云联想配置。键盘侧还规划了英语、日语和西语译词,以及联想词等能力。
这些设计可以保留在开发规划中,公开介绍需要跟随实际版本。
| 功能 | 检查内容 |
|---|---|
| 键盘启用引导 | 用户能否按路径完成添加与切换 |
| 输入体验页 | 是否可以复现中文输入和英文直输 |
| 学习页面 | 设置项是否真正影响对应行为 |
| 生词本 | 能否查看、编辑和管理词条 |
| JSON 导入导出 | 文件入口与实际处理是否可用 |
| 隐私与数据管理 | 能否重新查看政策和管理使用选择 |
| AI 云联想等规划功能 | 未完成时是否仍暴露在界面中 |
项目后来明确转向“隐藏未完成功能”和“补充隐私与数据管理”。功能范围收窄后,更容易说明每个入口的用途,也更容易完成验证。
首页、学习和生词本三个 Tab,后来还成为广告接入的位置。这些页面因此又多了一项检查内容:广告出现时,页面自身的列表、按钮和底部导航是否仍然可用。
AdMob 应用 ID、广告位 ID 和 app-ads.txt 分别放什么?
AdMob 应用 ID 用于识别应用,广告单元 ID 对应具体广告位置,app-ads.txt 使用发布商 ID。配置时应按这几个层次逐项核对。
应用 ID 的示例结构为:
ca-app-pub-<PUBLISHER_ID>~<APP_ID>
广告单元 ID 的示例结构为:
ca-app-pub-<PUBLISHER_ID>/<AD_UNIT_ID>
项目中的广告位置包括:
| 广告位置 | 对应配置 |
|---|---|
| 首页横幅 | <HOME_BANNER_AD_UNIT_ID> |
| 学习横幅 | <LEARNING_BANNER_AD_UNIT_ID> |
| 生词本横幅 | <NOTEBOOK_BANNER_AD_UNIT_ID> |
| 开屏广告 | <APP_OPEN_AD_UNIT_ID> |
这些占位符仅用于说明配置关系,不能直接用于广告请求。
以首页为例,应用 ID 用来识别整个 App,首页横幅 ID 则对应首页中的横幅位置。学习页与生词本使用各自的广告单元,核对时也应分别检查,避免页面之间填错。
项目先使用测试 ID,之后才提供正式广告配置。环境选择需要在实际运行中核实,用户界面无需再显示“是否加载测试广告”之类的开发提示。
广告位置本身也出现过问题:首页广告被底部 Tab 遮挡。检查时需要观察广告区域、列表末尾和底部导航之间的关系。广告请求成功后,还要确认它在屏幕上完整可见。
后来提出把广告与列表融合,这个方向更贴合主 App 的页面结构。验收时仍然要观察广告加载前后列表是否发生异常变化,以及底部内容能否正常访问。
TestFlight 广告只闪一下,能据此判断正式广告失败吗?
广告短暂出现后消失,说明当前展示行为存在异常,但还不能单独确定原因。需要把测试 ID、正式 ID、隐私选择和页面显示过程放在同一次复现中检查。
这个问题曾在 TestFlight 安装后出现。当时正式广告的实际表现仍有待确认,因此不能把测试环境的现象直接写成正式广告已经正常,或者正式广告一定失败。
复现记录至少应该包含这些内容:
安装来源:TestFlight
构建号:<BUILD_NUMBER>
页面:<AD_PLACEMENT>
使用的广告配置:测试或正式
用户的隐私选择:明确记录
实际现象:出现时机、持续情况、消失后的页面状态
首页广告被 Tab 遮挡与开屏广告短暂消失,表面上都像“广告没显示”,实际应分别重现。前者已经有可见的遮挡位置,后者还需要确认展示流程。
我的判断是,广告问题不适合用一句“换正式 ID 就好了”收尾。配置、同意状态和展示位置都可能参与最终结果,至少要在相同构建、相同页面和相同操作下复测,才能比较修改前后的表现。
Firebase 显示 Analytics 已启用,配置文件为什么还是 false?
Firebase 控制台显示 Google Analytics 已启用,与下载文件中的 IS_ANALYTICS_ENABLED 为 false,是需要继续核对的两个状态。项目侧已经显示启用时,排查就应当继续转向应用配置与客户端验证。
项目选择接入的 Firebase 功能是 Analytics 和 Crashlytics。配置文件使用:
GoogleService-Info.plist
应用更名和 Bundle ID 调整后,需要替换对应应用的配置文件。公开说明可以使用下面的占位形式:
Bundle ID:
<APP_BUNDLE_ID>
配置文件路径:
/path/to/GoogleService-Info.plist
核对重点是当前工程、当前应用身份和当前配置文件是否对应。不能只盯着一个布尔值,也不能用控制台存在 Analytics 页面来证明客户端已经完成统计验证。
| 检查项 | 需要核对的内容 |
|---|---|
| 应用名称 | 是否为当前发布名称 |
| Bundle ID | 是否为当前应用标识 |
| Firebase 配置 | 是否已经替换为对应应用的文件 |
| Analytics | 是否完成客户端使用验证 |
| Crashlytics | 是否完成崩溃报告接入验证 |
| 键盘扩展 | 是否保持与主 App 的 SDK 边界 |
丹木的产品边界中,AdMob、Firebase Analytics 和 Crashlytics 位于主 App,键盘扩展不接入这些 SDK。介绍隐私时,需要明确这个范围。
接入广告和统计以后,隐私政策应该怎样写?
隐私政策需要描述当前实际处理的数据、使用的第三方服务,以及用户能够作出的选择。其他 App 的政策可以参考结构,正文应当改写成输入法自己的情况。
项目曾以另一款 App 的隐私政策作为编写参考。参考政策涉及摄像头、麦克风、相册和视频文件,这些段落不能只替换应用名称后用于输入法。
丹木需要围绕自己的数据边界组织说明:
-
拼音输入和候选英语释义的离线使用。 -
键盘学习数据的本地保存。 -
主 App 生词本及导入导出功能。 -
主 App 中的广告服务。 -
Analytics 与 Crashlytics。 -
首次使用时的隐私确认,以及设置中的政策入口。
首次安装弹窗需要与政策内容衔接。弹窗里写了什么、用户同意或拒绝后发生什么、哪些服务会随后开始运行,应当能够在实际安装中观察到。
公开隐私政策地址可以在文档模板中写为:
https://<DEVELOPER_DOMAIN>/<PRIVACY_POLICY_PATH>
发布时,再填写实际可访问的政策页面。
政策页面、应用内说明和 App Store Connect 的数据声明,需要随着功能变化一起更新。只改其中一个位置,用户与审核人员仍然可能看到不同的描述。
ATT 被审核追问以后,代码和后台需要怎样核对?
ATT 审核问题要同时检查代码行为和 App Store Connect 声明。审核人员找不到权限请求时,产品需要明确实际采用的方案,并提供对应的真实设备流程。
审核反馈指出,应用使用了 AppTrackingTransparency 框架,但在审核环境中没有找到权限请求。要求补充的录屏流程包括:
全新安装或重置追踪权限
↓
启动 App
↓
展示追踪权限请求
↓
继续展示后续使用流程
审核反馈同时给出了另一条处理路径:如果应用不追踪用户,就需要更新后台隐私信息,取消追踪声明。
后续构建围绕取消追踪展开修改,并继续核对 SDK 涉及的数据。后台已确认的诊断数据调整方案包括:
| 数据类型 | 用途 |
|---|---|
| 崩溃数据 | 分析、App 功能 |
| 性能数据 | 第三方广告、分析、App 功能 |
| 其他诊断数据 | 第三方广告、分析、App 功能 |
这几类数据的调整方案均为“不用于追踪”,当时暂时保留了“与用户身份关联”的设置。设备标识、广告数据、产品交互和大致位置还需要继续核对,性能数据的关联状态也曾被单独提出复核。
“采集什么”“用于什么”“是否关联身份”和“是否追踪”,需要分别回答。取消追踪,不等于可以把所有数据改成不收集;接入某个 SDK,也不能代替对当前配置和实际用途的检查。
提交新构建后,审核备注应明确针对上一次拒绝原因做了什么修改,录屏也要展示对应构建的流程。旧录屏搭配新构建,会让已经调整过的问题再次变得难以判断。
上架前的审核材料怎样准备才完整?
审核材料应当让审核人员从启动 App 开始,完整复现核心功能。丹木的核心流程可以围绕启用键盘、输入拼音、查看释义和中文上屏展开,再补充主 App 的词汇管理。
首次审核要求提供真实设备录屏,设备运行最新操作系统。录屏必须从启动 App 开始,展示典型使用路径。
适合丹木的演示顺序是:
-
启动 App,展示首次使用流程。 -
说明键盘添加路径。 -
回到输入体验页,切换到丹木。 -
输入拼音,展示中文候选及英语释义。 -
选择候选,演示中文上屏。 -
演示退格、英文直输和输入框切换。 -
打开学习页与生词本。 -
展示设置中的隐私入口。
审核说明还需要写清楚应用目的、目标人群、主要功能访问方式、第三方服务,以及功能是否存在地区差异。涉及账号、付费或用户生成内容时,还需要提供对应流程,所有说明都应按照实际版本填写。
截图需要展示实际 App 的使用状态。项目准备过多组 iPhone 尺寸素材,并补充了必须上传的 13 英寸 iPad 截屏。
录屏解释完整流程,截图展示应用界面,构建测试用于确认功能运行。这些材料应当能对应到同一个发布版本。
公开分享审核经历时,联系人、邮箱、电话、提交编号和设备唯一标识可以省略,保留拒绝原因和处理过程即可。
第三方代码和数据的许可材料该怎样整理?
许可材料需要分别整理代码、名称与 Logo、随包数据。青简的代码许可信息已经明确,名称与 Logo 不包含在代码授权中,数据还有各自的来源和许可。
青简代码采用的许可标识为:
GPL-3.0-or-later
这项信息不能直接概括工程中所有资源的使用条件。整理材料时,应当把不同对象列出来:
| 对象 | 整理内容 |
|---|---|
| 上游代码 | 项目、使用部分及许可 |
| 名称与 Logo | 是否使用,以及对应授权情况 |
| 随包数据 | 来源与各自许可 |
| 自有图标与配色 | 对应的产品资源 |
| 第三方 SDK | 接入范围与用途 |
应用更名和重新设计图标,是产品识别层面的工作。代码与数据的许可整理仍然需要单独完成。
审核说明涉及第三方材料时,应根据工程实际使用的内容回答。已经替换的资源与仍然随包发布的资源,要在清单中分清楚。
app-ads.txt 浏览器能打开,为什么 AdMob 还无法验证?
浏览器能打开文件,只能确认当前访问可以取得内容。Google 是否已经找到并验证,需要查看 AdMob 中的验证状态,应用 ID 本身无法证明抓取成功。
文件内容的示例结构为:
google.com, pub-<PUBLISHER_ID>, DIRECT, <CERTIFICATION_AUTHORITY_ID>
实际文件中的各字段,应使用 AdMob 账号提供的完整内容。公开文章中的占位符需要替换后才能使用。
文件应放在开发者网站根目录,地址结构如下:
https://<DEVELOPER_DOMAIN>/app-ads.txt
AdMob 的验证提示曾指出,文件可能已经存在,但内容与账号信息不一致。检查时应逐项核对发布商 ID、DIRECT 和最后一段认证机构 ID。
同时确认开发者网站域名与 App Store 中填写的域名对应。
操作上,可以进入 AdMob 的应用页面查看 app-ads.txt 状态,在页面提供检查更新入口时重新检查。文件内容正确、网站可访问和后台验证通过,需要分别确认。
Product Hunt 的资料填完,就算正式发布了吗?
Product Hunt 的草稿与正式 Launch 是不同状态。丹木已经完成发布资料填写并创建草稿,但草稿页显示尚未安排发布时间。
填写时使用的产品名称是:
Danmu Bilingual Keyboard
标语为:
Type Chinese. Learn English as you go.
介绍围绕离线拼音输入、候选英语释义、本地学习和生词本展开。分类标签选择了:
Custom Keyboards
Education
Languages
媒体部分上传了应用图标,以及键盘、学习和生词本的功能截图。定价选为免费,并补充了 App Store 下载链接。
过程中曾出现 App Store 地址已关联现有产品的提示,相关情况已经发送给 Product Hunt 支持。正式安排 Launch 前,仍需要确认现有条目的情况,避免重复产品页。
公开复盘时,可以保留产品定位、文案和操作过程,省略账号标识、后台编辑地址及支持对话中的联系方式。
发布工作的最后一步,是查看页面上的实际状态。表单显示必填项完成,说明资料已经齐全;草稿显示未排期,就应当按未排期记录。
现在检查丹木项目,先做哪些事最有用?
优先检查用户能够直接遇到的输入、隐私和广告流程,再核对发布材料中的描述。每项检查都应记录构建号和实际结果,避免把计划功能混进已完成功能。
实用操作清单
-
在系统设置中添加丹木,并通过地球键切换成功。 -
输入 kaifa,确认中文候选、英语释义和中文上屏。 -
检查退格、英文直输和输入框切换。 -
重现候选汉字顶部遮挡,验证修改后的显示。 -
确认键盘学习数据的保存范围。 -
检查主 App 生词本的编辑与 JSON 导入导出。 -
核对 Bundle ID 与 Firebase 配置文件。 -
在 TestFlight 中分别检查各广告位置。 -
对照代码行为复核隐私政策和后台声明。 -
使用对应构建重新录制真实设备演示。 -
在 AdMob 查看 app-ads.txt验证状态。 -
在 Product Hunt 区分草稿、排期与正式 Launch。
一页速览
| 项目 | 核对重点 |
|---|---|
| 应用名称 | 丹木双语输入法 |
| 英文名称 | Danmu Bilingual Keyboard |
| 应用身份 | 使用当前项目的实际 Bundle ID |
| 核心体验 | 中文候选旁显示英语释义 |
| 输入载体 | iOS Keyboard Extension |
| 学习方案 | 键盘本地学习与自动用户词库 |
| 主 App 服务 | AdMob、Analytics、Crashlytics |
| 广告配置 | 分别核对应用 ID 和各广告单元 |
| 广告展示 | 按位置与配置复测 TestFlight 闪现现象 |
| 广告文件验证 | 以 AdMob 后台状态确认 |
| Product Hunt | 草稿创建后继续核对排期状态 |
| 公开文档 | 隐去账号、联系方式和本机路径 |
FAQ
安装 App 后为什么还看不到丹木键盘?
需要先在系统设置中添加丹木,再在输入框中长按地球键切换。
使用本地学习需要开启完全访问吗?
当前采用的键盘本地学习方案无需完全访问。主 App 管理共享词库需要另行接入共享容器。
汉字候选顶部遮挡,截图能确定原因吗?
截图能确认显示异常,具体原因仍需检查候选区布局和可见范围。
DeviceKitError 4002 能证明键盘崩溃吗?
不能。该报错描述的是实时设备画面连接超时,需要恢复设备交互后继续验证键盘。
Analytics 控制台已启用,是否说明客户端统计成功?
仍需核对当前 Bundle ID、配置文件和客户端验证结果。
app-ads.txt 能打开,是否代表 Google 已验证?
还需要在 AdMob 中确认已找到并验证的状态。
Product Hunt 显示草稿,是否已经完成 Launch?
尚未完成正式 Launch。草稿页还需要安排发布,并确认已有产品条目的归属。

