IntentTimelineProvider

A type that advises WidgetKit when to update a user-configurable widget’s display.

Declaration

protocol IntentTimelineProvider

Mentioned in

Increasing the visibility of widgets in Smart Stacks

Overview

An Intent timeline provider performs the same function as 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 Xcode project, you then define a custom SiriKit Intent Definition file. The intent definition can include the character’s details such as its name, avatar, strategic alliances, and so on.

[Image]

Xcode generates the following INIntent custom intent:

public class SelectCharacterIntent: INIntent {
    @NSManaged public var characterName: String?
    @NSManaged public var avatar: String?
    @NSManaged public var alliances: [String]?
    @NSManaged public var healthLevel: NSNumber?
}

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 getSnapshot(for:in:completion:) or getTimeline(for:in:completion:), it passes an instance of your custom INIntent, configured with the user-selected details. The game widget provider accesses the properties of the intent and includes them in the 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: IntentTimelineProvider {
    func getSnapshot(for configuration: SelectCharacterIntent, in context: Context, completion: @escaping (CharacterDetailEntry) -> Void) {
        let entry = CharacterDetailEntry(
            date: Date(),
            name: configuration.characterName,
            avatar: configuration.avatar,
            alliances: configuration.alliances,
            healthLevel: configuration.healthLevel?.doubleValue
        )
        completion(entry)
    }
}

Topics

Generating Timelines

Instance Methods

relevance()