# Notifications for mHub sites

How a site that runs in an mHub app tells the people who use it what is new:
a new film, an announcement, a broadcast that begins at eight tonight — with
a button that notes it, a reminder as it begins, and a tap that leads straight
into the stream.

This page is the guide. The reference of every call is in
[mhub-api.md](/mhub-api.md#windowmhubnotify).

- [What it is, in one minute](#what-it-is-in-one-minute)
- [Who may notify](#who-may-notify)
- [The quick way: a feed](#the-quick-way-a-feed)
- [The feed's format](#the-feeds-format)
- [What the person sees](#what-the-person-sees)
- [Now, not within the hour: the knock](#now-not-within-the-hour-the-knock)
- [Recipes](#recipes)
- [With Vuma](#with-vuma)
- [Without Vuma: the page calls](#without-vuma-the-page-calls)
- [What the person can switch off](#what-the-person-can-switch-off)
- [Limits](#limits)
- [Testing](#testing)
- [Questions](#questions)

---

## What it is, in one minute

1. You publish a small JSON file on your own site: **the feed**. It lists what
   you want to say — each entry a title, and optionally a line of text, a
   picture, an address on your site, and a time.
2. Your page hands the app the feed's address **once**
   (`mhub.notify({ watch })`; Vuma does it for you).
3. From then on **the person's device reads the feed itself** — about once an
   hour, also while the app is closed — and shows what is new as a
   notification that names your site.
4. For something that cannot wait an hour you ask for a **knock**: the devices
   read the feed at once.

There is no account to create, no key, no list of subscribers and no server of
yours to run. What you say goes from your file to the device and through
nobody else.

## Who may notify

Only an mHub site: a page that declares itself one.

```html
<meta name="mhub" content="app">
```

Such a site needs **no permission question**. The first time it speaks it has
an entry in the app's settings (Settings → MediaHub → Notifications), and the
person can switch it off there at any time — this site alone, or all sites.

A plain website cannot notify through the app at all. `mhub.notify` answers
`permission: "denied"` to `{ state: true }` and refuses everything else with
`code: "permission_denied"`.

Notifications exist on **Android phones and tablets** today. Check the
capability and the features before you offer anything:

```js
const can = window.mhub?.capabilities?.includes("notify");
const state = can ? await mhub.notify({ state: true }) : null;
// state.features: ["kinds","set","actions","chat","progress","silent","at","inbox","watch","settings"]
// An app from before these calls answers { shown: false } without `features`.
```

## The quick way: a feed

You do not have to write the file by hand: [the notices tool](/notices.html)
builds it from a form, and knocks for you.

Put a file on your site, for example `https://vuma.mx/notices.json`:

```json
{
  "title": "Vuma",
  "items": [
    {
      "id": "2026-12-02-frankfurt-dortmund",
      "title": "Eintracht Frankfurt – Borussia Dortmund",
      "text": "DFB-Pokal, round of 16 · live on Das Erste",
      "image": "https://vuma.mx/img/frankfurt-dortmund.jpg",
      "url": "https://vuma.mx/#/channel/das-erste",
      "start": "2026-12-02T20:15:00+01:00",
      "end": "2026-12-02T23:30:00+01:00"
    },
    {
      "id": "news-2026-11-19-ballz",
      "title": "Ballz: all six episodes are here",
      "text": "The comedy series, in the ZDF Mediathek from today",
      "kind": "news",
      "at": "2026-11-19T10:00:00+01:00"
    }
  ]
}
```

and hand its address to the app from your page, once:

```js
await mhub.notify({
  watch: {
    id: "site",                         // your name for this feed
    title: "Vuma",                      // shown with each notification
    url: "https://vuma.mx/notices.json",
    item: "https://vuma.mx/#/",         // where an entry without `url` leads
    everyHours: 1,                      // how often a device reads by itself
  },
});
```

That is all. **New entries go at the top.** To say something, add an entry and
upload the file; to stop saying it, remove the entry.

The first time a device reads the feed it only remembers what is there —
nothing rings for entries that were already in the file. Notifications begin
with the next entry you add.

## The feed's format

The file is JSON, served with any content type, readable without a sign-in
(the device sends no cookies). The list may stand at the top level or under
`items`, `results` or `data`. The first 60 entries are read.

| Field | | Notes |
|---|---|---|
| `id` | **required** | Yours, stable, unique in this feed. An entry is announced **once per id**: change the text of an entry and nobody is told again, give it a new id and everybody is. |
| `title` (or `name`) | **required** | Up to 120 characters. |
| `text` (or `description`) | | One line under the title. |
| `image` (or `poster`, `thumbnail`) | | An `https` picture. Shown as a cover at the left. |
| `url` | | Where a tap leads. **Must lie on your own site**; anything else is ignored and the tap opens the feed's `item` address. |
| `kind` | | `"news"`, `"release"` or `"live"`. Left out: `"release"`, or — with a `start` — an event. |
| `at` | | When you said it. An entry older than a day is remembered but never rung: you can fill a new feed with old entries without waking anyone. |
| `start` | | When it begins. Makes the entry an **event** (see below). |
| `end` | | When it is over. After that the entry is never rung. Without it an event counts as running for two hours. |
| `type` | | Free, for your own `item` pattern (`{type}`). |

Times are ISO strings with an offset (`"2026-11-21T20:00:00+01:00"`), or
seconds or milliseconds since 1970. Always write the offset: a time without
one is read in the device's zone.

The feed's own `title` is not used; the name shown is the `title` you gave
with the `watch`.

## What the person sees

Every notification carries your site's name in its head, beside the app's
(`VYPN · vuma.mx`).

What an entry becomes is decided by its times at the moment a device reads it:

| The entry | The notification |
|---|---|
| **begins later** (`start` in the future) | Title, the day and time in the person's own words, your text, and a button **"Vormerken"** (note it). Pressed, the device sets itself a reminder for the beginning — the app stays closed, nothing is sent anywhere — and the notification turns into a short receipt and leaves. |
| ↳ at the beginning | The reminder: title, your text, a button **"Watch now"**. A tap opens the entry's `url` on your site. |
| **begins now or runs** (`start` up to two minutes ahead, not yet over) | Said as something to watch now, with **"Watch now"**. This is the entry to publish when you want people in a stream at this moment. |
| **news** (`kind: "news"`, no `start`) | Title, text, picture; quiet — it stands in the shade without a sound. |
| **a new title** (anything else) | Title, your site's name, picture, and a button that saves it for your page (see [the inbox](#what-a-pressed-button-tells-your-page)). |
| **over**, or said more than a day ago | Nothing. |

With Vuma, what was noted is found again in the library, under "Saved": a
broadcast that was noted stands there with its picture, your text and when
it begins, until it has begun or is taken back; a title that was saved joins
the saved list. For that the entry's `url` has to be the title's own page
(`…/#/item/<addon>/<type>/<id>`) — an entry that opens anything else is
shown and opened, but there is no title to save.

More than three new titles from one reading become a single line
("5 new titles") that opens your site. Nothing is shown about a page that is
on screen right now.

## Now, not within the hour: the knock

A device reads a feed at its own pace — hourly at the most. For "the match
begins in ten minutes" ask this site to knock on the devices that watch your
feed:

```sh
curl -X POST https://www.mhub.mx/api/notify/knock \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://vuma.mx/notices.json"}'
```

```js
await fetch("https://www.mhub.mx/api/notify/knock", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://vuma.mx/notices.json" }),
});
```

The answer:

| | |
|---|---|
| `{ "knocked": true, "topic": "w-…" }` | Sent. Each device reads the feed within seconds. |
| `{ "knocked": false, "reason": "unchanged" }` | The feed's newest entries are what they were at the last knock. Upload first, then knock. |
| `{ "knocked": false, "reason": "rate_limited", "retryAfter": 240 }` | Too soon (HTTP 429, with `Retry-After`). |
| `"invalid_url"` | Not an `https` address of a public host (HTTP 400). |
| `"unreachable"`, `"not_a_feed"` | The file could not be read, or has no entries with an `id`. |
| `"push_unavailable"`, `"failed"` | Not this time; the devices still read at their own pace. |

**Use exactly the address you gave in `watch.url`** — the knock is addressed
by it, character for character.

Why this needs no key: a knock carries no content and can only make a device
read a public file it already watches. It is therefore limited, not guarded:
it goes out only when the feed really changed, at most every five minutes and
24 times a day per feed. A device reads a knocked feed at most every two
minutes.

The order is always: **change the file, upload it, knock.**

## Recipes

### Bring people into a stream that starts tonight

In the morning, add the entry with its `start`, upload, knock:

```json
{ "id": "f1-2026-11-22", "title": "Formula 1: Las Vegas", "text": "The race, live",
  "url": "https://vuma.mx/#/channel/sport-1", "start": "2026-11-22T05:00:00+01:00",
  "end": "2026-11-22T07:00:00+01:00" }
```

Everyone sees the announcement with "Vormerken". Whoever presses it is
reminded as the race begins — you do nothing more. Whoever did not press it
gets nothing further for this id.

### "It is on now"

Add an entry whose `start` is now (or leave `start` out and set
`"kind": "live"` with an `end`), upload, knock. It arrives as "Watch now".
Give it a new `id`: an id that was already announced is not announced again.

### A new release

```json
{ "id": "tt-123456", "title": "The Long Night", "text": "New: season 2",
  "image": "https://vuma.mx/covers/tt-123456.jpg",
  "url": "https://vuma.mx/#/item/addon/series/tt-123456" }
```

### New titles from an addon's catalog

A feed does not have to be written by hand. Any public JSON list with ids
works — for example the first page of an addon catalog, newest first. Hand
it over as a second watch, with your site's address pattern for an item:

```js
await mhub.notify({
  watch: {
    id: "dw-new",
    title: "DW · New",
    url: "https://addon.example/catalog/movie/new.json",
    item: "https://vuma.mx/#/item/{type}/{id}",
    everyHours: 6,
  },
});
```

The device reads the catalog, and each new id becomes a "new title"
notification that opens `item` with the entry's `id` and `type` put in. A
site may have 24 watches.

### New episodes of the series someone watches

A watch may stand on a series' own page at its addon
(`…/item/series/<id>.json`: an item with numbered `children`, or `catalogs`
per season). The device reads it as the series' episodes: each new one is
announced under the series' name ("The Show — S2 · E5 – The Long Night"),
and an episode whose release day has not come is announced on its day.

```js
if (state.features.includes("episodes")) {
  await mhub.notify({
    watch: {
      id: "series:tt-123456",
      title: "The Show",
      url: "https://addon.example/item/series/tt-123456.json",
      item: "https://vuma.mx/#/item/addon/series/tt-123456",
      everyHours: 6,
    },
  });
}
```

Vuma does this by itself for the twelve series a person watched last. All of
it happens on the device: no server learns who watches what.

### Take something back

Remove the entry and upload. A reminder a person already set stays set; to
make an event silent for everyone, keep the entry and move its `end` into the
past before it starts — a device that reads it then drops it.

## With Vuma

Vuma does the page's part. Name the feed when you mount it:

```js
mount({
  // …
  notices: {
    feed: "https://vuma.mx/notices.json",
    title: "Vuma",        // optional, default: your brand's name
    everyHours: 1,        // optional
  },
});
```

Vuma hands the feed to the app, and its settings get a group
"Notifications" with a switch for each of the three things a site can ring
for — new films and episodes, live and announcements, what the person noted —
and the list of noted entries, to be taken back. Whether your site may notify
at all is the app's switch.

Your page must carry `<meta name="mhub" content="app">`; Vuma's own page
does.

## Without Vuma: the page calls

Everything above is `mhub.notify(object)`; it resolves to an object and
rejects with `code: "permission_denied"` where the site may not. The full
list is in the [reference](/mhub-api.md#windowmhubnotify); the ones a page
of its own needs:

```js
// What may I do here?
const s = await mhub.notify({ state: true });
// { permission: "granted" | "denied", os: true | false | null,
//   kinds: { message, news, release, reminder }, features: [...] }

// Android's own question (13 and later asks once per app), while your page is in front:
await mhub.notify({ ask: true });

// Show something now (nothing is shown while your page is on screen):
await mhub.notify({
  title: "The Long Night", body: "New: season 2",
  kind: "release",                       // "news" | "release" | "reminder"; left out: a message
  image: "https://vuma.mx/covers/tt-123456.jpg", layout: "poster",
  url: "https://vuma.mx/#/item/addon/series/tt-123456", // must lie on your site
  tag: "release:tt-123456",              // the same tag replaces the earlier notification
  actions: [{ id: "save", title: "Save" }, { id: "watch", title: "Watch now", url: "https://vuma.mx/#/item/addon/series/tt-123456" }],
  data: { item: "tt-123456" },
});

// A reminder for later — this is "Vormerken" on your own page:
await mhub.notify({
  tag: "remind:f1-2026-11-22",
  at: Date.parse("2026-11-22T05:00:00+01:00"),
  kind: "reminder",
  title: "Formula 1: Las Vegas", body: "The race, live",
  url: "https://vuma.mx/#/channel/sport-1",
  actions: [{ id: "watch", title: "Watch now", url: "https://vuma.mx/#/channel/sport-1" }],
});
const { scheduled } = await mhub.notify({ scheduled: true }); // [{ tag, at, title }]
await mhub.notify({ cancel: "remind:f1-2026-11-22" });
```

### What a pressed button tells your page

A button **with** a `url` opens the app on that address. A button
**without** one keeps the app closed and is put into your site's inbox; read
it when your page next runs:

```js
const { inbox } = await mhub.notify({ inbox: true });
// [{ action: "save", tag, data, at }]  — handed out once; `action` is the button's id
```

### Switching kinds from your own settings

```js
await mhub.notify({ set: { kinds: { news: false } } });   // answers the new state
```

A kind you take away is off for your site; you can give it back. You cannot
give back what the person switched off in the app.

## What the person can switch off

| Where | What |
|---|---|
| The app: Settings → MediaHub → Notifications | all mHub sites at once; each site by itself |
| Your site's settings (Vuma) | each kind for your site; the entries noted for later |
| Android's settings for the app | the app's notifications as a whole; sites have no entry of their own there (they share "Messages") |

A site that is switched off shows nothing: not what its page asks for, not
what its feed brings, and what it had set for later is taken back.
`{ state: true }` then says `permission: "denied"`.

## Limits

| | |
|---|---|
| Watches per site | 24 |
| A device reads a watch | every hour at the most by itself (default every 6 hours; `everyHours` 1–168), plus knocks |
| Shown from one reading | 3 single notifications; more become one line |
| Shown per site per day from watches | 6 |
| Feed size | 512 KB, the first 60 entries |
| Feed address | `https`, a public host name, no sign-in |
| Reminders (`at`) per site | 30, at least 10 seconds and at most a year ahead |
| Buttons per notification | 3 |
| Knocks per feed | one per 5 minutes, 24 a day, and only when the feed changed |

A reminder arrives when it suits the device, usually within half a minute of
its moment; the app sets it a little early.

## Testing

1. Open your site in the app and call `mhub.notify({ state: true })` from the
   console of a debug build, or show the answer on a test page. `permission`
   must be `"granted"` and `features` must list `"watch"`.
2. Hand over the feed. The first reading only remembers.
3. Add an entry with a new `id` and a `start` three minutes ahead, upload,
   knock, and put the app in the background. The announcement appears with
   "Vormerken"; press it; at the start the reminder appears; "Watch now"
   opens your address.
4. Nothing came? Check, in this order: the app's notifications are on in
   Android; your site is on in Settings → MediaHub → Notifications; the
   entry's `id` is new; your page is not the one on screen; the knock
   answered `knocked: true`.

## Questions

**Do people have to sign in or subscribe?** No. Whoever opens your site in
the app has the feed handed over, and is told what is new until they switch
your site off.

**Can I see who gets my notifications?** No. Devices read a public file; no
list exists anywhere.

**Does the content pass through mhub.mx?** No. The knock carries nothing but
the word "read"; the text and pictures come from your file to the device.

**iPhone, television, desktop?** Not yet. The capability `"notify"` is listed
only where it works.

**Can I send to one person?** Not with a feed. Messages between people are
Social's; a reminder is set by the person's own device.
