RelevanceKit

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:

1. Add relevance() to an existing AppIntentTimelineProvider when the widget always has timeline content and relevance is supplementary.
2. Use RelevanceConfiguration with a RelevanceEntriesProvider when 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

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 WidgetRelevanceAttribute values 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 .named grouping intentionally.
• For timeline-provider relevance, call RelevantIntentManager.shared.updateRelevantIntents whenever 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 associatedKind and 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 associatedKind prevent unwanted duplicates.
• Relevant intents update whenever underlying data changes.
• Physical-watch testing covers permission and ranking behavior.

References

• RelevanceKit patterns
• RelevanceKit documentation
• RelevantContext
• Smart Stack widget suggestions
• RelevanceConfiguration
• RelevanceEntriesProvider