/shareplay-activities

name: shareplay-activities
description: "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS."

GroupActivities / SharePlay

Build shared real-time experiences using the GroupActivities framework. SharePlay connects people over FaceTime, Messages, AirDrop, and nearby visionOS sharing, synchronizing media playback, app state, or custom data.

Contents

• [Setup](#setup)
• [Defining a GroupActivity](#defining-a-groupactivity)
• [Session Lifecycle](#session-lifecycle)
• [Sending and Receiving Messages](#sending-and-receiving-messages)
• [Coordinated Media Playback](#coordinated-media-playback)
• [Starting SharePlay from Your App](#starting-shareplay-from-your-app)
• [GroupSessionJournal: File Transfer](#groupsessionjournal-file-transfer)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Setup

Capability

Add the **Group Activities** capability to the app target in Xcode. Xcode adds the required entitlement and updates the provisioning profile:

<key>com.apple.developer.group-session</key>
<true/>

Configure this only for app targets. Group Activities are not available in widgets, extensions, or App Clips.

Checking Eligibility

import GroupActivities

let observer = GroupStateObserver()

// Check if a FaceTime call or Messages conversation is active
if observer.isEligibleForGroupSession {
    showSharePlayButton()
}

Observe changes reactively:

for await isEligible in observer.$isEligibleForGroupSession.values {
    showSharePlayButton(isEligible)
}

Defining a GroupActivity

Conform to `GroupActivity` and provide metadata:

import GroupActivities

struct WatchTogetherActivity: GroupActivity {
    let movieID: String
    let movieTitle: String

    var metadata: GroupActivityMetadata {
        var meta = GroupActivityMetadata()
        meta.title = movieTitle
        meta.type = .watchTogether
        meta.fallbackURL = URL(string: "https://example.com/movie/\(movieID)")
        return meta
    }
}

Activity Types

| Type | Use Case | |---|---| | `.generic` | Default for custom activities | | `.watchTogether` | Video playback | | `.listenTogether` | Audio playback | | `.createTogether` | Collaborative creation (drawing, editing) | | `.exploreTogether` | Shared browsing, planning, or exploration | | `.learnTogether` | Shared learning or studying | | `.readTogether` | Shared reading | | `.shopTogether` | Shared shopping | | `.workoutTogether` | Shared fitness sessions |

`GroupActivity` is `Codable`; stored activity data must be codable. Add `Transferable` only for SwiftUI `ShareLink`, SharePlay over AirDrop, or AppKit/UIKit share sheets. Keep payloads minimal: use identifiers or URLs instead of large data.

Session Lifecycle

Listening for Sessions

Set up a long-lived task to receive sessions when another participant starts the activity:

@Observable
@MainActor
final class SharePlayManager {
    private var session: GroupSession<WatchTogetherActivity>?
    private var messenger: GroupSessionMessenger?
    private var sessionTasks: [Task<Void, Never>] = []

    func observeSessions() {
        Task {
            for await session in WatchTogetherActivity.sessions() {
                self.configureSession(session)
            }
        }
    }

    private func configureSession(
        _ session: GroupSession<WatchTogetherActivity>
    ) {
        self.session = session
        self.messenger = GroupSessionMessenger(session: session)

        // Observe session state changes
        let stateTask = Task {
            for await state in session.$state.values {
                handleState(state)
            }
        }
        sessionTasks.append(stateTask)

        // Observe participant changes
        let participantTask = Task {
            for await participants in session.$activeParticipants.values {
                handleParticipants(participants)
            }
        }
        sessionTasks.append(participantTask)

        // Join the session
        session.join()
    }

    private func cleanUp() {
        sessionTasks.forEach { $0.cancel() }
        sessionTasks.removeAll()
        session = nil
        messenger = nil
    }
}

Session States

| State | Description | |---|---| | `.waiting` | Session exists but local participant has not joined | | `.joined` | Local participant is actively in the session | | `.invalidated(reason:)` | Session ended (check reason for details) |

Handling State Changes

private func handleState(_ state: GroupSession<WatchTogetherActivity>.State) {
    switch state {
    case .waiting:
        print("Waiting to join")
    case .joined:
        print("Joined session")
        loadActivity(session?.activity)
    case .invalidated(let reason):
        print("Session ended: \(reason)")
        cleanUp()
    @unknown default:
        break
    }
}

private func handleParticipants(_ participants: Set<Participant>) {
    print("Active participants: \(participants.count)")
}

Leaving and Ending

// Leave the session (other participants continue)
session?.leave()

// End the session for all participants
session?.end()

Sending and Receiving Messages

Use `GroupSessionMessenger` to sync small, time-sensitive app state between participants.

Defining Messages

Messages must be `Codable`; keep each message under 256 KB.

struct SyncMessage: Codable {
    let action: String
    let timestamp: Date
    let data: [String: String]
}

Sending

func sendSync(_ message: SyncMessage) async throws {
    guard let messenger else { return }

    try await messenger.send(message, to: .all)
}

// Send to specific participants
try await