Principles of great widgets

• provide as many timeline future entries as possible (when it makes sense for your app)

• support as many sizes as you possible, so that users have choice when placing their widgets

Widgets relevance

• Time

• Presentation

• Location

Widgets reloads

• Individual background reload budgets

• Budget updates throughout the day

• Influenced by viewing habits

• Variable update cadence per widget

• Updates are withheld until new budget is available

• A frequently viewed widget can be expected to receive 40-70 background updates per day

• Reloads are on the order of minutes/hours, not seconds

Ways the widget will refresh

• TimelineReloadPolicy API

  • Scheduled background updates atEnd afterDate: never

  • informs the system when you’d like to automatically refresh your widget in the background

• WidgetCenter API

  • Event-based triggers .reloatTimelines(ofKind:) .reloadAllTimelines

  • free when:

    • the reload occurs when the host app is in the foreground

    • the user is in a current session, like Navigation or Now Playing audio

• Significant location changes

  • budget-free update when the system detects a significant location change

  • this free refresh occurs when the user views your widget (not when the location changes)

• System updates

  • when a big change in the system happen:

    • the user changes an Accessibility preference like dynamic text or bold text

    • language or region change

    • iCloud or App Store account change

    • significant time change

    • and more

TimelineReloadPolicy

• atEnd

  • marks your widget eligible to be refreshed when the current timeline last entry becomes relevant

  • recommended if your widget already has content that extends beyond the life of its current timeline

  • not recommended for single-entry timeline, as the system would choose a reload time for you

  • not recommended for data that loses accuracy over time (e.g. weather)

  • Apple apps using atEnd policy: Reminders, Calendar, Photos, Tips, and more

• afterDate

  • marks your widget eligible to be refreshed after the date you specify

  • recommended for widgets showing unpredictable data (that can change unpredictably/unexpectedly)

  • recommended for widgets showing data whose accuracy or relevance changes periodically

  • Apple apps using afterDate policy: Stocks, Weather, News, Mail, and more

  • be cautious of:

    • very frequent reloads (you risk to consume all refresh budget)

    • setting a date where new data will be available

    • (if backend data driven) to not overload your servers (add jitter to the data, use caching servers)

• never

  • it never refreshes automatically

  • recommended for content that:

    • only changes through user interaction

    • doesn’t change

    • gated on conditional access

• • Use WidgetCenter API to refresh from foreground application or events

  • Apple apps using never policy: TV, notes, music, podcast, contacts, and more

Appearance

Full privacy redactions

• Individual views may now be automatically masked in privacy-sensitive environments

• new privacySensitive(_:) view modifier: when the user is not authenticated, the view will automatically be masked/redacted

default-data-protection entitlement

If your app leverages complete data protection that can’t be accessed while an iOS device is passcode locked (e.g. Health data), you can now tell WidgetKit to:

• replace your active timeline content with your placeholder content when the device is passcode locked for a full redaction of content

• withhold updates while the device is passcode locked

Adopt the entitlement com.apple.developer.default-data-protection with value NSFileProtectionComplete to opt in into this behavior

Location

If you’d like to use user location in your widget:

1. add NSWidgetUsesLocation with true value in your Info.plist

2. use CLLocationManager from your TimelineProvider in your widget extension

• use the lowest resolution possible (for faster location resolution and less battery usage)

• use isAuthorizedForWidgetUpdates to check whether the widget can get the user location

Widget location permission

Based on app permission:

• never: ❌

• ask next time (“allow once”): ❌

• while using app: only when the widget’s container app is in the foreground or other situations that would consider the app to be in-use, like being in a navigation session

• while using app or widgets: same as “while using app”, plus the widget can receive location up to 15 minutes after it was last viewed

• always: ✅