A type that can advertise your app's activities to other participants.
Adopt the `GroupActivity` protocol in custom app data structures that represent
your app's shareable experiences. The protocol provides the system with the context
and metadata to start an activity-related session. For example,
the protocol defines the unique identity of the activity, and returns information
about the activity.
In addition to the protocol's methods and properties, make sure your type
includes the information you need to start the activity. When a participant
accepts an activity, the system provides a copy of your activity type. You
must use that type to begin the activity. For example, use it to present
the appropriate UI for the activity and to load any required content.
To initiate an activity, create an instance of your custom type and call its
``prepareForActivation()`` or ``activate()`` method. You might call one of these
methods from a button in your app's UI, or in response to other user actions.
If activation succeeds, the system advertises the activity on the current
FaceTime call.
When an activity begins, the system creates a ``GroupSession`` instance for the
activity and delivers it asynchronously to your app. Use the ``sessions()``
method to get the session and configure your app's UI.
- Important: `GroupActivity` types must be <doc://com.apple.documentation/documentation/swift/codable>
so that the system can serialize them and send them to other participant's devices.
Returns the participant's preferred option for how to start the activity.
Call this method as the first step in starting a group activity,
instead of calling the ``GroupActivity/activate()`` method.
Specifically, call this method when the participant tries to start an
activity directly from your app's UI — for example, when
they try to watch a movie that's shareable with a group.
This method determines if sharing is possible, and may also prompt the
participant to choose whether to start the activity locally or share
it with the group.
The system learns over time what activities the user commonly shares,
and may not prompt the user in all situations. The system also doesn't
prompt the user if the user disabled activity sharing or isn't a
member of an active group.
- Returns: The action to take for the activity. Use this value to
determine whether to start an activity locally or as a shared experience.
method · iOS 15.0+
activate
Swift declaration
func activate() async throws -> Bool
Begins the activity immediately and creates a session for the app when
a FaceTime call is active.
Typically, you call this method only when the ``GroupActivity/prepareForActivation()``
method delivers the ``GroupActivityActivationResult/activationPreferred``
result. However, you may call it directly if your activity only makes sense
in a group setting. For example, call it if the activity applies only to groups
and can't be performed without other participants.
If a FaceTime call is active, this method configures a session.
The system also invites other participants to join the activity. If a session will be
delivered to your app this function returns true, otherwise it returns false. A case where this function
could return false is when a session is created and handed off to an Apple TV.
If a call isn't active or a session wasn't created, this method throws an error
Skipped declarations
3 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
GroupActivity.activityIdentifier
Static protocol requirements cannot be called through an instance.
GroupActivity.transferRepresentation
This protocol needs associated types that cannot yet cross the bridge.
GroupActivity.sessions()
Static protocol requirements cannot be called through an instance.
