A Flutter plugin to use iOS 16.1+ Live Activities & iPhone 14 Pro Dynamic Island features.
This plugin uses the iOS ActivityKit API.
live_activities can be used to show dynamic live notification & implement dynamic island feature on iPhones that support it ποΈ
β οΈ live_activities is only intended to use with iOS 16.1+ ! It will simply do nothing on other platform & < iOS 16.1
Due to technical restriction, it's not currently possible to only use Flutter π«£.
You need to implement in your Flutter iOS project a Widget Extension & develop in Swift/Objective-C your own Live Activity / Dynamic Island design.
βΉοΈ You can check into the example repository for a full example app using Live Activities & Dynamic Island
ios/Runner.xcworkspace
.File
-> New
-> Target...
Widget Extension
& click on Next.MyAppWidget
) and be sure to select "Runner" in "Embed in Application" dropdown.Add the "Push Notifications" capabilities for the main Runner
app only!.
Enable live activity by adding this line in Info.plist
for both Runner
and your Widget Extension
.
<key>NSSupportsLiveActivities</key>
<true/>
Add the "App Group" capability for both Runner
and your widget extension.
After you add the capability, check the checkmark next to the text field that contains an identifier of the form group.example.myapp
.
This identifier will be used later and refered to as YOUR_GROUP_ID
.
βΉοΈ You can check on this resource or here for more native informations.
ActivityAttributes
called EXACTLY LiveActivitiesAppAttributes
(if you rename, activity will be created but not appear!)struct LiveActivitiesAppAttributes: ActivityAttributes, Identifiable {
public typealias LiveDeliveryData = ContentState // don't forget to add this line, otherwise, live activity will not display it.
public struct ContentState: Codable, Hashable { }
var id = UUID()
}
extension LiveActivitiesAppAttributes {
func prefixedKey(_ key: String) -> String {
return "\(id)_\(key)"
}
}
UserDefaults
with your group id to access Flutter data in your Swift code.// Create shared default with custom group
let sharedDefault = UserDefaults(suiteName: "YOUR_GROUP_ID")!
struct FootballMatchApp: Widget {
var body: some WidgetConfiguration {
ActivityConfiguration(for: LiveActivitiesAppAttributes.self) { context in
// create your live activity widget extension here
// to access Flutter properties:
let myVariableFromFlutter = sharedDefault.string(forKey: context.attributes.prefixedKey("myVariableFromFlutter"))!
// [...]
}
}
}
import 'package:live_activities/live_activities.dart';
final _liveActivitiesPlugin = LiveActivities();
_liveActivitiesPlugin.init(appGroupId: "YOUR_GROUP_ID");
final Map<String, dynamic> activityModel = {
'name': 'Margherita',
'ingredient': 'tomato, mozzarella, basil',
'quantity': 1,
};
_liveActivitiesPlugin.createActivity(activityModel);
You can pass all type of data you want but keep it mind it should be compatible with
UserDefaults
UserDefaults
instance to access data:let sharedDefault = UserDefaults(suiteName: "YOUR_GROUP_ID")!
β οΈ Be sure to use the SAME group id in your Swift extension and your Flutter app!
let pizzaName = sharedDefault.string(forKey: context.attributes.prefixedKey("name"))! // put the same key as your Dart map
let pizzaPrice = sharedDefault.float(forKey: context.attributes.prefixedKey("price"))
let quantity = sharedDefault.integer(forKey: context.attributes.prefixedKey("quantity"))
// [...]
LiveActivityImageFromAsset
or LiveActivityImageFromUrl
object:final Map<String, dynamic> activityModel = {
'assetKey': LiveActivityImageFromAsset('assets/images/pizza_chorizo.png'),
'url': LiveActivityImageFromUrl(
'https://cdn.pixabay.com/photo/2015/10/01/17/17/car-967387__480.png',
resizeFactor: 0.3,
),
};
_liveActivitiesPlugin.createActivity(activityModel);
βΉοΈ Use LiveActivityImageFromAsset
to load an image from your Flutter asset.
βΉοΈ Use LiveActivityImageFromUrl
to load an image from an external url.
β οΈ Image need to be in a small resolution to be displayed in your live activity/dynamic island, you can use
resizeFactor
to automatically resize the image π.
if let assetImage = sharedDefault.string(forKey: context.attributes.prefixedKey("assetKey")), // <-- Put your key here
let uiImage = UIImage(contentsOfFile: shop) {
Image(uiImage: uiImage)
.resizable()
.frame(width: 53, height: 53)
.cornerRadius(13)
} else {
Text("Loading")
}
In order to pass some useful data between your native live activity / dynamic island with your Flutter app you just need to setup URL scheme.
β οΈ It's recommended to set a custom scheme, in this example,
la
is used but keep in mind, you should use a more personalized scheme.ex: for an app named
Strava
, you could usestr
.
Link(destination: URL(string: "la://my.app/order?=123")!) { // Replace "la" with your scheme
Text("See order")
}
β οΈ Don't forget to put the URL Scheme you have typed in the previous step. (
str://
in the previous example)
_liveActivitiesPlugin.init(
appGroupId: 'your.group.id', // replace here with your custom app group id
urlScheme: 'str' // replace here with your custom app scheme
);
_liveActivitiesPlugin.urlSchemeStream().listen((schemeData) {
// do what do you want here π€
});
You can update live activity directly in your app using the updateActivity()
method, but if your app was killed or in the background, you canβt update the notification...
To do this, you can update it using Push Notification on a server.
_liveActivitiesPlugin.activityUpdateStream.listen((event) {
event.map(
active: (activity) {
// Get the token
print(activity.activityToken);
},
ended: (activity) {},
unknown: (activity) {},
);
});
final activityToken = await _liveActivitiesPlugin.getPushToken(_latestActivityId!);
print(activityToken);
To set matchName
for a specific notification, you just need to grab the notification id you want (ex. 35253464632
) and concatenate with your key by adding a _
, example: 35253464632_matchName
.
That's it π
Name | Description | Returned value |
---|---|---|
.init() |
Initialize the Plugin by providing an App Group Id (see above) | Future When the plugin is ready to create/update an activity |
.createActivity() |
Create an iOS live activity | String The activity identifier |
.updateActivity() |
Update the live activity data by using the activityId provided |
Future When the activity was updated |
.endActivity() |
End the live activity by using the activityId provided |
Future When the activity was ended |
.getAllActivitiesIds() |
Get all activities ids created | Future<List<String>> List of all activities ids |
.getAllActivities() |
Get a Map of activitiyIds and the ActivityState |
Future<Map<String, LiveActivityState>> Map of all activitiyId -> LiveActivityState |
.endAllActivities() |
End all live activities of the app | Future When all activities was ended |
.areActivitiesEnabled() |
Check if live activities feature are supported & enabled | Future<bool> Live activities supported or not |
.getActivityState() |
Get the activity current state | Future<LiveActivityState?> An enum to know the status of the activity (active , dismissed or ended ) |
.getPushToken() |
Get the activity push token synchronously (prefer using activityUpdateStream instead to keep push token up to date) |
String? The activity push token (can be null) |
.urlSchemeStream() |
Subscription to handle every url scheme (ex: when the app is opened from a live activity / dynamic island button, you can pass data) | Future<UrlSchemeData> Url scheme data which handle scheme url host path queryItems |
.dispose() |
Remove all pictures passed in the AppGroups directory in the current session, you can use the force parameters to remove all pictures |
Future Picture removed |
.activityUpdateStream |
Get notified with a stream about live activity push token & status | Stream<ActivityUpdate> Status updates for new push tokens or when the activity ends |
Contributions are welcome. Contribute by creating a PR or an issue π.
String
(Date, Number etc.).