Use RelevanceKit to tell the Apple Watch Smart Stack when a widget matters by time, location, fitness state, sleep schedule, or connected hardware. Targets Swift 6.3 and watchOS 26+ relevant-widget workflows.
Beta-sensitive. Re-check current Apple documentation before changing availability, signatures, or Smart Stack behavior.
Contents
- Choose a provider
- Scope boundaries
- Signals and permissions
- Provider invariants
- Testing
- Common mistakes
- Review checklist
- References
Choose a provider
Use one of two models:
- Add
relevance()to an existingAppIntentTimelineProviderwhen the widget always has timeline content and relevance is supplementary. - Use
RelevanceConfigurationwith aRelevanceEntriesProviderwhen the widget should appear only under matching conditions or create multiple relevant cards. This path is watchOS 26+.
Read RelevanceKit patterns for complete
providers, every RelevantContext factory, permissions, grouping,
associatedKind, previews, and RelevantIntentManager updates.
RelevantContext is declared across Apple platforms, but its relevance effect
is watchOS-only. Shared provider code may compile elsewhere without changing
widget visibility there.
Scope boundaries
Keep this skill focused on RelevantContext, WidgetRelevanceAttribute,
provider relevance(), RelevanceConfiguration, grouping,
RelevantIntentManager, and permissions required by relevance clues.
Route these sibling concerns elsewhere:
- Widget timelines, families, reload budgets, rendering, push reloads, Live
Activities, and controls →
widgetkit. - Workout sessions, activity/sleep queries, routes, and HealthKit authorization
UX →
healthkit. - Geocoding, place search, directions, regions, geofencing, and location
authorization architecture →
mapkit.
Signals and permissions
| Context | Use | Required setup |
|---|---|---|
.date(...) |
Moment, scheduled event, or date interval | None |
.location(inferred:) |
Home, work, school, commute | App location permission plus NSWidgetWantsLocation |
.location(_:) |
Specific CLRegion |
Same location setup |
.location(category:) |
Nearby point-of-interest category | Same setup; returns optional |
.fitness(.workoutActive) |
Active workout | HealthKit read access to HKWorkoutType |
.fitness(.activityRingsIncomplete) |
Ring progress | Exact exercise/move/stand read types |
.sleep(...) |
Bedtime or wakeup | Sleep-analysis read access |
.hardware(headphones:) |
Headphone connection | None |
Location purpose strings belong in the containing app. The widget extension
declares NSWidgetWantsLocation and checks
CLLocationManager.isAuthorizedForWidgetUpdates. Enable HealthKit and request
the exact read types in every target that supplies fitness or sleep relevance.
Provider invariants
- Return
WidgetRelevanceAttributevalues in priority order; the system may use only a subset. location(category:)is optional—omit unsupported categories rather than force-unwrapping.- A relevance entries provider supplies
relevance,entry,placeholder, and a deterministic preview path. - When timeline and relevant widgets represent the same data, set
.associatedKind(_:)to avoid duplicate Smart Stack cards. - Use
.automatic,.ungrouped, or.namedgrouping intentionally. - For timeline-provider relevance, call
RelevantIntentManager.shared.updateRelevantIntentswhenever source data changes, not only during timeline refresh. - Degrade gracefully when authorization is absent; do not manufacture false location, fitness, or sleep clues.
Testing
- Enable WidgetKit Developer Mode on the Apple Watch.
- Preview entry and configuration states at relevant display sizes.
- Exercise permission granted, denied, restricted, and unavailable data paths.
- Verify ordering, grouping, and duplicate suppression with realistic entries.
- Finish on a physical watch; do not treat compilation or iOS preview behavior as proof of Smart Stack ranking.
Common Mistakes
- Expecting RelevanceKit calls to affect iOS widget ranking.
- Creating a relevant widget when a normal timeline plus relevance is sufficient.
- Returning location clues without widget-update authorization.
- Failing to refresh relevant intents after source data changes.
- Omitting
associatedKindand creating duplicate cards. - Assuming every point-of-interest category creates a context.
Review Checklist
- Provider model matches always-available versus condition-only content.
- Relevance scope is separated from WidgetKit, HealthKit, and MapKit ownership.
- Every clue has its exact permission and availability setup.
- Attributes are priority-ordered and unsupported optionals are omitted.
- Entry, placeholder, relevance, and preview paths are deterministic.
- Grouping and
associatedKindprevent unwanted duplicates. - Relevant intents update whenever underlying data changes.
- Physical-watch testing covers permission and ranking behavior.