iOS critical alerts, interruption levels and sound
This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application…
This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application; Pushizo generates the payload, while the entitlement and permission remain on the app side.
1. Supported iOS fields
APNs equivalents of the POST /v1/notifications fields (and template/campaign content) (packages/providers/src/apns.ts buildApnsPayload):
| Pushizo field | APNs | Note |
|---|---|---|
headings, contents, subtitle | aps.alert.title, .body, .subtitle | Resolved to the recipient's language. |
ios_sound | aps.sound (string) | default if not given. A .caf/.aiff/.wav file name in the app bundle (≤ 30 s). |
ios_badge_type + ios_badge_count | aps.badge (SetTo) or hs.badge_inc (Increase, applied by the NSE) | None leaves the badge untouched. |
ios_category | aps.category | For action buttons (buttons), the SDK registers a UNNotificationCategory. |
thread_id | aps.thread-id | Grouping; falls back to android_group. |
ios_interruption_level | aps.interruption-level | passive, active, time-sensitive, critical (see §2). |
ios_relevance_score | aps.relevance-score | 0–1; iOS 15+ summary ordering. |
target_content_identifier | aps.target-content-id | Scene selection. |
ios_attachments, big_picture | hs.image → downloaded by the NSE | PushizoExtension for rich media. |
mutable_content | aps.mutable-content: 1 | Always sent as 1 on visible notifications (NSE: received event, media, badge increment). |
content_available | aps.content-available: 1, apns-push-type: background, priority 5 | Silent push; no alert/sound is sent. |
priority | apns-priority | 10 (default) immediate, 5 power-saving. |
ttl | apns-expiration | Seconds. |
collapse_id | apns-collapse-id | Up to 64 characters. |
data | Custom keys at the payload root | Keys other than aps and hs; read via event.notification.data. |
aps.sound is always written as a string; the { "critical": 1, "name": "…", "volume": … } dictionary is not generated (see §3).
2. Interruption level
| Value | Behavior | Requirement |
|---|---|---|
passive | No sound/vibration, does not wake the lock screen; added to the notification list. | — |
active (default) | Normal notification. | — |
time-sensitive | Breaks through Focus modes and the Scheduled Summary; plays sound. | Xcode → Signing & Capabilities → Time Sensitive Notifications capability (com.apple.developer.usernotifications.time-sensitive). Users can turn it off per app in Settings. |
critical | Plays sound even in silent mode and Do Not Disturb, and wakes the screen. | The Critical Alerts entitlement from Apple (com.apple.developer.usernotifications.critical-alerts) and the user having granted critical alert permission. |
Sending:
await hs.notifications.create({
target: { include_external_ids: ['user_42'] },
headings: { tr: 'Güvenlik uyarısı' },
contents: { tr: 'Hesabınıza yeni cihazdan giriş yapıldı' },
ios_interruption_level: 'time-sensitive',
ios_sound: 'alert.caf',
thread_id: 'security',
});Only send ios_interruption_level: 'critical' to apps that have the entitlement; without it, APNs does not reject the request, but the device shows the notification at the normal (active) level.
3. Critical alert setup and current behavior
Apple side
- Submit a critical alert entitlement request (it requires use cases such as health, security or public safety).
- After approval, add the Critical Alerts capability to the App ID; set
com.apple.developer.usernotifications.critical-alerts = truein the.entitlementsfile. - Add the
.criticalAlertoption to the permission prompt. The Pushizo iOS SDK'sPushizo.Notifications.requestPermissioncall requests[.alert, .badge, .sound](+.provisionalifprovisionalAuthorizationis on); it does not request.criticalAlert. Your app must therefore request critical alert permission separately:
import UserNotifications
func requestCriticalAlerts() {
UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound, .criticalAlert]) { granted, _ in
// The user manages critical alert permission with a separate switch (Settings → Notifications → app → Critical Alerts)
}
}This call does not conflict with the Pushizo SDK's permission tracking: the SDK reads the effective permission through UNUserNotificationCenter.getNotificationSettings and updates the subscription's push_capable value; addPermissionObserver reports the change.
Pushizo side (current behavior)
ios_interruption_level: "critical"→aps.interruption-level: "critical"is written.ios_sound→aps.sound: "<file>"(string). Theaps.sound = { "critical": 1, "name": "…", "volume": 0.0–1.0 }dictionary Apple defines for critical alerts, and therefore volume override, is not supported; the sound plays at the device's volume setting. When these fields are added,MessageContent(packages/db/src/schema/delivery.ts) and the OpenAPI contract will be extended without changing existing fields (additions are non-breaking).- The Notification Service Extension (
PushizoExtension) preserves theapscontent withmutableCopy; theinterruption-levelandsoundvalues pass through the NSE unchanged. The NSE cannot raise a notification to the critical level (that is only possible with the payload + entitlement). - Critical and time-sensitive levels are not automatically exempt from quiet hours and frequency caps; for transactional/critical messages, send the
quiet_hours_exempt: trueandfrequency_cap_exempt: truefields together.
4. Sound
ios_sound: a custom sound in the app bundle (alert.caf);defaultis the system sound. If the file is not found, iOS plays the default sound.- Silent push (
content_available: true) sends no sound. - On Android, the equivalent is
android_sound(res/raw/<name>), or the channel sound (android_channel_id) under Dashboard → Settings → Android notification categories. On Android 8+, the channel determines the sound; a per-message sound applies only when there is no channel. - On Web, sound is a browser/operating system setting; there is no message field.
5. Verification
- On a test device (a real device; the simulator has no APNs), run the app with the
sandboxenvironment and confirm the environment matches in Dashboard → Channels → iOS Push (BadDeviceTokenindicates an environment mismatch). - Put the device in Do Not Disturb; a
time-sensitivemessage should come through, while anactivemessage should stay in the summary. - In an app with the critical alert entitlement, silence the device and send
ios_interruption_level: "critical"; the sound should play. Without the entitlement, the notification arrives at the normal level, which is expected behavior. - In Message Tracking, check the
sent → received → openedtimeline; thereceivedevent is recorded by the NSE (ifPushizoExtensionhas not been added, onlyopenedappears).
iOS Safari (16.4+) web push and PWA
On iOS 16.4 and later, Safari can send notifications to web apps added to the Home Screen (PWAs) using standard Web Push. The Pushizo Web SDK supports this flow without extra code; the difference is that the user must first add the site to the Home…
iOS Live Activities
Live Activities show live content on the lock screen and in the Dynamic Island: order tracking, delivery time, match scores, journey status. With Pushizo, you start, update and end activities from the server…