live_activities 1.4.0+4 icon indicating copy to clipboard operation
live_activities: ^1.4.0+4 copied to clipboard

PlatformiOS

A Flutter plugin to use iOS 16.1+ Live Activities & iPhone 14 Pro Dynamic Island features

flutter ios 16 live activities


A Flutter plugin to use iOS 16.1+ Live Activities & iPhone 14 Pro Dynamic Island features.

๐Ÿง What is it ? #

This plugin use iOS ActivityKit API.

live_activities can be used to show dynamic live notification & implement dynamic island feature on the iPhone 14 Pro / Max ๐Ÿ๏ธ

โš ๏ธ live_activities is only intended to use with iOS 16.1+ ! It will simply do nothing on other platform & < iOS 16.1


flutter ios 16 live activities dynamic island flutter ios 16 live activities lockscreen
flutter ios 16 live activities preview dynamic island flutter ios 16 live activities preview action

๐Ÿ‘ป Getting started #

Due to some 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

  • ๐Ÿ“ฑ Native #

    • Open the Xcode workspace project ios/Runner.xcworkspace.
    • Click on File -> New -> Target...
      • Select Widget Extension & click on Next.
      • Specify the product name (MyAppWidget for eg.) & be sure to select "Runner" in "Embed in Application" dropdown.
      • Click on Finish.
      • When selecting Finish, an alert will appear, you will need to click on Activate.
create widget extension xcode
  • Enable push notification capabilities on the main Runner app only!.
enable push notification capabilities
  • Enable live activity by adding this line in Info.plist for both Runner & your Widget Extension.
<key>NSSupportsLiveActivities</key>
<true/>
enable live activities xcode
  • Create App Group for both Runner & your Widget Extension.
enable live activity

โ„น๏ธ You can check on this ressource or here for more native informations.

  • ๐Ÿ’™ Flutter #

    • Import the plugin.
    import 'package:live_activities/live_activities.dart';
    
    • Initialize the Plugin by passing the created App Group Id (created above).
    final _liveActivitiesPlugin = LiveActivities();
    _liveActivitiesPlugin.init(appGroupId: "YOUR_CREATED_APP_ID");
    
    • Create your dynamic activity.
    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


Access Flutter basic data from Native ๐Ÿงต #

  • In your Swift extension, you need to create an UserDefaults instance to access data:
let sharedDefault = UserDefaults(suiteName: "YOUR_CREATED_APP_ID")!

โš ๏ธ Be sure to use the SAME group id in your Swift extension and your Flutter app!

  • Access to your typed data:
let pizzaName = sharedDefault.string(forKey: "name")! // put the same key as your Dart map
let pizzaPrice = sharedDefault.float(forKey: "price")
let quantity = sharedDefault.integer(forKey: "quantity")
// [...]

Access Flutter picture from Native ๐Ÿงต #

  • In your map, send a 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 ๐Ÿ‘.

  • In your Swift extension, display the image:
if let assetImage = sharedDefault.string(forKey: "assetKey"), // <-- Put your key here
  let uiImage = UIImage(contentsOfFile: shop) {
  Image(uiImage: uiImage)
      .resizable()
      .frame(width: 53, height: 53)
      .cornerRadius(13)
} else {
  Text("Loading")
}

Communicate over Native ๐Ÿงต and Flutter ๐Ÿ’™ #

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.

  • Add a custom url scheme in Xcode by navigating to Runner > Runner > URL Types > URL Schemes
add url scheme xcode
  • In your Swift code, just create a new link and open to your custom URL Scheme
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.

  • In your Flutter App, you just need to listen on the url scheme Scheme
_liveActivitiesPlugin.urlSchemeStream().listen((schemeData) {
  // do what do you want here ๐Ÿค—
});

๐Ÿ“˜ Documentation #

NameDescriptionReturned 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 activityString The activity identifier
.updateActivity()Update the live activity data by using the activityId providedFuture When the activity was updated
.endActivity()End the live activity by using the activityId providedFuture When the activity was ended
.getAllActivitiesIds()Get all activities ids createdFuture<List<String>> List of all activities ids
.endAllActivities()End all live activities of the appFuture When all activities was ended
.areActivitiesEnabled()Check if live activities feature are supported & enabledFuture<bool> Live activities supported or not
.getActivityState()Get the activity current stateFuture<LiveActivityState> An enum to know the status of the activity (active, dismissed or ended)
.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 picturesFuture Picture removed

๐Ÿ‘ฅ Contributions #

Contributions are welcome. Contribute by creating a PR or create an issue ๐ŸŽ‰.

๐ŸŽฏ Roadmap #

  • Inject a Widget inside the notification with Flutter Engine ?
  • Pass media between extension & Flutter app.
  • Support multiple type instead of String (Date, Number etc.).
  • Pass data across native dynamic island and Flutter app.
  • Pass data across native live activity notification and Flutter app.
  • Cancel all activities.
  • Get all activities ids.
  • Check if live activities are supported.