文章

邀请参与者共享活动

为群组活动提供支持,并在特定时间通过你的 UI 展示它们。

概览

创建群组体验时,应该以你的 App 所支持的活动为中心。例如,视频流 App 可以定义观影活动。活动包含 App 执行相关任务 (如播放影片) 所需的数据。它还包括关于活动的描述信息 (如影片的名称),系统可以将这些信息传达给其他参与者。

通过 Group Activities 框架,你可以将活动信息整合到 App 的现有类型和对象中。为你的 App 支持的每个独特体验定义一项活动。例如,视频流 App 可以分别为观影和观看电视节目定义不同的活动。通过分别使用不同的活动类型,可以更轻松地为每项活动定制体验。

配置授权

由于活动涉及与其他设备的交互,因此你的 App 必须具有 com.apple.developer.group-session (英文) 授权。在 Xcode 中将此授权添加到你的 App:

  1. 打开你的 Xcode 项目。

  2. 选择你的 App 目标。

  3. 前往“Signing & Capabilities”(签名和功能) 标签。

  4. 将群组活动功能添加到相应目标中。

群组活动功能会将必要的授权添加到你的 App 和预置描述文件中。你可以将此功能仅添加到 App 目标。

定义自定活动实例

对于 App 支持的每项活动,定义采用 GroupActivity (英文) 协议的轻量级类或结构。活动实例提供 App 向参与者提供的特定活动相关描述信息。活动实例实际上可能是 App 中的现有数据类型。例如,观影 App 的活动实例可能包含影片名称、海报图像以及关于如何播放影片的特定于 App 的信息。

以下示例展示了为观影活动提供支持的结构的实现。activityIdentifier 属性包含你的活动的唯一标识符,通常采用反向 DNS 格式。其他属性则会定义关于影片的信息。例如,这个 App 使用 catalogcontentIdentifier 属性在 iTunes Store 中查找影片。


struct WatchTogether: GroupActivity {
  
   // Specify the activity type to the system.
    static let activityIdentifier = “com.example.myapp.watch-movie-together”
   
   //----------
   // Store app-specific information about the movie. 


   // The catalog identifier or store location of the content.
   var catalog: Catalog = .us


   // The content item identifier of the movie to watch together.
   var contentIdentifier: String


   // The movie title localized to the initiator's language.
   var movieTitle: String


}

只有当你的 App 向用户展示活动时,这些活动才是相关的,因此你需要在用户界面设置时创建 GroupActivity (英文) 类型,并将其保存在视图中。例如,在影片详情视图中创建一个上述类型,该视图显示供参与者观看的影片。

提供关于活动的描述信息

在用户加入活动之前,系统会显示该活动的相关信息,包括标题、可选的副标题以及要显示的图像。观影 App 可能会返回影片名称及其相关海报图像。听歌 App 可能会返回所选曲目的名称和任何专辑插图。

要将活动的元数据返回给系统,需实现 metadata (英文) 属性并返回 GroupActivityMetadata (英文) 实例。以下示例展示了 WatchTogether 结构的一个扩展,其中创建了这一结构并将影片标题填入其中。它还包含一个基于 web 的 URL,供尚未在设备上安装你的 App 的参与者使用。


extension WatchTogether {


    // Provide information about the activity. 
    var metadata: GroupActivityMetadata {
        var metadata = GroupActivityMetadata()
        metadata.type = .watchTogether
        metadata.title = movieTitle
        metadata.fallbackURL = URL(string: 
                "https://itunes.apple.com/\(catalog)/movie/\(contentIdentifier)")
        return metadata
    }
}

提供加入活动所需的 UI

在 App 的 UI 中加入按钮或其他控件,让用户能够启动新活动。当用户轻点相应按钮,或者以启动活动的方式与 UI 交互时,调用相关 GroupActivity (英文) 类型的适当方法。

对于大多数活动,你可以调用 GroupActivity (英文) 类型的 prepareForActivation() (英文) 方法来启动活动。该方法可确定 App 是否支持活动共享,以及用户是否希望共享活动。例如,用户可能选择观看影片而不与朋友共享。当结果就绪时,该方法调用你提供的完成处理程序,你可以使用它来启动或中止活动。以下示例展示了如何实现对该方法的典型调用:


private func playMovie() {
   // If a session is already active, just change the movie.
   if let activeGroupSession = activitySession.groupSession {
      // Change the current movie.
      activeGroupSession.activity = currentMovie
   } else {
      // Try to start a new movie-watching activity.
      item.prepareForActivation { result in
         switch result {
         case .activationPreferred:
            // Watch the movie with the group.
            currentMovie.activate()
         case .activationDisabled:
            // Watch the movie locally. 
            isMoviePlaying = true
         default:
            break
         }
     }
   }
}

要进一步了解如何加入新启动的活动,请参阅“加入和管理共享活动”。

另请参阅

活动创建