Dokumentation — 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 saysnotify).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(thenotifyright is not approved for this commit),bad_request,timeout,missing;Notifications::refusalText($reason)in words.status(): Task?Subscription(idns_…,user,groups).unsubscribe(): Task bool.- Events:
subscribed(Subscription),refused(reason),unsubscribed,change(the newreason()). - 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).