AppIntentTimelineProvider

protocol · iOS 17.0+ · SDK 27.1

protocol AppIntentTimelineProvider

A type that advises WidgetKit when to update a user-configurable widget's display. An App Intent timeline provider performs the same function as <doc:TimelineProvider>, but it also incorporates user-configured details into timeline entries. For example, in a widget that displays the health status of a game character the user has chosen, the provider receives a custom intent specifying the character to display. In your app code, you then define a custom App Intent. The intent can include the character’s details such as its name, avatar, strategic alliances, and so on. struct CharacterConfiguration: WidgetConfigurationIntent { static var title: LocalizedStringResource = "Character" @Parameter(title: "Name") var name: String @Parameter(title: "Avatar", default: "Player 1") var avatar: String @Parameter(title: "Alliances", default: []) var alliances: [String] @Parameter(title: "Health", default: 100.0) var healthLevel: Double } Because users can add multiple instances of a particular widget, your provider needs a way to differentiate which instance WidgetKit is asking about. When WidgetKit calls <doc:AppIntentTimelineProvider/snapshot(for:in:)> or <doc:AppIntentTimelineProvider/timeline(for:in:)>, it passes an instance of your configuration intent, configured with the user-selected details. The game widget provider accesses the properties of the intent and includes them in the <doc:TimelineEntry>. WidgetKit then invokes the widget configuration's content closure, passing the timeline entry to allow the views to access the user-configured properties. For example, the provider might implement a `TimelineEntry` with properties corresponding to those in the custom intent: struct CharacterDetailEntry: TimelineEntry { var date: Date var name: String var avatar: String var alliances: [String] var healthLevel: Double } To generate a snapshot, the game widget provider initializes the character detail entry using the properties from the intent. struct CharacterDetailProvider: AppIntentTimelineProvider { func snapshot(for configuration: CharacterConfiguration, in context: Context) async -> CharacterDetailEntry { return CharacterDetailEntry( date: Date(), name: configuration.characterName, avatar: configuration.avatar, alliances: configuration.alliances, healthLevel: configuration.healthLevel?.doubleValue ) } }

Members (0)

This type has no directly callable members in this snapshot. See the framework’s skipped declarations for unsupported APIs.

All WidgetKit types →