Push to Start Live Activities

[brismithers]

Description

One Line Summary

Update SDK to support Live Activities PushToStart and add a concept of a "Default" Live Activity to facilitate easier adoption.

Details

Push to Start Live Activities

Starting with iOS 17.2, Live Activities can now be started via push notification (Apple's documentation). This change enhances the OneSignal SDK to provide application's access to the full suite of Live Activity functionality.

Default Live Activity

The concept of a "Default" Live Activity has been established in the SDK, which eliminates the need for a customer app to define and manage their own ActivityAttributes. This is most beneficial for wrapper-SDKs, as they will no longer need to create their own cross-platform <-> native iOS bridge to establish this management. The following new external interfaces are provided for customer app's to use:

• A DefaultLiveActivityAttributes struct which conforms to OneSignalLiveActivityAttributes (i.e. a OneSignal aware ActivityAttributes). A customer app can create a widget with ActivityConfiguration(for: DefaultLiveActivityAttributes.self) to use this provided model. The DefaultLiveActivityAttributes establishes a dynamic dictionary of attributes, able to consume any customer-provided structure of data.
• A new function OneSignal.LiveActivities.setupDefault() which tells the OneSignal SDK to manage the LiveActivity lifecycle for the DefaultLiveActivityAttributes type. When calling this method, a customer can use both 'push-to-start' and push-to-update notifications to start/update/end their Default Live Activity.
• A new function OneSignal.LiveActivities.startDefault(activityId, activityAttributes, initialContentState) which allows a customer app to start a live activity based on the DefaultLiveActivityAttributes type "in app".

The downside to using a default Live Activity is:

• The app will be limited to only one Live Activity type.
• The widget rendering logic is slightly more complicated in that it is using a dynamically defined ActivityAttributes. For example, instead of rendering a text attribute as Text(context.state.message) it would be rendered as Text(context.state.data["message"]?.asString() ?? "").

Alternative (low level) method to setup Live Activities with OneSignal

If a customer app does not want to use the default live activity they can still create their own ActivityAttribute structure and manage the live activity lifecycle themselves. These methods require the application to listen for pushToStart token updates, the starting of live activities, and update token updates. This encompasses existing
functions OneSignal.LiveActivities.enter and OneSignal.LiveActivities.exit which are documented here. Additional new methods to cover registering/unregistering pushToStart tokens have been created:

• OneSignal.LiveActivities.setPushToStartToken: To be called 'per-activity-typeeach time that activity type's pushToStart token has been refreshed. An "activity type" is the name of theActivityAttribute` structure. The new pushToStart tokens are sync'd to the OneSignal backend and registered against the current subscription, where it can be the target of a started live activity.

• OneSignal.LiveActivities.removePushToStartToken: To be called per-activity-type whenever that activity type should no longer be registered against the current subscription.

Motivation

Full support of Live Activities functionality introduced in iOS 17.2

Scope

Live Activities

Testing

Manual testing

• Updated the example app to include a live activities section, which drives both the new default live activities flow and the lower level enter, exit, setPushToStartToken, and removePushToStartToken. Note that the lower level methods send dummy tokens, the example app does not show how to create a cordova<->ios native bridge to manage live activities.
• A new widget extension was established for the example app to use and render an example live activity that uses the default live activity.
• Ran the example app and monitored log statements to ensure the pushToStart token and pushToUpdate token requests were being sent to the backend.
• Ensured the default activity could be started "in-app" and via push notification.

Affected code checklist

• [ ] Notifications
  • [ ] Display
  • [ ] Open
  • [ ] Push Processing
  • [ ] Confirm Deliveries
• [ ] Outcomes
• [ ] Sessions
• [ ] In-App Messaging
• [x] REST API requests
• [x] Public API changes
• [x] Live Activities

Checklist

Overview

• [x] I have filled out all REQUIRED sections above
• [x] PR does one thing
  • If it is hard to explain how any codes changes are related to each other then it most likely needs to be more than one PR
• [x] Any Public API changes are explained in the PR details and conform to existing APIs

Testing

• [x] I have included test coverage for these changes, or explained why they are not needed
• [x] All automated tests pass, or I explained why that is not possible
• [x] I have personally tested this on my device, or explained why that is not possible

Final pass

• [x] Code is as readable as possible.
  • Simplify with less code, followed by splitting up code into well named functions and variables, followed by adding comments to the code.
• [x] I have reviewed this PR myself, ensuring it meets each checklist item
  • WIP (Work In Progress) is ok, but explain what is still in progress and what you would like feedback on. Start the PR title with "WIP" to indicate this.

---

This change is