Android

Notifications & Events

Notification behavior, timing and events for Android 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. Kotlin uses replace(reference, request).

After a restart or uncertain response, read Stay22.notifications.current() from a coroutine. 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

TimingRequest
NotificationTiming.AccountDefaultUse the delay configured for your account, counted from submission
NotificationTiming.After(delayMs)Run no earlier than this delay after the first submission
NotificationTiming.NotBefore(atMs)Run no earlier than this UTC instant
NotificationTiming.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. Android supports TargetSelection and PrePostCheck, which also checks immediately before posting. It rejects 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

import com.stay22.sdk.NotificationConfig
import com.stay22.sdk.Stay22

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 null.

NotificationConfig also accepts badges, grouping, actions and local-file image attachments. Android renders one attachment as the expanded image. It requires a file:// URI; a content:// URI is ignored. launchImageName is a drawable resource name; relevanceScore has no Android effect.

Events

import com.stay22.sdk.Stay22

Stay22.advanced.setEventHandler { event ->
    android.util.Log.d("Stay22 integration", event.toString())
}

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.

On this page