Notifications

Notifications can give people timely and important information, whether the device is locked or in use. For example, notifications can signal when a message arrives, an event is about to occur, new data is available, or there’s a status change.

A partial screenshot of the Lock Screen on iPhone on which two notifications appear. The top notification is from Calendar and reads Team Breakfast Apple Park. The second notification is a Messages communication notification from a contact named Sara Tyler that reads Hey! Do we have everything we need for the party on Friday?

People appreciate receiving a notification for something they care about, but they don’t always appreciate being interrupted. To help people manage the overall experience, you need to get permission before sending any notifications; the system lets people change this decision — and adjust alert styles, previews, and Siri interactions — in Settings > Notifications. People can also silence all notifications (except for government alerts in some locales) in Settings > Focus.

For developer guidance, see UserNotifications.

Helping People Manage Notifications

In iOS 15 and later, people can make fine-grained adjustments to notification behavior by specifying delivery times and setting up a Focus. Delivery scheduling lets people choose whether to receive notification alerts immediately or in a summary that’s delivered at times they choose. A Focus helps people filter notifications during a time period they define for an activity like sleeping, working, reading, or driving.

People identify the contacts and apps that can break through a Focus to deliver notification alerts. In a Work Focus, for example, people might want to receive alerts from work colleagues, family members, and work-related apps as soon as notifications arrive. People might also want to receive all Time Sensitive notification alerts during a Focus. A Time Sensitive notification contains essential information people appreciate getting right away.

IMPORTANT Even though a Focus might delay the delivery of a notification alert, the notification itself is available as soon as it arrives.

To support these behavior customizations, you first identify the types of notifications your app can send. If your app supports direct communications — like phone calls and messages — you use communication notifications; for all other types of tasks, you use noncommunication notifications. To support communication notifications, you adopt SiriKit intents, which means people can use Siri to customize notification behaviors; for developer guidance, see INSendMessageIntent and UNNotificationContentProviding.

You specify a system-defined interruption level for each noncommunication notification your app can send. The system uses the interruption level to help determine when to deliver the alert; when a communication notification arrives, the system uses the sender to determine when to deliver the alert.

The system defines four interruption levels for noncommunication notifications:

  • Passive. Information people can view at their leisure, like a restaurant recommendation.
  • Active (the default). Information people might appreciate knowing about when it arrives, like a score update on their favorite sports team.
  • Time Sensitive. Information that directly impacts the user and requires their immediate attention, like an account security issue or a package delivery.
  • Critical. Urgent information about personal health and public safety that directly impacts the user and demands their immediate attention. Critical notifications are extremely rare and typically come from governmental and public agencies or healthcare apps. You must get an entitlement to use the Critical interruption level.

Notification alerts in each system-defined interruption level can behave in the following ways:

Interruption level Overrides scheduled delivery Breaks through Focus Overrides Ring/Silent switch
Passive No No No
Active No No No
Time Sensitive Yes Yes No
Critical Yes Yes Yes

NOTE Because a Critical notification can override the Ring/Silent switch and break through scheduled delivery and Focus, you must get an entitlement to send one.

Build trust by accurately representing the urgency of each notification. People have several ways to adjust how they receive notifications from your app — including turning off all notifications — so it’s essential to be as realistic as possible when assigning an interruption level. You don’t want people to feel that a notification uses a high level of urgency to interrupt them with low-priority information.

Use the Time Sensitive interruption level only for notifications that are relevant in the moment. To help people understand the benefits of letting Time Sensitive notifications break through a Focus or scheduled delivery, make sure the notification is about an event that’s happening now or will happen within an hour. The first time a Time Sensitive notification arrives from your app, the system describes how such a notification works and gives people a way to turn it off if they don’t agree that the information requires their immediate attention. Going forward, the system periodically gives people additional opportunities to evaluate how your Time Sensitive notification is working for them. For developer guidance, see UNNotificationInterruptionLevel.

Never use the Time Sensitive interruption level to send a marketing notification. People may have agreed to receive marketing notifications from your app, but such a notification should never break through a Focus or scheduled delivery setting.

Designing a Great Notification Experience

Aim to provide rich, high-value information that people can understand at a glance.

Create a short title if it provides context for the notification content. The system displays your title at the top of a notification where it’s most visible. If you don’t provide a title for a noncommunication notification, the system displays your app name; in a communication notification, the system automatically displays the sender’s name in the title area. The prominence of the notification title area makes it a great place to provide useful information. For example, a noncommunication notification might display a headline, event name, or email subject. If you can only provide a generic title, like New Document, it can be better to let the system display your app name instead.

Write succinct, easy-to-read notification content. Use complete sentences, sentence case, and proper punctuation, and don’t truncate your message — the system does this automatically when necessary. Avoid telling people to open your app, navigate to specific screens, tap specific buttons, or perform other tasks that are hard to remember after the notification disappears.

Don’t include sensitive, personal, or confidential information in a notification. You can’t predict what people will be doing when they receive a notification, so it’s essential to avoid including private information that could display on the device screen.

Avoid sending multiple notifications for the same thing, even if the user hasn’t responded. People attend to notifications at their convenience. If you send multiple notifications for the same thing, you fill up Notification Center, and people may turn off all notifications from your app.

Provide generically descriptive text to display when notification previews are hidden. In Settings, people can choose to hide notification previews for all apps. In this situation, the system shows only your app icon and the default title Notification. To give people sufficient context to know whether they want to view the full notification, write body text that succinctly describes the notification content without revealing too many details, like “Friend Request,” “New Comment,” “Reminder,” or “Shipment.” For developer guidance, see hiddenPreviewsBodyPlaceholder.

Don’t include your app name or icon. The system automatically displays a large version of your app icon at the leading edge of each notification; in a communication notification, the system displays the sender’s contact image — or avatar — badged with a small version of your icon.

Consider providing a sound to supplement your notifications. Sound can be a great way to distinguish your app’s notifications and get someone’s attention when they’re not looking at the screen. You can create a custom sound that coordinates with the style of your app or use a system-provided alert sound. If you use a custom sound, make sure it’s short, distinctive, and professionally produced. A notification sound can enhance the user experience, but don’t rely on it to communicate important information, because people may not hear it. Although people can also enable a vibration that accompanies alert sounds, you can’t enable such a vibration programmatically. For developer guidance, see UNNotificationSound.

Providing Notification Actions

A notification can present a customizable detail view that contains up to four buttons people use to perform actions without opening your app. For example, a Calendar event notification provides a Snooze button that postpones the event’s alarm for a few minutes.

People can open a detail view by using the touch and hold gesture to reveal the notification preview or, on an unlocked device, swiping down. For developer guidance, see Handling Notifications and Notification-Related Actions.

Provide beneficial actions that make sense in the context of your notification. Prefer actions that let people perform common, time-saving tasks that eliminate the need to open your app. For each button, use a short, title-case term or phrase that clearly describes the result of the action. Don’t include your app name or any extraneous information in the title, keep the text brief to avoid truncation, and take localization into account as you write the text.

Don’t provide a notification action that merely opens your app. When people tap a notification or its preview, they expect your app to open the relevant screen, so presenting an action button that does the same thing clutters the detail view and can be confusing.

Avoid providing destructive actions. If you must provide a destructive action, make sure people have enough context to avoid unintended consequences. Actions you identify as destructive appear in red.

Provide a simple, recognizable glyph for each notification action. A glyph reinforces an action’s meaning, helping people instantly understand what it does. The system displays your glyph on the trailing side of the action title. When you use SF Symbols, you can choose an existing symbol that represents your command or edit a related symbol to create a custom glyph.

For developer guidance, see the icon property of UNNotificationAction.

Badging

You can badge your app icon to indicate a count of unread notifications. For developer guidance, see applicationIconBadgeNumber.

Use a badge only to show people how many unread notifications they have. Don’t use a badge to convey other types of numeric information, such as weather-related data, dates and times, stock prices, or game scores.

Don’t use a badge to communicate important information. People can turn off badging for your app, so if you rely on badging to communicate important information, you run the risk of people missing it.

Keep badges up to date. Update your app’s badge as soon as people view the corresponding information. You don’t want people to think there’s new information available, only to find that they’ve already seen it. Note that reducing a badge’s count to zero removes all related notifications from Notification Center.

Sending Marketing Notifications

Don’t use notifications to send marketing or promotional content unless people explicitly agree to receive such information. When people want to learn about new features, content, or events related to your app, they can grant their permission to receive marketing notifications. For example, the users of a subscriptions app might appreciate getting an offer to become a subscriber, and the players of a game might want to receive a special offer related to a live event.

IMPORTANT Never designate a marketing notification as Time Sensitive. For guidance, see Helping People Manage Notifications.

Get people’s permission if you want to send them promotional or marketing notifications. Before you send these notifications to people, you must receive their explicit permission to do so. Create an alert, modal view, or other interface that describes the types of information you want to send and gives people a clear way to opt in or out.

Make sure people can manage their notification preferences within your app. In addition to requesting permission to send informational or marketing notifications, you must also provide an in-app settings screen that lets people change their choice. For guidance, see Settings.

A partial screenshot of an app’s notifications settings screen on iPhone. The settings are displayed in a grouped table view that contains two groups, each of which contains two rows. The group titled General shows the following two settings: New followers and achievements. Both items are turned on. The group titled Marketing shows the following two settings: Subscription offers and live events. Subscription offers is turned on and live events is turned off.