diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
new file mode 100644
index 00000000..4a3c12c9
--- /dev/null
+++ b/.github/FUNDING.yml
@@ -0,0 +1 @@
+github: abausg
\ No newline at end of file
diff --git a/.github/assets/target_membership.png b/.github/assets/target_membership.png
new file mode 100644
index 00000000..56f08d61
Binary files /dev/null and b/.github/assets/target_membership.png differ
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 66ea045f..fa16460d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -75,14 +75,19 @@ jobs:
strategy:
matrix:
device:
- - "iPhone 13"
+ - "iPhone 14"
fail-fast: false
- runs-on: macos-latest
+ runs-on: macos-13
steps:
- uses: actions/checkout@v2
+ - uses: maxim-lobanov/setup-xcode@v1
+ with:
+ xcode-version: latest
+ - name: Download iOS 17
+ run: xcodebuild -downloadPlatform ios
- uses: subosito/flutter-action@v1
with:
- channel: stable
+ channel: beta
- uses: futureware-tech/simulator-action@v1
id: simulator
with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad4e2777..6876aa1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 0.4.0
+* Add support for Interactive Widgets on iOS
+* Rename `registerBackgroundCallback` to `registerInteractivityCallback`
+* Restructure README
+
## 0.3.1
* fix: Fix Null Pointer when Saving `renderFlutterWidget` by [milindgoel15](https://github.com/milindgoel15) in [#182](https://github.com/ABausG/home_widget/pull/182)
* fix: Update Gradle to 8 by [milindgoel15](https://github.com/milindgoel15) in [#155](https://github.com/ABausG/home_widget/pull/155)
diff --git a/README.md b/README.md
index bfa77ba0..39648ff5 100644
--- a/README.md
+++ b/README.md
@@ -17,49 +17,6 @@ HomeWidget does **not** allow writing Widgets with Flutter itself. It still requ
## Platform Setup
In order to work correctly there needs to be some platform specific setup. Check below on how to add support for Android and iOS
-Android
-
-### Create Widget Layout inside `android/app/src/main/res/layout`
-
-### Create Widget Configuration into `android/app/src/main/res/xml`
-```xml
-
-
-
-```
-
-### Add WidgetReceiver to AndroidManifest
-```xml
-
-
-
-
-
-
-```
-
-### Write your WidgetProvider
-For convenience, you can extend from [HomeWidgetProvider](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetProvider.kt) which gives you access to a SharedPreferences Object with the Data in the `onUpdate` method.
-In case you don't want to use the convenience Method you can access the Data using
-```kotlin
-import es.antonborri.home_widget.HomeWidgetPlugin
-...
-HomeWidgetPlugin.getData(context)
-```
-which will give you access to the same SharedPreferences
-
-### More Information
-For more Information on how to create and configure Android Widgets, check out [this guide](https://developer.android.com/develop/ui/views/appwidgets) on the Android Developers Page.
-
-iOS
### Add a Widget to your App in Xcode
@@ -106,11 +63,56 @@ let data = UserDefaults.init(suiteName:"YOUR_GROUP_ID")
```
Android
+
+### Create Widget Layout inside `android/app/src/main/res/layout`
+
+### Create Widget Configuration into `android/app/src/main/res/xml`
+```xml
+
+
+
+```
+
+### Add WidgetReceiver to AndroidManifest
+```xml
+
+
+
+
+
+
+```
+
+### Write your WidgetProvider
+For convenience, you can extend from [HomeWidgetProvider](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetProvider.kt) which gives you access to a SharedPreferences Object with the Data in the `onUpdate` method.
+In case you don't want to use the convenience Method you can access the Data using
+```kotlin
+import es.antonborri.home_widget.HomeWidgetPlugin
+...
+HomeWidgetPlugin.getData(context)
+```
+which will give you access to the same SharedPreferences
+
+### More Information
+For more Information on how to create and configure Android Widgets, check out [this guide](https://developer.android.com/develop/ui/views/appwidgets) on the Android Developers Page.
+
+iOS
For iOS, you need to call `HomeWidget.setAppGroupId('YOUR_GROUP_ID');`
Without this you won't be able to share data between your App and the Widget and calls to `saveWidgetData` and `getWidgetData` will return an error
+Dart
-In order for these methods to work you need to follow these steps:
+1. Write a **static** function that takes a Uri as an argument. This will get called when a user clicks on the View
+ ```dart
+ @pragma("vm:entry-point")
+ FutureOr backgroundCallback(Uri data) async {
+ // do something with data
+ ...
+ }
+ ```
+ `@pragma('vm:entry-point')` must be placed above the `callback` function to avoid tree shaking in release mode.
-#### iOS
-Add `.widgetUrl` to your WidgetComponent
-```swift
-Text(entry.message)
- .font(.body)
- .widgetURL(URL(string: "homeWidgetExample://message?message=\(entry.message)&homeWidget"))
-```
-In order to only detect Widget Links you need to add the queryParameter`homeWidget` to the URL
+2. Register the callback function by calling
+ ```dart
+ HomeWidget.registerInteractivityCallback(backgroundCallback);
+ ```
+iOS
-In your WidgetProvider add a PendingIntent to your View using `HomeWidgetLaunchIntent.getActivity`
-```kotlin
-val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity(
- context,
- MainActivity::class.java,
- Uri.parse("homeWidgetExample://message?message=$message"))
-setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
-```
+1. Adjust your Podfile to add `home_widget` as a dependency to your WidgetExtension
+ ```
+ target 'YourWidgetExtension' do
+ use_frameworks!
+ use_modular_headers!
-### Background Click
+ pod 'home_widget', :path => '.symlinks/plugins/home_widget/ios'
+end
+ ```
+2. To be able to use plugins with the Background Callback add this to your AppDelegate's `application` function
+ ```swift
+ if #available(iOS 17, *) {
+ HomeWidgetBackgroundWorker.setPluginRegistrantCallback { registry in
+ GeneratedPluginRegistrant.register(with: registry)
+ }
+ }
+ ```
+3. Create a custom `AppIntent` in your App Target (Runner) and make sure to select both your App and your WidgetExtension in the Target Membership panel
+
+ 
+
+ In this Intent you should import `home_widget` and call `HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)` in the perform method. `url` and `appGroup` can be either hardcoded or set as parameters from the Widget
+ ```swift
+ import AppIntents
+ import Flutter
+ import Foundation
+ import home_widget
+
+ @available(iOS 16, *)
+ public struct BackgroundIntent: AppIntent {
+ static public var title: LocalizedStringResource = "HomeWidget Background Intent"
+
+ @Parameter(title: "Widget URI")
+ var url: URL?
+
+ @Parameter(title: "AppGroup")
+ var appGroup: String?
+
+ public init() {}
+
+ public init(url: URL?, appGroup: String?) {
+ self.url = url
+ self.appGroup = appGroup
+ }
+
+ public func perform() async throws -> some IntentResult {
+ await HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)
+
+ return .result()
+ }
+ }
+ ```
+4. Add a Button to your Widget. This Button might be encapsulated by a Version check. Pass in an instance of the `AppIntent` created in the previous step
+ ```swift
+ Button(
+ intent: BackgroundIntent(
+ url: URL(string: "homeWidgetExample://titleClicked"), appGroup: widgetGroupId)
+ ) {
+ Text(entry.title).bold().font( /*@START_MENU_TOKEN@*/.title /*@END_MENU_TOKEN@*/)
+ }.buttonStyle(.plain)
+ ```
+5. With the current setup the Widget is now Interactive as long as the App is still in the background. If you want to have the Widget be able to wake the App up you need to add the following to your `AppIntent` file
+ ```swift
+ @available(iOS 16, *)
+ @available(iOSApplicationExtension, unavailable)
+ extension BackgroundIntent: ForegroundContinuableIntent {}
+ ```
+ This code tells the system to always perform the Intent in the App and not in a process attached to the Widget. Note however that this will start your Flutter App using the normal main entrypoint meaning your full app might be run in the background. To counter this you should add checks in the very first Widget you build inside `runApp` to only perform necessary calls/setups while the App is launched in the background
+Android
-#### Android/Native Part
1. Add the necessary Receiver and Service to you `AndroidManifest.xml` file
```
-
+
@@ -204,26 +252,13 @@ With home_widget you can use this by following these steps:
)
setOnClickPendingIntent(R.id.widget_title, backgroundIntent)
```
+Dart
For example, say you have a chart in your Flutter app configured with `CustomPaint`:
```dart
@@ -247,9 +282,9 @@ class LineChart extends StatelessWidget {
-Rewriting the code to create this chart on both Android and iOS might be time consuming.
-Instead, you can generate a png file of the Flutter widget and save it to a shared container
-between your Flutter app and the home screen widget.
+Rewriting the code to create this chart on both Android and iOS might be time consuming.
+Instead, you can generate a png file of the Flutter widget and save it to a shared container
+between your Flutter app and the home screen widget.
```dart
var path = await HomeWidget.renderFlutterWidget(
@@ -260,8 +295,9 @@ var path = await HomeWidget.renderFlutterWidget(
```
- `LineChart()` is the widget that will be rendered as an image.
- `key` is the key in the key/value storage on the device that stores the path of the file for easy retrieval on the native side
+iOS
To retrieve the image and display it in a widget, you can use the following SwiftUI code:
1. In your `TimelineEntry` struct add a property to retrieve the path:
@@ -295,7 +331,7 @@ To retrieve the image and display it in a widget, you can use the following Swif
…
}
```
-
+
4. Display the chart in the body of the widget's `View`:
```swift
VStack {
@@ -306,8 +342,9 @@ To retrieve the image and display it in a widget, you can use the following Swif
```
+Android
1. Add an image UI element to your xml file:
```xml
@@ -360,3 +397,60 @@ To retrieve the image and display it in a widget, you can use the following Swif
}
}
```
+iOS
+
+Add `.widgetUrl` to your WidgetComponent
+```swift
+Text(entry.message)
+ .font(.body)
+ .widgetURL(URL(string: "homeWidgetExample://message?message=\(entry.message)&homeWidget"))
+```
+In order to only detect Widget Links you need to add the queryParameter`homeWidget` to the URL
+Android
+Add an `IntentFilter` to the `Activity` Section in your `AndroidManifest`
+```
+
+
+
+```
+
+In your WidgetProvider add a PendingIntent to your View using `HomeWidgetLaunchIntent.getActivity`
+```kotlin
+val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity(
+ context,
+ MainActivity::class.java,
+ Uri.parse("homeWidgetExample://message?message=$message"))
+setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
+```
+