Relevancekit

RelevanceKit

Provide on-device contextual clues that increase a widget's visibility in the Apple Watch Smart Stack. RelevanceKit tells the system when a widget is relevant by time, location, fitness state, sleep schedule, or connected hardware. Targets Swift 6.3 / watchOS 26+.

Beta-sensitive. Re-check Apple documentation before making strong RelevanceKit availability or behavior claims.

See references/relevancekit-patterns.md for complete relevant-widget, timeline provider, grouping, preview, and permission patterns.

Contents

• Overview
• Setup
• Relevance Providers
• Boundary Routing
• Time-Based Relevance
• Location-Based Relevance
• Fitness and Sleep Relevance
• Hardware Relevance
• Combining Signals
• Widget Integration
• Common Mistakes
• Review Checklist
• References

Overview

watchOS uses two mechanisms to determine widget relevance in the Smart Stack:

1. Timeline provider relevance -- implement relevance() on an existing AppIntentTimelineProvider to attach RelevantContext clues to timeline entries. Available across platforms; only watchOS acts on the data.
2. Relevant widget -- use RelevanceConfiguration with a RelevanceEntriesProvider to build a widget driven entirely by relevance clues. The system creates individual Smart Stack cards per relevant entry. watchOS 26+ only.

Choose a timeline provider when the widget always has data to show and relevance is supplementary. Choose a relevant widget when the widget should only appear when conditions match, or when multiple cards should appear simultaneously (e.g., several upcoming calendar events).

Key Types

RelevanceConfiguration, RelevanceEntriesProvider, and RelevanceEntry are WidgetKit APIs. Keep them in this skill's scope only when they are part of the watchOS relevant-widget workflow that exposes RelevanceKit clues.

Setup

Import

import RelevanceKit
import WidgetKit

Platform Availability

RelevantContext is declared across platforms (iOS 17+, watchOS 10+), but RelevanceKit functionality only takes effect on watchOS. Calling the API on other platforms has no effect. Timeline-provider relevance() is available on iOS 18+, macOS 15+, visionOS 26+, and watchOS 11+ for shared provider code. RelevanceConfiguration, RelevanceEntriesProvider, and RelevanceEntry are watchOS 26+ only.

Permissions

Certain relevance clues require authorization or target setup:

Add location purpose strings to the containing app's Info.plist, not only the widget extension. In widget code, check CLLocationManager.isAuthorizedForWidgetUpdates before relying on location clues. For fitness and sleep clues, enable HealthKit and request the exact read types in the app and widget extension target that provides relevance.

Relevance Providers

Option 1: Timeline Provider with Relevance

Add a relevance() method to an existing AppIntentTimelineProvider. This approach shares code across iOS and watchOS while adding watchOS Smart Stack intelligence.

struct MyProvider: AppIntentTimelineProvider {
    // ... snapshot, timeline, placeholder ...

    func relevance() async -> WidgetRelevance<MyWidgetIntent> {
        let attributes = events.map { event in
            let context = RelevantContext.date(
                from: event.startDate,
                to: event.endDate
            )
            return WidgetRelevanceAttribute(
                configuration: MyWidgetIntent(event: event),
                context: context
            )
        }
        return WidgetRelevance(attributes)
    }
}

Option 2: RelevanceEntriesProvider (watchOS 26+)

Build a widget that only appears when conditions match. The system calls relevance() to learn when the widget matters, then calls entry() with the matching configuration to get render data.

@available(watchOS 26.0, *)
struct MyRelevanceProvider: RelevanceEntriesProvider {
    func relevance() async -> WidgetRelevance<MyWidgetIntent> {
        let attributes = events.map { event in
            WidgetRelevanceAttribute(
                configuration: MyWidgetIntent(event: event),
                context: RelevantContext.date(event.date, kind: .scheduled)
            )
        }
        return WidgetRelevance(attributes)
    }

    func entry(
        configuration: MyWidgetIntent,
        context: Context
    ) async throws -> MyRelevanceEntry {
        if context.isPreview {
            return .preview
        }
        return MyRelevanceEntry(event: configuration.event)
    }

    func placeholder(context: Context) -> MyRelevanceEntry {
        .placeholder
    }
}

Boundary Routing

When a feature mixes widgets, location, workouts, and Smart Stack relevance, keep RelevanceKit focused on RelevantContext, WidgetRelevanceAttribute, provider relevance(), RelevantIntentManager, relevant-widget handoffs, and permissions for relevance clues. Route timelines, reload budgets, families, rendering, APNs widget pushes, Live Activities, and widget Controls to WidgetKit; HKWorkoutSession, HKLiveWorkoutBuilder, HKWorkoutRoute, queries, activity-ring/sleep data, and authorization UX to HealthKit; and MKLocalSearch, MKLocalSearchCompleter, MKDirections, geocoding, authorization, regions, geofencing, and place data to MapKit/CoreLocation.

Time-Based Relevance

Time clues tell the system a widget matters at or around a specific moment.

Single Date

RelevantContext.date(eventDate)

Date with Kind

DateKind provides an additional hint about the nature of the time relevance:

RelevantContext.date(meetingStart, kind: .scheduled)

Date Range

// Using from/to
RelevantContext.date(from: startDate, to: endDate)

// Using DateInterval
RelevantContext.date(interval: dateInterval, kind: .scheduled)

// Using ClosedRange
RelevantContext.date(range: startDate...endDate, kind: .default)

Location-Based Relevance

Inferred Locations