文章

加入和管理共享活动

加入活动,并使用系统提供的群组会话对象同步您的 App 的行为。

概览

任何活跃的 FaceTime 通话的参与者都可以启动一项活动,并与群组共享该活动。系统向通话中的其他参与者显示共享活动,并邀请他们加入。当参与者接受邀请时,系统将:

  • 根据需要启动您的 App。

  • 为选定的活动创建 GroupSession (英文) 对象。

  • 将会话通过异步方式传递到您的 App。

如果参与者更改了会话的特定活动,系统会将更新的会话通过异步方式传递到您的 App。例如,参与者可能会选择观看不同的单集。在新会话和更新会话中为所选内容配置 App 的 UI。

有关如何广播 App 所支持活动的信息,请参阅“邀请参与者共享活动”。

通过异步方式接收会话对象

系统通过自定 GroupActivity (英文)sessions() (英文) 方法将 GroupSession (英文) 对象通过异步方式传递到您的 App。此方法会返回一个 AsyncSequence 类型,该类型通过异步方式一次返回一个会话。当参与者更新当前会话时,序列会将该会话添加为下一个元素。要检索每个新会话,需配置一个异步任务以在 for...in 循环中迭代序列。

以下示例展示了如何在 SwiftUI 视图中接收会话。.task 修饰符会创建一个新的异步任务,该任务会迭代活动的会话。当新会话到达时,任务会更新会话状态变量,从而触发视图更新。


struct DrawTogetherView: View {
    @State var session: GroupSession<DrawTogether>?
    var body: some View {
        Text("Draw Together")
            .task {
                // Receive the new session asynchronously.
                for await drawingSession in DrawTogether.sessions() {
                   session = drawingSession
                }
            }
            .fullScreenCover(item: $session) { session in
                DrawingView(session: session)
            }
    }
}

如果您不使用 SwiftUI,可以使用独立 async 块来启动异步任务,如下方示例所示。当会话到达时,执行代码来启动或更新相关活动。


// Process an asynchronously delivered session.
async {
    for await drawingSession in DrawTogether.sessions() {
        // Update the app for the new session.
        self.updateActivity(session: drawingSession)
    }
}

准备您的 App 的 UI

当您收到新的 GroupSession (英文) 对象时,立即针对该活动配置 App 的 UI。只有当用户表示对该活动感兴趣时,您的 App 才会收到会话,因此需要优先处理该活动。根据需要针对新内容显示一个窗口或视图控制器,或者更新 App 的现有 UI 以体现与会话相关的更改。

在针对该活动显示任何 UI 之前,请对该活动和会话进行任何必要的验证。如果您的 App 需要参与者为内容付费、提供登录凭证、下载内容或执行其他任务,请首先显示这些任务的相关 UI。这些任务成功完成后,立即指引参与者转向您的活动 UI,以最大限度地减少加入会话的延迟。

加入群组会话以开始同步内容

只有在确认您的 App 已准备好开始活动并开始与其他参与者设备同步内容后,才能加入群组会话。新的 GroupSession (英文) 对象不会立即与群组同步数据,而是会以 GroupSession.State.waiting (英文) 状态启动,您必须显式调用其 join() (英文) 方法,让系统知道您的 App 已准备好开始相关活动。如果您对 join() (英文) 的调用成功,系统会将会话更改为 GroupSession.State.joined (英文) 状态,并开始设备之间的信息流动。

调用 join() (英文) 方法的最佳时间是在屏幕上显示与活动相关的 UI 时。确保对您的 App 进行适当配置,以便在 UI 出现时可以启动活动。采取任何必要的额外步骤,提前为活动做好准备。例如,在显示 UI 之前,请验证用户是否拥有任何媒体内容的数字权限,并提示用户提供必要的凭证。

加入会话后,将 GroupSession (英文) 对象传递给需要同步的任何其他对象。例如,通过将会话传递给 AVPlaybackCoordinator (英文) 对象来同步电影播放。

退出活动

加入会话后,您的 App 可以通过调用会话的 leave() (英文) 方法随时退出会话。退出会话可以让您在不影响其他用户的情况下将 App 与活动分离。例如,退出会话的媒体播放 App 可以在本地停止播放,而不会停止群组中其他成员的播放。当您退出群组时,系统会将您的 App 的会话返回到 GroupSession.State.invalidated(reason:) (英文) 状态,并停止与其他设备之间的信息流动。退出会话后,放弃会话对象。

当用户执行以下操作时,您可能会退出会话:

  • 离开您的 App 的活动 UI。

  • 退出您的 App。

  • 切换到其他 App。

如果其他用户仍在参与活动,则系统会向退出活动的参与者显示 UI,使他们能够重新加入。如果参与者重新加入,系统会向您的 App 提供一个新会话,您可以用来重新加入会话,并再次与活动同步。

另请参阅

会话管理