RFC — Game pill, alarm and auto-start

Summary

A product declares a pill with a window, a deadline and a destination. The host draws it with a countdown on every surface, opens the destination on tap and, if asked, at the deadline. Scheduled notifications gain a Critical urgency that rings the device alarm.

Motivation

The Jollity game starts at a fixed instant. Polkadot Mobile brings a registered player there natively with a countdown pill, an alarm and a game that opens itself. A product has none of it: it draws only in its own surface, a notification cannot ring as an alarm, and nothing opens a product at an instant.

Approach

sequenceDiagram
    participant J as Jollity worker
    participant H as Host
    participant U as User
    J->>H: declare_pill(key, show_from, deadline, destination, title, open_at_deadline)
    J->>H: send_push_notification(Critical, scheduled_at = game start, deeplink)
    Note over H: show_from: pill + countdown on every surface, hidden while Jollity is foreground
    U->>H: tap
    H->>U: open destination
    Note over H: deadline: pill withdrawn
    alt open_at_deadline set, app in foreground, nothing blocking
        H->>U: auto-open destination, current tab kept
    else app in background, or flag not set
        H->>U: alarm rings
        U->>H: act on alarm
        H->>U: open deeplink
    end
    J->>H: withdraw_pill(key), cancel_push_notification(id)

Where the work lands:

Pill. A declaration with a key already in use replaces it. The pill carries no permission. A host that draws no pills answers Unsupported, and the alarm is the fallback.

Alarm. A Critical notification is delivered in one of three ways:

• The product holds Alarms: the host rings the device alarm at scheduled_at, and acting on it opens deeplink.
• The product does not hold Alarms: the host delivers it as Normal, and the response says so.
• The host has no alarm framework: it refuses the Alarms grant, so every Critical from that product is delivered as Normal.

Auto-start. open_at_deadline is an optional flag on the declaration. Without it the pill is only withdrawn at the deadline. With it the host also opens destination, with no prompt, when the app is in the foreground and nothing blocks; what counts as blocking is host policy, and on iOS only an active call does.