I have done some research on the iOS widget refresh mechanism:
1 With containing app in the foreground, the widget refresh is not limited
Read the apple developer docs, I learned that the widget refresh is controlled by the WidgetKit budgets. As it states:
For a widget the user frequently views, a daily budget typically includes from 40 to 70 refreshes
But in the following cases, the reload doesn’t count against the widget’s budget:
- The widget’s containing app is in the foreground.
- The widget’s containing app has an active audio or navigation session.
- The system locale changes.
- Dynamic Type or Accessibility settings change.
2 We can use WidgetCenter.shared.reloadTimelines to refresh widget from containing app
The same doc says:
In the game widget example above, if the app receives a push notification indicating a teammate has given the character a healing potion, the app can tell WidgetKit to reload the timeline and update the widget’s content.
3 I have seen some great implementation on this
Apps like LiveIn gives me a smooth user experience with widget refresh timely when I got a post from my friends (as long as the containing app is in the foreground, guess they can improve this with Background Refresh).
This product is not limited by the daily 40 to 70 refreshes budget limitation, and I get a little delay (little enough to be ignored) between the picture display in containing app and the widget.
4 But I’m still stuck here
But when I tried to build an app using the above API WidgetCenter.shared.reloadTimelines or WidgetCenter.shared.reloadAllTimelines to notify the widget to refresh with data stored in UserDefaults, my widget does not respond to the API call timely. Sometimes, it may be stuck for more than 10 minutes, which is a terrible case far far away from the product I mentioned above.
5 Some hack attempts
I have looked through so many Stackoverflow QAs & blogs and do find some tricky things in the iOS widget. For example, the View._clockHandRotationEffect(.secondHand, in: .current, anchor: .center) API can be used to refresh the widget view without limits (usually used to build clock based applications).
But it seems to have nothing to do with the message notification between the containing app and the widget (or it is just I have not figured it out yet).
6 My question
So here comes my question. As some apps existing on the iOS store already have the capability to notify widgets timely, why can I still not get the smooth user experience guided by the official documentation? Do I miss some things important here, or they are just using other private APIs that are out of my sight?
The code is not complex and the Xcode signing is annoying, so I do not prepare a minimal project to reproduce this. You may take pawello2222/WidgetExamples as a demo if you want to give it a try. Any hints or clues will be highly appreciated!
2
Answers
Finally, we get a smooth user experience. The solution is quite strange at first glance but works like a charm compared to our earlier implementation.
All you need to do is to call
WidgetCenter.shared.reloadTimelinesorWidgetCenter.shared.reloadAllTimelinesafter the application goes into foreground as soon as possible.Why? As the doc Managing Your App's Life Cycle states:
The doc is clear but the time is also important, there are some phenomenons we test to be as is but cannot be found in any official documentation (running app in release, not debug mode with xcode connected):
WidgetCenter.shared.reloadTimelinesorWidgetCenter.shared.reloadAllTimelinesconstantly, the delay will increase significantly as time goes byWidgetCenter.shared.reloadTimelinesorWidgetCenter.shared.reloadAllTimelinesafter the app starts ASAP, the widget view will refresh instantly (almost 100% success rate)I've seen many developers stuck in the refresh mystery of the iOS widget and give up using it finally. Hope my experience will help others a better understanding and make a decision more quickly.
@Lebecca I just want to add more insights from my side. Hope you find it helpful.
In my app I call WidgetCenter.shared.reloadAllTimelines just before my app goes to background. I have no problem with this Reload at all. Reload success rate is 100%.
From my experience, when app goes to background, you have few seconds to do some work, after that the process is killed. It is possible that your widget need more time to reload than the time allowed. That’s why you do not see the Reload consistently. And that the solution that you call WidgetCenter.shared.reloadTimelines as soon as application goes into foreground fix this because you give the widget "more" time for it to finish the Reload. (When app in foreground, you do not have limit on processing time.)
There are 3 parts involving widget reload.
Data for the widget: if your app need to run some code or retrieve some information from the network. Be sure it doesn’t take too long, otherwise the widget reload process can be killed.
Complexity of the widget: Here I mean whether your widget view is complex or not. Many Stacks, many elements will potentially cause the widget Reload to fail.
How many timeline entries you have: Say if you have 100 timeline entries for a day, this might cause some problems as well. You need to find the balance of timeline entries and number of Reloads you plan to run on a day.
Widget Reload budget. I always try to keep it around 40-50 times per day, just to be safe.
Widget is really a mystery. Above are all from my experience.