shareplay-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SharePlay Developer

SharePlay 开发者指南

Description and Goals

描述与目标

This skill provides comprehensive guidance for implementing SharePlay experiences with the GroupActivities framework. It covers activity definition, session lifecycle, state synchronization, UI surfaces, and visionOS spatial coordination.

本技能为使用GroupActivities框架实现SharePlay体验提供全面指导，涵盖活动定义、会话生命周期、状态同步、UI界面以及visionOS空间协同。

Goals

目标

Enable developers to build SharePlay experiences across Apple platforms
Guide proper GroupActivity definition and activation
Support GroupSession lifecycle management
Help implement state synchronization with messaging and journals
Enable spatial coordination for visionOS immersive experiences (group immersive space)

帮助开发者在Apple平台上构建SharePlay体验
指导正确定义和激活GroupActivity
支持GroupSession生命周期管理
协助实现基于消息传递与日志的状态同步
为visionOS沉浸式体验（群组沉浸式空间）实现空间协同

What This Skill Should Do

本技能的适用场景

When implementing SharePlay features, this skill should:

Guide activity setup - Help you define GroupActivity types and metadata
Handle activation - Show how to check eligibility and activate SharePlay
Manage sessions - Demonstrate GroupSession lifecycle and participant management
Sync state - Provide patterns for messaging and journal-based synchronization
Coordinate spatially - Show how to use SystemCoordinator for visionOS spatial experiences and group immersive spaces
Present UI - Guide use of ShareLink and other SharePlay UI surfaces

Load the appropriate reference file from the tables below for detailed usage, code examples, and best practices.

在实现SharePlay功能时，本技能可：

指导活动设置 - 帮助你定义GroupActivity类型和元数据
处理激活流程 - 展示如何检查资格并激活SharePlay
管理会话 - 演示GroupSession生命周期和参与者管理
同步状态 - 提供基于消息传递和日志的同步模式
空间协同配置 - 展示如何使用SystemCoordinator实现visionOS空间体验和群组沉浸式空间
UI界面呈现 - 指导使用ShareLink及其他SharePlay UI界面

如需详细用法、代码示例和最佳实践，请从下表加载对应的参考文件。

Quick Start Workflow

快速开始流程

Add the Group Activities capability and
```
com.apple.developer.group-session
```
entitlement in Xcode.
Define a
```
GroupActivity
```
type per experience and keep its data minimal and
```
Codable
```
.
Provide
```
GroupActivityMetadata
```
with a clear title, type, and fallback URL.

Check

GroupStateObserver.isEligibleForGroupSession

and activate or present SharePlay UI.

Listen for sessions with
```
for await session in Activity.sessions()
```
and store the session strongly.
Configure
```
SystemCoordinator
```
before
```
join()
```
when spatial personas or immersive spaces are involved.
Call
```
session.join()
```
only after UI and state are ready.
Sync state with
```
GroupSessionMessenger
```
(small, time-sensitive) or
```
GroupSessionJournal
```
(attachments).
Observe
```
activeParticipants
```
and send a state snapshot for late joiners.
Call
```
leave()
```
or
```
end()
```
and cancel tasks when the session invalidates.

在Xcode中添加Group Activities功能和
```
com.apple.developer.group-session
```
权限。
为每个体验定义一个
```
GroupActivity
```
类型，确保其数据精简且符合
```
Codable
```
协议。
提供包含清晰标题、类型和备用URL的
```
GroupActivityMetadata
```
。
检查
```
GroupStateObserver.isEligibleForGroupSession
```
，然后激活或呈现SharePlay UI。
通过
```
for await session in Activity.sessions()
```
监听会话，并保持对会话的强引用。
当涉及空间角色或沉浸式空间时，在调用
```
join()
```
前配置
```
SystemCoordinator
```
。
仅在UI和状态准备就绪后调用
```
session.join()
```
。
使用
```
GroupSessionMessenger
```
（小型、时间敏感数据）或
```
GroupSessionJournal
```
（附件）同步状态。
监听
```
activeParticipants
```
，并为晚加入的参与者发送状态快照。
当会话失效时，调用
```
leave()
```
或
```
end()
```
并取消任务。

visionOS Launch-Only Workflow (Same Space, No Sync)

visionOS 仅启动流程（同一空间，无同步）

Use this when you only want participants to enter the same immersive space with spatial coordination, without synchronizing entities or interactions yet.

Define a

GroupActivity

with lightweight metadata and

GroupActivityTransferRepresentation

Provide a

SharePlayManager

that observes sessions and configures

SystemCoordinator

```
supportsGroupImmersiveSpace = true
```
```
spatialTemplatePreference = .sideBySide
```
(or another appropriate template)

In your
```
ImmersiveSpace
```
scene, set
```
.immersiveEnvironmentBehavior(.coexist)
```
so the system can colocate participants.
Provide a start button:
- If FaceTime is active and activation is preferred, call
```
activate()
```
  .
- Otherwise present
```
GroupActivitySharingController
```
  (UIKit) or
```
ShareLink
```
  (SwiftUI).
Join the session with
```
session.join()
```
once configured.

当你仅希望参与者进入同一沉浸式空间并实现空间协同，但暂不同步实体或交互时，可使用此流程。

定义一个包含轻量级元数据和

GroupActivityTransferRepresentation

的

GroupActivity

。

提供一个

SharePlayManager

来监听会话并配置

SystemCoordinator

：

设置
```
supportsGroupImmersiveSpace = true
```
设置
```
spatialTemplatePreference = .sideBySide
```
（或其他合适的模板）

在你的
```
ImmersiveSpace
```
场景中，设置
```
.immersiveEnvironmentBehavior(.coexist)
```
，以便系统可以定位参与者。
提供一个启动按钮：
- 如果FaceTime处于活跃状态且优先激活，调用
```
activate()
```
  。
- 否则，在UIKit中使用
```
GroupActivitySharingController
```
  ，或在SwiftUI中使用
```
ShareLink
```
  。
配置完成后，调用
```
session.join()
```
加入会话。

Information About the Skill

技能相关信息

Core Concepts

核心概念

Activity Definition

活动定义

Use
```
GroupActivity
```
to define the shareable experience and keep payloads minimal.
Provide
```
GroupActivity.metadata
```
with title, subtitle, preview image, and fallback URL.
Set
```
GroupActivityMetadata.type
```
to a matching
```
ActivityType
```
value.

Use

GroupActivityActivationResult

from

prepareForActivation()

to decide activation.

Use

GroupActivityTransferRepresentation

for

ShareLink

and share sheets.

使用
```
GroupActivity
```
定义可共享的体验，并保持负载精简。
为
```
GroupActivity.metadata
```
提供标题、副标题、预览图和备用URL。
将
```
GroupActivityMetadata.type
```
设置为匹配的
```
ActivityType
```
值。

使用

prepareForActivation()

返回的

GroupActivityActivationResult

决定激活方式。

为

ShareLink

和分享面板使用

GroupActivityTransferRepresentation

。

Session Lifecycle and Participants

会话生命周期与参与者

Use
```
GroupSession
```
to manage the live activity; call
```
join()
```
,
```
leave()
```
, or
```
end()
```
.

Observe

GroupSession.state

activeParticipants

, and

isLocallyInitiated

to drive UI.

Use
```
GroupSession.sceneSessionIdentifier
```
to map sessions to scenes when needed.
Call
```
requestForegroundPresentation()
```
when the activity needs the app visible.

Use

GroupSession.showNotice(_:)

postEvent(_:)

for system playback notices.

使用
```
GroupSession
```
管理实时活动；调用
```
join()
```
、
```
leave()
```
或
```
end()
```
。

监听

GroupSession.state

、

activeParticipants

和

isLocallyInitiated

以驱动UI。

必要时，使用
```
GroupSession.sceneSessionIdentifier
```
将会话映射到场景。
当活动需要应用可见时，调用
```
requestForegroundPresentation()
```
。

使用

GroupSession.showNotice(_:)

或

postEvent(_:)

发送系统播放通知。

Messaging and Transfer

消息传递与传输

Use
```
GroupSessionMessenger
```
for small messages (<= 256 KB).
Use
```
.reliable
```
delivery for critical state and
```
.unreliable
```
for high-frequency updates.
Use
```
GroupSessionJournal
```
for attachments and large data (<= 100 MB).

使用
```
GroupSessionMessenger
```
传输小型消息（≤256 KB）。
对关键状态使用
```
.reliable
```
交付模式，对高频更新使用
```
.unreliable
```
交付模式。
使用
```
GroupSessionJournal
```
传输附件和大型数据（≤100 MB）。

UI Surfaces to Start SharePlay

启动SharePlay的UI界面

Use

ShareLink

with

Transferable

GroupActivityTransferRepresentation

in SwiftUI.

Use
```
GroupActivitySharingController
```
in UIKit/AppKit when no FaceTime call is active.

Use

NSItemProvider.registerGroupActivity(...)

in share sheets when needed.

在SwiftUI中结合

Transferable

GroupActivityTransferRepresentation

使用

ShareLink

。

当FaceTime通话未激活时，在UIKit/AppKit中使用
```
GroupActivitySharingController
```
。

必要时，在分享面板中使用

NSItemProvider.registerGroupActivity(...)

。

visionOS Spatial Coordination

visionOS空间协同

Use

SystemCoordinator

from

GroupSession.systemCoordinator

for spatial layout.

Set

spatialTemplatePreference

and

supportsGroupImmersiveSpace

as needed.

Use

localParticipantStates

and

remoteParticipantStates

to track poses.

Use
```
groupActivityAssociation(_:)
```
to choose the primary scene.
For immersive spaces, prefer
```
.immersiveEnvironmentBehavior(.coexist)
```
on the
```
ImmersiveSpace
```
scene to allow co-location.

使用

GroupSession.systemCoordinator

提供的

SystemCoordinator

进行空间布局。

根据需要设置

spatialTemplatePreference

和

supportsGroupImmersiveSpace

。

使用

localParticipantStates

和

remoteParticipantStates

跟踪姿态。

使用
```
groupActivityAssociation(_:)
```
选择主场景。
对于沉浸式空间，建议在
```
ImmersiveSpace
```
场景上设置
```
.immersiveEnvironmentBehavior(.coexist)
```
以支持共定位。

Reference Files

参考文件

Reference	When to Use
`[REFERENCE.md](references/REFERENCE.md)`	When looking for GroupActivities-focused code samples and excerpts.
`visionos-immersive-space.md`	When implementing “launch-only” SharePlay for a visionOS immersive space (same space, no sync).
`activation-ui.md`	When wiring the start button (FaceTime-active activation vs share sheet fallback).

参考文件	使用场景
`[REFERENCE.md](references/REFERENCE.md)`	查找GroupActivities相关代码示例和片段时使用。
`visionos-immersive-space.md`	为visionOS沉浸式空间实现“仅启动”SharePlay（同一空间，无同步）时使用。
`activation-ui.md`	配置启动按钮（FaceTime激活状态下的激活与分享面板回退）时使用。

Implementation Patterns

实现模式

Send a full state snapshot when new participants join.
Keep UI state separate from shared game state to reduce message churn.
Use
```
GroupSessionMessenger
```
for transient actions and
```
GroupSessionJournal
```
for durable data.
Prefer AVFoundation coordinated playback for media sync.

当新参与者加入时发送完整状态快照。
将UI状态与共享游戏状态分离，以减少消息传输量。
使用
```
GroupSessionMessenger
```
传输临时操作，使用
```
GroupSessionJournal
```
传输持久化数据。
对于媒体同步，优先使用AVFoundation协同播放。

Pitfalls and Checks

常见陷阱与检查项

Keep
```
GroupActivity
```
data minimal; send state changes via messenger or journal.

Store strong references to

GroupSession

GroupSessionMessenger

, and

GroupSessionJournal

Join only when UI and state are ready; call
```
leave()
```
on teardown.
Handle late joiners by sending the current state snapshot on
```
activeParticipants
```
change.
For visionOS group immersive space: if participants don't colocate, verify
```
supportsGroupImmersiveSpace
```
, your scene's
```
.immersiveEnvironmentBehavior(.coexist)
```
, and that
```
SystemCoordinator
```
is configured before
```
join()
```
.

保持
```
GroupActivity
```
数据精简；通过messenger或journal发送状态变更。

对

GroupSession

、

GroupSessionMessenger

和

GroupSessionJournal

保持强引用。

仅在UI和状态准备就绪后加入会话；在销毁时调用
```
leave()
```
。
当
```
activeParticipants
```
变化时，通过发送当前状态快照处理晚加入的参与者。
对于visionOS群组沉浸式空间：如果参与者无法共定位，请检查
```
supportsGroupImmersiveSpace
```
、场景的
```
.immersiveEnvironmentBehavior(.coexist)
```
设置，以及是否在
```
join()
```
前配置了
```
SystemCoordinator
```
。