PL

← Notification

Dokumentacja — Notification

Notifications (jumphp/notification)

Push notifications on the phone of the people who use your JumPHP application in the browser, through the JumPHP runtime for Android, with their consent. You send them from a script, a server, bin/jumphp notify or Claude (bin/jumphp notify:mcp). The contract (messages, server API, quotas): docs/notifications.md of JumPHP.

Three doors, all needed: the administrator of jumphp.net approves the notify right of your application (studio, "Network access", per commit, like tcp); you, the owner, hold the sending token jnt_… (studio, project → Notifications); the person says yes in the runtime's own window on their phone, and can take it back there at any time.

In the application (browser)

use JumphpExtensions\Notification\Notifications;

final class SettingsScene extends Form
{
    public function __construct(private Notifications $notifications) {}      // a service of the extension

    public function onNotifyClick(): void
    {
        if (!$this->notifications->supported()) {
            $this->info->text = $this->notifications->reasonText();         // why not, in the person's language
            return;
        }
        $this->notifications->subscribe('player-42', ['beta'])              // your id for this person, your groups
            ->then(fn (bool $ok) => $this->info->text = $ok ? 'On' : Notifications::refusalText($this->notifications->lastRefusal()));
    }
}
  • supported(): a browser, and the JumPHP runtime for Android answers (its hello says notify). reason() otherwise: browser (not in a browser: desktop, tests), checking, missing (no runtime: install it), blocked (the browser forbids 127.0.0.1), runtime (the desktop runtime: it does not show notifications). reasonText(): the same in words.
  • subscribe(?string $user, array $groups): Task bool. User ≤ 128 characters, ≤ 32 groups of ≤ 64. One dialog at a time. A refusal: lastRefusal() = denied (the person said no, or did within 10 minutes), later (no answer in 30 s, another dialog open, the runtime paused or rate limited), server (network, server), ticket (the notify right is not approved for this commit), bad_request, timeout, missing; Notifications::refusalText($reason) in words.
  • status(): Task ?Subscription (id ns_…, user, groups). unsubscribe(): Task bool.
  • Events: subscribed (Subscription), refused (reason), unsubscribed, change (the new reason()).
  • Without a container at hand: Notifications::of($engine).

The widget: one line does it all

- {class: JumphpExtensions\Notification\NotifyToggle, id: notify, user: player-42, groups: [beta], events: {change: onNotifyChange}}

"Receive notifications", ticked when subscribed; a click subscribes or unsubscribes; no runtime on the phone: a click opens the install guide (RuntimeGuide); not possible here: greyed with the reason. It asks once whether the person is already subscribed. Props: text, user, groups. Events: change (bool), refused (reason), guide, click. Texts in 14 languages (your lang.yaml wins).

Sending (the owner: scripts, servers, Claude)

The token is a secret: never in a game or a repository. Sender is for your scripts, your server, your desktop tools.

use JumphpExtensions\Notification\Sender;

$sender = new Sender(getenv('JUMPHP_NOTIFY_TOKEN'));                        // curl: each call waits for its answer
$sender->send(Sender::toUsers('player-42'), 'Your turn', 'Ada played', url: '/play/?room=ABCD', tag: 'turn')->result();
$sender->dryRun(Sender::everyone())->result()['targets'];                   // how many, nothing sent
$sender->stats('2026-11-01')->result();  $sender->history(20)->result();
$sender->subscribers(group: 'beta')->result();  $sender->groups()->result();  $sender->setGroups('player-42', ['vip']);
// in an engine program: new Sender($token, http: $this->engine->http()) never blocks the frame

Every call is a Task (then(), result()): the server's JSON, or a SendError (errorCode, status, retryAfter on a 429). Bounds are checked before any request: title ≤ 65, body ≤ 240, ttl ≤ 604800 s, data ≤ 2 KB of JSON, url a path of the application or https. Requests carry the token and the User-Agent jumphp-notify, nothing else about you. JUMPHP_NOTIFY_URL changes the server.

From the terminal and from Claude

bin/jumphp notify:login my-game                       # the token, asked without echo, kept in ~/.jumphp/notify/tokens.json (0600)
bin/jumphp notify my-game --group beta "Season 2" "New levels are out" --url /play/ [--dry-run]
bin/jumphp notify:stats my-game ; bin/jumphp notify:history my-game ; bin/jumphp notify:logout my-game
claude mcp add jumphp-notify -- bin/jumphp notify:mcp # tools notify_send (to.all needs confirm: true), notify_dry_run, notify_stats,
                                                      # notify_history, notify_subscribers, notify_groups, notify_set_groups

JUMPHP_NOTIFY_TOKEN / JUMPHP_NOTIFY_URL win over the saved token (CI, a server).

Testing your application

PhoneSimulator plays the runtime for Android (no phone, no browser): (new PhoneSimulator())->attach($notifications), then $phone->answer = 'denied' (granted | denied | later | server | ticket | silent). FakeTransport plays the server for Sender (queue(200, [...]), requests, lastJson()).

project.yaml

Nothing of its own. The ticket is asked where TCP tickets are (tcp_ticket_url, JUMPHP_TCP_URL); the runtime is the engine's ($engine->runtime()).

Samples (doc/samples/)

  • SupportSample: supported() and reason() for each state of the runtime.
  • SubscribeSample: subscribe(), status(), unsubscribe(), the events; the person says yes or no.
  • ToggleSample: the NotifyToggle widget in a settings form.
  • SenderSample: Sender's send(), dryRun(), stats() and a quota error (a pretend server).

Notification Samouczek