Notifications & Events
Notification behavior, timing and events for iOS 3.x.
One current request
Call Stay22.notifications.ensure(request) when the trip is ready. Repeating the same request keeps its receipt; a different ensure returns different_input while the existing request is current. Keep the receipt's reference for Stay22.notifications.replace and Stay22.notifications.cancel. Swift uses replace(reference, with: request).
After a restart or uncertain response, read await Stay22.notifications.current() on the main actor. It returns stored receipts and native observations without changing scheduling or reporting state. Use the current reference rather than guessing an ID or revision. clearTravelContext() is deprecated; cancel the receipt instead.
Choose when the notification is sent
| Timing | Request |
|---|---|
.accountDefault | Use the delay configured for your account, counted from submission |
.after(delayMs:) | Run no earlier than this delay after the first submission |
.notBefore(atMs:) | Run no earlier than this UTC instant |
.at(atMs:) | Schedule for this UTC instant, or reject with missed_target when it is missed |
Times and deadlines are UTC milliseconds since the Unix epoch. A repeated request or app restart does not restart an after delay. The quick start includes a complete request with deadlines.
allowedWindows restricts scheduling to local hours in an IANA time zone such as Europe/Paris. Each period uses minutes from midnight, an exclusive end, and optional ISO weekdays (Monday = 1, Sunday = 7). Split overnight periods at midnight. Set requiredWindowGuarantee whenever you supply windows. iOS supports .targetSelection, which constrains the selected target; it rejects .prePostCheck and .visiblePresentation. Unsupported requirements return unsupported_guarantee.
The requested time must leave room before both execution and action deadlines. A missing deadline without a cached account policy returns expiry_required. Timing or allowed-hours conflicts return no_allowed_time; an excessive execution horizon returns unsupported_horizon, with the limit in capabilities.supportedHorizonMs. The operating system controls visible presentation, so none of these options guarantees the alert appears at an exact time.
Customize the notification
Run SDK calls on the main actor.
import Stay22SDK
Stay22.notificationConfig = NotificationConfig(
title: "Hotels in {destination}",
subtitle: "{checkin}-{checkout}",
message: "Find stays near {destination}.",
categoryId: "stay22_destinations",
threadId: "stay22"
)Title, subtitle and message support {destination}, {checkin} and {checkout} placeholders. Leave title and message unset to use account text or the built-in copy. Their default values are nil.
NotificationConfig also accepts badges, grouping, actions and local-file image attachments. Use local file URLs for attachments; the SDK does not download remote images for this field.
Events
import Stay22SDK
Stay22.advanced.setEventHandler { event in
print(event)
}Scheduling and delivery changes arrive on notificationChanged. Read receipt.requestStatus, receipt.reason, and receipt.execution?.reason to distinguish a rejected command from a later execution outcome. A tap arrives as notificationClicked. Keep a default branch if you switch on events: SDK updates can add event types.
Receipt evidence means the operating system accepted or posted a notification, or the SDK observed it. It does not prove a person saw the alert.
Available from SDK 3.0.1: when Stay22 enables prepared links for an eligible release, taps can open a booking link prepared during scheduling. notificationClicked still carries the saved Stay22 link, which can differ from the prepared link opened. The fallback is the saved Stay22 link. Use SDK 3.1.1 or later for prepared links; see prepared booking links.
Attribution
Initialize with the partner ID Stay22 issued you. Set Stay22.campaignId = "spring_push" to group this campaign's bookings. See Link Attribution when your app sends its own notifications.