mcpField
A
apple-wallet-passes

apple-wallet-passes

github.com/ios-agent开发1248 次安装34 周前更新
代码仓库

关于 apple-wallet-passes

apple-wallet-passes 是指导 Apple Wallet 通行证全生命周期的技能，面向设计和开发通行证的人员。它涵盖样式选择、PassKit 构建、签名、分发、更新及核验。

主要功能

  1. 01选择五种通行证样式
  2. 02规划版面与信息字段
  3. 03使用 PassKit 构建和签名
  4. 04通过应用、邮件或网页分发
  5. 05处理更新、兑换与身份核验

适用场景

  1. 01创建登机牌、优惠券或活动门票
  2. 02配置证书并分发 .pkpass 文件
  3. 03为通行证实现推送更新
  4. 04使用条码、NFC 或身份 API 核验

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ios-agent/iosagent.dev --skill apple-wallet-passes

安装后在 Claude Code 中输入/apple-wallet-passes确认已加载。

附带文件references/passkit-technical.md

详细介绍

Apple Wallet 通行证

此技能可帮助你引导用户完成 Apple Wallet 通行证的整个生命周期：从选择合适的通行证样式，到设计和开发，再到签名、分发和更新。

适用场景

遇到以下任一场景时，请使用此技能：

  • 创建新的 Wallet 通行证（登机牌、优惠券、活动门票、商店卡、通用通行证）
  • 设计通行证布局并选择合适的通行证样式
  • 设置 Apple 签发证书的通行证签名
  • 通过应用、电子邮件或 Web 分发通行证
  • 使用推送通知实现通行证更新
  • 使用 NFC 读卡器或扫描条形码
  • 添加“添加到 Apple Wallet”徽章
  • 实现 Verify with Wallet API 或 ID Verifier
  • 咨询 PassKit 框架或 WalletPasses 文档

通行证样式概览

Apple Wallet 支持五种通行证样式。选择正确的样式至关重要，因为它决定了视觉布局、信息层级，以及时间和位置相关性的运作方式。

样式用途示例
登机牌旅行和交通航班、火车、巴士通行证
优惠券促销和折扣商店优惠券、促销优惠
活动门票有时间限制的活动音乐会、电影、体育赛事门票
商店卡忠诚度和奖励忠诚度卡、礼品卡、会员卡
通用通行证其他用途会员卡、领取凭证、保险卡

样式会影响相关性（时间范围和位置半径）的解读方式。登机牌的相关性范围与电影票截然不同，因此务必根据实际用途选择样式。

开发工作流

按照以下步骤依次引导用户，并根据他们当前所处的阶段灵活调整：

1. 选择通行证样式

询问用户正在制作哪种通行证。根据其用途，帮助他们选择合适的样式。如果用途不明确（例如，健身房会员资格），请说明选择商店卡或通用通行证的利弊。

2. 设计通行证
  • 通行证应清晰、经过优化，并在所有设备上呈现良好效果
  • 指引用户参考人机界面指南，了解设计最佳实践
  • 设计时的关键考量：徽标、条带图像、图标、相关文本字段、条形码位置
3. 使用 PassKit 构建通行证
  • 使用 PassKit 框架创建、分发和更新通行证
  • 通行证是经过签名的程序包（.pkpass 文件），其中包含 pass.json 清单和资源
  • 如需了解 API 详情，请参阅 PassKit 文档
  • 如需通过 Web 分发，请参阅 WalletPasses 文档
4. 为通行证签名

通行证必须使用 Apple 签发的证书签名，该证书须关联到开发者的 Apple Developer 账户。

需要说明的要点：

  • 在证书、标识符与描述文件中管理证书
  • 只有来自同一团队且具备相应权限的应用才能访问这些通行证
  • 证书过期：设备上已有的通行证仍可使用，但无法签署新通行证，也无法发送更新
  • 证书被撤销：通行证将停止工作——务必强调这一区别
5. 分发通行证

三种分发渠道：

  1. 应用内 — 使用 PassKit API 展示带有“添加到 Wallet”徽章的通行证
  2. 电子邮件 — 附上 .pkpass 文件；收件人轻点即可添加
  3. Web — 托管通行证以供下载；使用“添加到 Wallet”徽章

重要细节：

  • 用户无需安装关联应用即可添加通行证
  • 如果存在关联应用，用户可以直接从通行证安装该应用
  • iCloud 会在用户的所有设备间同步通行证
  • 请遵循“添加到 Apple Wallet”徽章指南使用品牌标识
6. 更新通行证

有两种更新机制：

  • 推送通知 — 服务端发送更新通知；用户轻点即可查看更改
  • 下拉刷新 — 用户手动刷新通行证背面

常见更新场景：登机口变更、余额调整、日程变更。

7. 接收 / 核销通行证

有三种核销方式：

方式详情
NFC非接触式核销；用户将设备靠近读卡器即可。无需条形码。Apple Pay 忠诚度通行证请参阅忠诚度通行证文档。
条形码支持 QR、Aztec、PDF417 格式。屏幕会锁定为纵向并提高背光亮度。对于 iPhone 屏幕，光学扫描器比激光扫描器效果更好。
文本备用方式在条形码下方显示会员号 / 账户号码，供手动输入。
8. 身份验证（可选）

有两个身份验证 API：

  • 使用 Wallet API 验证 — 使用 Wallet 中存储的 ID 进行年龄或身份验证。了解更多
  • ID Verifier — 将 iPhone 用作移动 ID 读取器，进行现场验证，无需外部硬件。了解更多

常见问题

用户提出以下问题时，可以这样回答：

“如果我的证书过期了会怎样？” → 设备上已有的通行证仍可使用。你只是无法签署新通行证或推送更新。

“我应该使用哪种条形码格式？” → QR 的通用性最高。Aztec 格式紧凑，常用于航空公司。PDF417 用于某些旧系统。请使用实际扫描硬件进行测试。

“用户可以不通过我的应用添加通行证吗？” → 可以。无需安装任何应用，用户也可以通过电子邮件或网页添加通行证。

“如何测试通行证扫描？” → 务必使用实际要采用的硬件进行测试。与激光扫描器相比，光学扫描器对 iPhone 屏幕的识读效果好得多。

参考

如需深入了解技术细节，请阅读 references/passkit-technical.md，其中介绍了 pass.json 结构、服务端更新流程和代码示例。

评论

支持 Markdown