Plugins
Sending notifications
Notify Fliks users from a plugin with the notify:users scope, the audiences, the notification fields, translations and the rate limit.
A plugin can send a notification to users. It reaches each user on every device where they turned notifications on: a message in the app, the browser, the desktop app and the phone (see Notifications). Core does the delivery, the encryption and the muting: the plugin names the audience and the text.
Requirements#
- The manifest scope
notify:users(see the manifest). An administrator sees it at install, like any scope. - A manifest
fliksrange that starts at the Fliks release that ships the function. A plugin built before it does not import it and runs unchanged; one that calls it fails to load on an older core. - Texts in the manifest
i18nblock, with an English entry for every key.
The call#
use fliks_plugin_sdk::notify::{self, Notification, NotifyAudience};
let note = Notification::new("acme.done.title", "acme.done.body")
.param("title", "Some Title")
.media(42);
notify::users(NotifyAudience::Viewers(42), ¬e)?;The raw WIT function is notify-users(audience, notification) in the notify interface.
Audience#
| Variant | Who |
|---|---|
Users(ids) |
The users with these ids, at most 500. An id that is not an enabled user is dropped |
Recipients(media_id) |
The requesters of the media, else the administrators: the audience of events_emit_own for a media |
Viewers(media_id) |
The viewers of the media |
There is no audience for everybody. Users and the media are independent: a media only supplies the
default page and poster, and no library access is checked for the recipients.
Notification fields#
| Field | Meaning |
|---|---|
title_key, body_key |
Keys of the manifest i18n. Required, and each must have an English entry, else ERR_VALIDATION |
params |
Up to 16 strings of at most 500 characters filling the {{name}} slots of the texts |
url |
An in-app path the notification opens: one leading /, no \, no encoded //. Anything else is ERR_VALIDATION |
image |
A path under /api/images/ |
media_id |
Gives the media's page as url and its poster as image when you set neither. Unknown media is ERR_NOT_FOUND. With neither, the notification opens / |
The notification has one Open action, lives one day, and sits in the category plugin.<id>, which
each user can mute from the notification settings; the muted users are skipped.
Translations#
Each device gets the text in its own language. Define the keys in the manifest and use {{name}}
for the params:
"i18n": {
"en": { "acme.done.title": "Import finished", "acme.done.body": "{{title}} is ready" },
"fr": { "acme.done.title": "Import terminé", "acme.done.body": "{{title}} est prêt" }
}Fliks matches the base language of the device (en, fr, de, es, it, pt) and falls back to
English. The usual i18n rules apply to the keys.
Limits and errors#
- 10 notifications per hour per plugin, whatever the audience size. The eleventh fails with
ERR_RATE_LIMITEDuntil the window slides. A call refused for validation, or one whose audience holds nobody who can receive it, is not counted and succeeds. - The relay limits for phones still apply to the delivery (see Push notifications), with no feedback to the plugin: delivery is best effort, with no retry and no inbox.
- Other errors:
ERR_DENIEDwithout the scope,ERR_VALIDATIONfor a bad key,urlorimage,ERR_NOT_FOUNDfor an unknown media.
Send what matters and group what comes in bursts: a notification per file of a 200 file import is the way to exhaust the limit and annoy your users.