skip to content

With UserNotifications' interruption levels, how should an iOS lead decide which concert-app alerts are time-sensitive, active or passive, and keep that rule enforced?

level: principalimportance: should knowfreq 30%

answer

  1. four levels since iOS 15
  2. breaking through Focus and the summary
  3. an entitlement, not an authorization option
  4. the person can switch time-sensitive off
  5. relevanceScore sorts; it does not interrupt

basics

~20 s

Make time-sensitive the exception, for alerts that lose their value within the hour such as a gate change; keep reminders active and nice-to-know news passive; set interruptionLevel and relevanceScore in one reviewed place, and leave critical to Apple-approved safety cases.

solid answer

~50 s

Since iOS 15 every notification has an `interruptionLevel`: `.passive` goes quietly to the list, `.active` is the default, `.timeSensitive` can break through Focus and the scheduled summary, and `.critical` bypasses the mute switch and needs an entitlement Apple must approve. My rule for a ticket app: time-sensitive only when acting late costs the fan something right now (a gate change, a cancelled show), active for the doors reminder, passive for tour announcements and small set-time tweaks. Time-sensitive comes from the time-sensitive entitlement plus the level, not the deprecated `UNAuthorizationOptions.timeSensitive`, and each person can switch it off, which `timeSensitiveSetting` reports. I'd keep the mapping in one function and one server-side table that set `interruptionLevel` or the payload's `interruption-level`, plus `relevanceScore` for summary order, and make every new time-sensitive case a reviewed change, because overuse teaches people to turn the privilege off.

code

swift · 29 lines
swift
import UserNotifications

enum ConcertAlert {
    case gateChange, doorsReminder, newTourDate, setTimesTweak
}

// One function owns the mapping, so a level change is reviewed in one place.
func content(for alert: ConcertAlert, title: String, body: String) -> UNMutableNotificationContent {
    let content = UNMutableNotificationContent()
    content.title = title
    content.body = body
    switch alert {
    case .gateChange:
        content.interruptionLevel = .timeSensitive  // needs the time-sensitive entitlement
        content.relevanceScore = 1.0
    case .doorsReminder:
        content.interruptionLevel = .active
        content.relevanceScore = 0.7
    case .newTourDate, .setTimesTweak:
        content.interruptionLevel = .passive
        content.relevanceScore = 0.2
    }
    return content
}

func canBreakThrough() async -> Bool {
    let settings = await UNUserNotificationCenter.current().notificationSettings()
    return settings.timeSensitiveSetting == .enabled
}

go deeper

for a junior

Recall the four interruption levels and that active is the default when nothing is set.

for a middle

Explain how time-sensitive differs from active and critical, and why it comes from an entitlement rather than an authorization option.

for a senior

Show how levels travel in code and in the interruption-level payload key, and how timeSensitiveSetting changes what an alert can actually do.

for a principal

Own the trade-off between reach today and trust tomorrow: a written test for time-sensitive, one mapping, reviewed changes and a metric that shows erosion.

## The four levels An **interruption level** tells the system how strongly a notification may interrupt the person. It arrived in iOS 15 as `UNNotificationInterruptionLevel`, set on `UNMutableNotificationContent.interruptionLevel` for local notifications and through the `interruption-level` key in a push's `aps` dictionary (`"passive"`, `"active"`, `"time-sensitive"`, `"critical"`). | Level | What the system does | What it needs | |---|---|---| | `.passive` | Adds it to the notification list; no screen wake, no sound | Nothing | | `.active` | Presents it at once, lights the screen, may play a sound; the default | Nothing | | `.timeSensitive` | Like active, but can break through Notification Summary and Focus | The time-sensitive entitlement | | `.critical` | Always presented, even in Do Not Disturb; bypasses the mute switch | An entitlement Apple must approve, plus the `.criticalAlert` authorization option | Two details trip teams up. First, `UNAuthorizationOptions.timeSensitive` exists in the SDK but was deprecated in iOS 15 with the message "Use time-sensitive entitlement": the privilege comes from the entitlement, and each notification opts in through its level. Second, Apple's documentation says the person can turn off time-sensitive interruptions for the app, and `UNNotificationSettings.timeSensitiveSetting` (iOS 15) reports whether they did. ## Why this is a lead's decision Every feature team believes its alert is urgent. If each one picks a level alone, the app ends up sending ordinary reminders as time-sensitive, and the person's answer is to switch time-sensitive off, or notifications off entirely, which then silences the one alert that mattered. The level is a small API property with a product-wide cost, so it needs one owner and one rule. When to ask for permission and how the server prioritises sends are push-design questions; this decision is about which level each kind of alert gets. ## A rule for a concert-ticket app A workable test is: **does acting an hour late cost the fan something real?** - **Time-sensitive**: venue gate change, show cancelled or moved on the day, entry time slot about to close. - **Active**: the doors-open reminder two hours ahead, a ticket transfer received. - **Passive**: new tour dates, small set-time adjustments, merchandise news. - **Critical**: none. Critical alerts override the mute switch and Do Not Disturb, the entitlement needs Apple's approval, and no ticket alert justifies that. `relevanceScore`, also iOS 15, is a separate lever: a value from 0 to 1 that sorts the app's notifications, with the highest featured in the notification summary. It never raises the interruption, so a high score is not a way to make a passive alert louder. ## Enforcing the rule A rule nobody can see erodes. Make it structural: 1. **One mapping in the app.** A single function or enum turns an alert kind into `interruptionLevel` and `relevanceScore`, as in the example, so local notifications cannot bypass it. 2. **One table on the server.** Pushes set `interruption-level` from the same list of alert kinds, never from a free-text field a campaign tool can fill. 3. **Reviewed changes.** Adding a kind to the time-sensitive set needs the lead's sign-off in review, with the one-hour test written down. 4. **Read what people allowed.** Log `timeSensitiveSetting` alongside notification opens; a falling share of people who allow it is the early warning that the rule is being bent. ## How the level reaches the device The same rule has to hold on both delivery paths: - **Local notifications** set `content.interruptionLevel` (and `relevanceScore`) on the `UNMutableNotificationContent` before the request is added. - **Remote notifications** carry the level as the `interruption-level` string in `aps` and the score as `relevance-score`, a number between 0 and 1. - **Unset means active.** A notification that names no level is delivered as active, so the passive tier only exists where someone set it on purpose. A useful review question for every new alert is therefore twofold: which kind is it, and does the code or server path that sends it go through the shared mapping? ## Trade-offs to weigh - **Reach versus trust.** More time-sensitive alerts reach more people now and fewer later, once they switch the privilege off. - **Entitlement upkeep.** Time-sensitive needs the entitlement in the app's signing; critical needs an approval most products will not get. - **Devices below iOS 15.** With an iOS 17 baseline every supported device honours levels, so the policy can rely on them. - **Passive is not silence.** Passive alerts still land in the list and still count as notifications the person can judge, so they too should earn their place.

  • When would this app ask Apple for the critical-alert entitlement?
    Practically never. Critical alerts bypass the mute switch and always present, even during Do Not Disturb; the entitlement needs Apple's approval, and the app also requests the `.criticalAlert` authorization option. A gate change is urgent, but nothing in a ticket app justifies overriding someone's mute switch; time-sensitive is the right ceiling.
  • Can a high relevanceScore stand in for time-sensitive delivery?
    No. `relevanceScore` only sorts the app's notifications, with the highest featured in the notification summary; it does not change whether a notification breaks through Focus or wakes the screen. Interruption comes only from `interruptionLevel`, so the two are set together but answer different questions.
  • How do you know whether a fan's gate-change alert can actually break through?
    Read `notificationSettings()` and check `timeSensitiveSetting`; if the person turned time-sensitive off for the app, the alert loses its ability to break through Focus and the summary. The app can mention in its settings screen why gate changes matter, but it cannot override the person's choice.

  • Request UNAuthorizationOptions.timeSensitive to unlock time-sensitive alerts.
  • A relevanceScore of 1.0 makes a notification break through Focus.
  • Critical alerts are the right level for any alert the business considers urgent.
  • Once the entitlement is in place, every person receives time-sensitive interruptions.
  • Each feature team should choose interruption levels for its own alerts.

Assumes the iOS 27 SDK on an iOS 17 baseline; interruptionLevel, relevanceScore and timeSensitiveSetting arrived in iOS 15, when UNAuthorizationOptions.timeSensitive was deprecated for the entitlement.