Share files with SharePlay
System & Services 进阶 20m

通过 SharePlay 传输文件：GroupSessionJournal 详解

Share files with SharePlay

2023年6月5日

在 Apple 官方观看视频

一句话判断

GroupSessionJournal 是 SharePlay 的文件传输 API，支持端到端加密、自动处理迟到者同步，单个附件上限 100MB。

这场 Session 讲了什么

Adam 介绍了 iOS 17 中 GroupActivities 框架新增的 GroupSessionJournal API。在此之前，GroupSessionMessenger 只能传输小型消息数据，无法传输图片、PDF、语音备忘录等大文件。GroupSessionJournal 填补了这个空白。

核心机制：一个 GroupSessionJournal 实例绑定到一个 GroupSession，所有参与者共享同一个 Journal。当一个人调用 add 上传附件，所有参与者的 attachments AsyncSequence 都会收到通知。调用 remove 同理。附件类型只需遵循 Transferable 协议。

两个关键设计决策：附件大小上限 100MB，这迫使开发者思考用户体验——大文件应该走自己的服务器，而不是通过用户设备中转；生命周期与 GroupSession 绑定，只要还有人在线，附件就保留，所有人都离开后自动清除。

迟到者（Late Joiner）问题也得到了解决。以前新加入的人需要其他参与者重新上传状态数据，现在 Journal 会自动把已有附件同步给新加入者，不需要其他人重新上传。

值得深挖的点

Transferable 协议的复用。GroupSessionJournal 的 add 方法接受任何遵循 Transferable 协议的类型。这个协议同时被拖拽、剪贴板、SharePlay 等系统 API 使用，一次实现多处复用。

100MB 限制的设计哲学。这不是技术上的极限，而是对用户体验的约束。通过用户设备传输大文件会消耗带宽和电池，对于非用户生成的内容（比如一部电影），应该由服务器分发。

端到端加密的实现层次。数据传输利用 Apple 的云端基础设施做了多层优化——最小化传输数据量、最小化等待时间——同时在系统层面完成加密，Apple 无法看到传输内容。

代码片段

// 创建 GroupSessionJournal 并监听附件变化
func configureGroupSession(_ session: GroupSession<DrawingActivity>) {
    let journal = GroupSessionJournal(session: session)
    
    // 监听附件变化
    Task {
        for await attachments in journal.attachments {
            for attachment in attachments {
                // 加载附件数据
                let imageData = try await attachment.load(Data.self)
                let image = UIImage(data: imageData)
                canvas.addImage(image)
            }
        }
    }
    self.journal = journal
}

// 上传本地图片到 Journal
func addImage(_ image: UIImage) async {
    guard let data = image.jpegData(compressionQuality: 0.8) else { return }
    // Data 遵循 Transferable，可以直接添加
    try? await journal?.add(data)
}
// 移除附件（所有参与者都会收到通知）
func removeAttachment(_ attachmentID: UUID) async {
    try? await journal?.remove(attachmentID)
}

最佳实践

  • 限制用户可添加的内容大小，比如画布应用限制图片不超过 100MB。
  • 区分”用户生成内容”和”应用资源”：前者走 Journal，后者走自己的 CDN。
  • Journal 中附件的生命周期与 Session 绑定，重要数据要在 Session 结束前持久化到本地。
  • 迟到者自动同步意味着你不需要为 Journal 数据单独实现状态恢复逻辑。
  • 压缩图片和文件再上传，减少传输时间和带宽消耗。

还有什么值得关注

  • Session 用 DrawTogether 示例 App 演示了完整的 adoption 流程
  • Transferable 协议是 Apple 平台的通用数据交换协议，值得单独了解
  • 如果你的 App 已经用了 GroupSessionMessenger，添加 Journal 支持的工作量很小
  • 端到端加密对医疗、金融等敏感场景很有吸引力
WWDC 2023