4

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!

Lebecca
  • 2,406
  • 15
  • 32
  • 1
    In my case I was using Swift Concurrency Task.detached, I had not set the priority. Setting the priority as .userInitiated seems to work. `Task.detached(priority: .userInitiated) { }` – user1046037 Dec 06 '22 at 17:35

2 Answers2

2

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.reloadTimelines or WidgetCenter.shared.reloadAllTimelines after the application goes into foreground as soon as possible.

Why? As the doc Managing Your App's Life Cycle states:

a foreground app has the user’s attention, so it has priority over system resources, including the CPU

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):

  • Launch the app in the foreground all the time, notifying the widget to refresh the view by calling WidgetCenter.shared.reloadTimelines or WidgetCenter.shared.reloadAllTimelines constantly, the delay will increase significantly as time goes by
  • When calling WidgetCenter.shared.reloadTimelines or WidgetCenter.shared.reloadAllTimelines after 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
  • 2,406
  • 15
  • 32
  • I have a similar problem, but I don't understand the solution described above. What does the first bullet mean? I think it needs to be re-phrased. – RawMean Sep 13 '22 at 23:32
  • Hi, @RawMean . The key is `call WidgetCenter.shared.reloadTimelines or WidgetCenter.shared.reloadAllTimelines after the application goes into foreground as soon as possible.`. My suggestion is to add a listener, when the app goes into the foreground, refresh your widget here and the success rate will be high. But you also need to know Apple's suggestion for widget refresh is rely on the scheduled timeline, you should make sure the total refresh count is not beyond 70 times per day, or the refresh will be throttled by iOS. If you think the timeline cannot satisfy you, then use my suggestion. – Lebecca Sep 14 '22 at 08:23
  • If the app is in foreground (a user is currently using the app), calling WidgetCenter.shared.reloadAllTimelines should not cause any problem. And this widget refresh isn't counted toward your daily budget. The difficult part is how to reliably refresh the widget timeline when the app is NOT in foreground. I have a similar problem on my widget app since iOS 16.1 update. – Boon Nov 15 '22 at 08:18
  • @Boon Yes, if the app is in the foreground, widget refresh isn't counted toward the app's daily budget. Still, I'm 100% sure that WidgetCenter.shared.reloadAllTimelines may not refresh widgets immediately (very likely, and do not be cheated by an iPhone connected to XCode). – Lebecca Nov 15 '22 at 13:24
1

@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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Boon
  • 111
  • 1
  • 5