丹木双语输入法开发复盘: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 管理或导入用户词库,需要另接共享容器。

一个容易混淆的使用场景是:

  1. 用户在键盘中多次选择某个候选。
  2. 键盘把学习结果保存在自己的本地容器。
  3. 用户打开主 App 的生词本。
  4. 生词本是否自动出现这个词,需要看两端是否已经建立数据共享关系。

产品文案因此需要分别描述“键盘本地学习”和“主 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 的输入体验页,点进输入框,长按地球键选择丹木。

完整体验流程可以这样组织:

  1. 启动主 App,阅读首次使用的隐私说明。
  2. 按照引导进入系统设置,添加丹木键盘。
  3. 回到输入体验页,点击第一个输入框。
  4. 长按地球键切换到丹木。
  5. 输入 kaifa,检查候选及英语释义。
  6. 选择“开发”,确认中文进入输入框。
  7. 使用退格,再切换英文直输。
  8. 点击第二个输入框,继续检查输入状态。

第二个输入框有实际用途。它让用户和开发者都能观察切换输入位置后的行为,帮助发现只在单个文本框里不容易遇到的问题。

启用引导也不宜只放一个“打开设置”按钮。用户需要知道打开设置后去哪里,以及返回 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 开始,展示典型使用路径。

适合丹木的演示顺序是:

  1. 启动 App,展示首次使用流程。
  2. 说明键盘添加路径。
  3. 回到输入体验页,切换到丹木。
  4. 输入拼音,展示中文候选及英语释义。
  5. 选择候选,演示中文上屏。
  6. 演示退格、英文直输和输入框切换。
  7. 打开学习页与生词本。
  8. 展示设置中的隐私入口。

审核说明还需要写清楚应用目的、目标人群、主要功能访问方式、第三方服务,以及功能是否存在地区差异。涉及账号、付费或用户生成内容时,还需要提供对应流程,所有说明都应按照实际版本填写。

截图需要展示实际 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。草稿页还需要安排发布,并确认已有产品条目的归属。