Configurable Widgets

Sometimes you want to give your users the ability to configure their HomeScreenWidgets to their liking. For example a weather widget that can show the weather for different locations or a todo list that can show different lists.

iOS

On iOS there are two ways to make your App Configurable. The new and recommended way by Apple is to use WidgetConfigurationIntent you can also provide backwards compatibility using SiriKit Intents

WidgetConfigurationIntent

Create Widget Extension
If you create a new Widget add an extension by going File > New > Target > Widget Extension This time checking the box for Include Configuration App Intent
The generated Widget code includes the following classes:
- AppIntentTimelineProvider - Provides a Timeline of entries at which the System will update the Widget automatically using an AppIntent for configuration
- TimelineEntry - Represents the Data Object used to build the Widget. The date field is necessary and defines the point in time at which the Timeline would update
- View - The Widget itself, which is built with SwiftUI
- Widget - Configuration: Make note of the kind you set in the Configuration as this is what's needed to update the Widget from Flutter.
In a separate file there is a WidgetConfigurationIntent defined that will determine the configuration options of the Widget in AppIntent.swift.

Adjusting the Configuration Intent

You can add fields that appear in the configuration by changing the generated ConfigurationAppIntent class.

@Parameter(title: "Name", default: "World")
var name: String

You can access the fields of the configuration when building the Widget UI

struct ConfigurableWidgetEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text("Hello")
            Text(entry.configuration.name)
        }
    }
}

Getting Data from Flutter to the Configuration

App Groups

In order for sending Data from your Flutter App to the Widget we need to use App Groups.

App Groups require a paid Apple Developer Account

Create a new App Group

Visit the Apple Developer Portal and create a new App Group.

Enable App Groups in XCode

Add the App Group capability to both the App Target (Runner) and your Widget Extension in XCode.

Register App Group in Flutter

In your Flutter code register the App Group with home_widget

import 'package:home_widget/home_widget.dart';
void main() {
    WidgetFlutterBinding.ensureInitialized();
    HomeWidget.setAppGroupId('group.YOUR_APP_GROUP_ID');
    runApp(MyApp());
}

Send Data

You can store data from Flutter for the Widget using HomeWidget.saveWidgetData to use it as options in the configuration panel.

final punctuations = [
    '!',
    '!!!',
    '.',
    '?',
    // Wave Emoji
    '\u{1F44B}',
];
await HomeWidget.saveWidgetData(
    'punctuations',
    jsonEncode(punctuations),
);

Use Values from Flutter as Options in Customize Panel

In XCode and Swift add an AppEntity and matching EntityQuery


@Parameter(title: "Punctuation")
var punctuation: PunctuationEntity
}

// Make Entity Codable so home_widget
// That way home_widget can best extract the values from a configuration
struct PunctuationEntity: AppEntity, Codable {

let id: String

static var typeDisplayRepresentation: TypeDisplayRepresentation = "Punctuation"
static var defaultQuery = PunctuationQuery()

var displayRepresentation: DisplayRepresentation {
    DisplayRepresentation(title: "\(id)")
}
}

struct PunctuationQuery: EntityQuery {

func punctuations() -> [PunctuationEntity] {
    let userDefaults = UserDefaults(suiteName: "YOUR_APP_GROUP")

    do {
    let jsonPunctuations = (userDefaults?.string(forKey: "punctuations") ?? "[\"!\"]").data(
        using: .utf8)!
    let stringArray = try JSONDecoder().decode([String].self, from: jsonPunctuations)
    return stringArray.map { punctuation in
        PunctuationEntity(id: punctuation)

    }
    } catch {
    return [PunctuationEntity(id: "!")]
    }

}

func entities(for identifiers: [PunctuationEntity.ID]) async throws -> [PunctuationEntity] {
    let results = punctuations().filter { identifiers.contains($0.id) }
    return results
}

func suggestedEntities() async throws -> [PunctuationEntity] {
    return punctuations()
}

func defaultResult() async -> PunctuationEntity? {
    try? await suggestedEntities().first
}

}

Now you can access this new parameter in your Widget Code

struct ConfigurableWidgetEntryView: View {
var entry: Provider.Entry

var body: some View {
    VStack {
    Text("Hello")
    Text(entry.configuration.name)
    Text(entry.configuration.punctuation.id)
    }
}
}

Seeing Configuration in Flutter

You need to let home_widget know about the relation of the Intent and the kind (what you need for updating the widget).

Add `Runner` as a Target of the Widget

Open the Intent Swift File and in the Details Pane enable the Target Membership for the Runner Target

Register Configuration in AppDelegate

In your AppDelegate.swift register the Configuration Intent together with the kind of your Widget

import Flutter
import UIKit
import home_widget

@main
@objc class AppDelegate: FlutterAppDelegate {
override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    if #available(iOS 17.0, *) { 
    HomeWidgetPlugin.setConfigurationLookup(to: [ 
        "ConfigurableWidget": ConfigurationAppIntent.self
    ])
    } 
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}

To get the configuration a user made to a Widget you can use HomeWidget.getInstalledWidgets().

final configuration = await HomeWidget.getInstalledWidgets();

this will give you a list of HomeWidgetInfo in there there is a Map<String, dynamic>? configuration.

On iOS Simulators HomeWidget.getInstalledWidgets() will always return an empty list.

To fully test this you should test on a real iOS Device

For our Greeting Example the Configuration would be:

{
    "name": "Documentation",
    "punctuation": {
        "id": "!!!"
    }
}

SiriKit Intents

Before iOS 17 SiriKit Intents where used to build configurable widgets. You can use this to add backwards compatibility.

You could also use SiriKit Intents standalone however it is unclear how long Apple will support this.

Basic setup

Create Intent
Create a new SiriKit Intent File by going to File > New > SiriKit Intent File
Create a new Intent using the + button in the bottom left.
In the Intent set Category to View and enable Intent is eligible for widgets
Add a simple parameter to the Intent. FOr our example a String parameter called name

Using Intent in Widget

To use our custom generated Intent in the generated Widget we need to to adjust the automatically generated code to conform to the correct APIs.

Adjust your SimpleEntry to use properties instead of the Intent so we can use both the AppIntent and the SiriIntent.

struct SimpleEntry: TimelineEntry {
    let date: Date
    let configuration: ConfigurationAppIntent 
    let name: String
    var punctuation: String? = nil
}

Create an IntentTimelineProvider

struct IntentProvider: IntentTimelineProvider {
    typealias Entry = SimpleEntry

    typealias Intent = GreetingIntentIntent

    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), name: "World")
    }

    func getSnapshot(
        for configuration: GreetingIntentIntent, in context: Context,
        completion: @escaping (SimpleEntry) -> Void
    ) {
        completion(SimpleEntry(date: Date(), name: configuration.Name))
    }

    func getTimeline(
        for configuration: GreetingIntentIntent, in context: Context,
        completion: @escaping (Timeline<SimpleEntry>) -> Void
    ) {
        var entries: [SimpleEntry] = []

        // Generate a timeline consisting of five entries an hour apart, starting from the current date.
        let currentDate = Date()
        for hourOffset in 0..<5 {
        let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
        let entry = SimpleEntry(date: entryDate, name: configuration.Name)
        entries.append(entry)
        }

        completion(Timeline(entries: entries, policy: .atEnd))
    }
}

In the Widget definition add code to use the appropriate configuration provider.

var body: some WidgetConfiguration {
    if #available(iOS 17.0, *) { 
    AppIntentConfiguration(
        return AppIntentConfiguration(
            kind: kind, intent: ConfigurationAppIntent.self, provider: Provider()
        ) {
            entry in
            ConfigurableWidgetEntryView(entry: entry)
            .containerBackground(.fill.tertiary, for: .widget)
        }
    } else { 
        return IntentConfiguration(
            kind: kind, 
            intent: GreetingIntentIntent.self, 
            provider: IntentProvider()
        ) { entry in
            ConfigurableWidgetEntryView(entry: entry)
        } 
    } 
}

Getting Data from Flutter to the Configuration

With SiriKit Intents you need to add a new IntentHandler that can handle using Data you send from home_widget.

For this add a new Intents Extension to your App. Using File > New > Target > Intents Extension

In your SiriKit Intents definition add the newly created Extension as a Target

In the same configurations file add a new Type and configure it to the options you need.

Create a Field that uses this new type. Ensuring to enable Options are provided dynamically

Implement the IntentHandler to handle the new Intent

import Intents

class IntentHandler: INExtension, GreetingIntentIntentHandling {

func providePunctuationOptionsCollection(for intent: GreetingIntentIntent) async throws -> INObjectCollection<Punctuation> {
    let userDefaults = UserDefaults(suiteName: "YOUR_APP_GROUP")
    
    do {
        let jsonPunctuations = (userDefaults?.string(forKey: "punctuations") ?? "[\"!\"]").data(using: .utf8)!
        let stringArray = try JSONDecoder().decode([String].self, from: jsonPunctuations)
        let items = stringArray.map { punctuation in
            Punctuation(identifier: punctuation, display: punctuation)
        }
        return INObjectCollection(items: items)
        
    } catch {
        return INObjectCollection(items: [Punctuation(identifier: "!", display: "!")])
    }
}
}

Seeing Configuration in Flutter
Similar to the WidgetConfigurationIntent you can use HomeWidget.getInstalledWidgets() to get the configuration of the Widget.
final configuration = await HomeWidget.getInstalledWidgets();
this will give you a list of HomeWidgetInfo in there there is a Map<String, dynamic>? configuration.
For our Greeting Example the Configuration would be:
{ "Name": "Siri", "Punctuation": { "identifier": "👋", "displayString": "👋" } }

Usage

Platform Setup

Features

Android XML

Configurable Widgets

iOS

WidgetConfigurationIntent

Create Widget Extension

Adjusting the Configuration Intent

Getting Data from Flutter to the Configuration

App Groups

Create a new App Group

Enable App Groups in XCode

Register App Group in Flutter

Send Data

Use Values from Flutter as Options in Customize Panel

Seeing Configuration in Flutter

Add `Runner` as a Target of the Widget

Register Configuration in AppDelegate

SiriKit Intents

Basic setup

Create Intent

Using Intent in Widget

Getting Data from Flutter to the Configuration

Seeing Configuration in Flutter

On this page

Usage

Platform Setup

Features

Android XML

Configurable Widgets

iOS

WidgetConfigurationIntent

Create Widget Extension

Adjusting the Configuration Intent

Getting Data from Flutter to the Configuration

App Groups

Create a new App Group

Enable App Groups in XCode

Register App Group in Flutter

Send Data

Use Values from Flutter as Options in Customize Panel

Seeing Configuration in Flutter

Add Runner as a Target of the Widget

Register Configuration in AppDelegate

SiriKit Intents

Basic setup

Create Intent

Using Intent in Widget

Getting Data from Flutter to the Configuration

Seeing Configuration in Flutter

On this page

Add `Runner` as a Target of the Widget