The settings form (apiVersion 6)¶
The usual settings hold values your code reads with kino.config. From
"apiVersion": 6 (Kino 0.9.50) the form can also show and do things, and every installed plugin
gets its own tab in Ajustes. This page has every field type, the three types without
a value, the two configuration aids of apiVersion 12, the exports that fill and check them, and
a complete example.
For a new UI, use screens
From apiVersion 14 (Kino 0.9.74) the preferred way to build your plugin's configuration, onboarding
or a dashboard is screens, which can also show this very form with the
settings node. This form keeps working for compatibility.
Its own tab in Ajustes¶
Every installed plugin that is enabled gets its own tab in Ajustes (phone and TV), named after the
plugin, with its Modo debug switch; when it has settings the tab holds their
form too, and Plugins ▸ Configurar opens the same form. That is why, from Kino 0.9.50,
the auth_required error reads "Configura {plugin} en Ajustes ▸ {plugin}" when your plugin declares
settings.
Every field type¶
The form shows your settings in the order of the manifest, each with its label and, under it, its
hint. Eleven types, and a twelfth, qr, from apiVersion 13 (Kino 0.9.74):
type |
What the person sees | What kino.config.get(key) returns |
Since |
|---|---|---|---|
text |
a text field (at most 500 characters) | the text, or undefined |
apiVersion 1 |
password |
a hidden text field (at most 500), kept encrypted on the device | the text, or undefined |
apiVersion 1 |
url |
an address field (at most 2,048): http/https; that server becomes a host your plugin may reach (The person's own servers) |
the address as typed, or undefined |
apiVersion 1 |
toggle |
a switch | true / false (false when there is no default) |
apiVersion 1 |
select |
a choice among options |
the chosen value (the first option when there is no default) |
apiVersion 1 |
list |
a list the person builds with "Agregar", each entry a dialog of the list's fields |
an array of { [field key]: string }, or undefined when empty |
apiVersion 4 |
section |
a heading, with hint as its explanation |
nothing | apiVersion 6 |
status |
a read-only line your settingsStatus() fills |
nothing | apiVersion 6 |
action |
a button that runs your action(key) |
nothing | apiVersion 6 |
link |
a button that opens an https address through the system, only when the person taps it (Configuration aids) |
nothing | apiVersion 12 |
help |
a button ("Ayuda") that opens your instructions in a modal (Configuration aids) | nothing | apiVersion 12 |
qr |
a QR code drawn on the device from a text your settingsStatus() returns (A QR code) |
nothing | apiVersion 13 (Kino 0.9.74) |
What each entry may carry:
| Attribute | Types | Rule |
|---|---|---|
key |
all | required, ^[a-z][a-zA-Z0-9_]{0,31}$, unique in the list |
label |
all | required, 1 to 40 characters (optional on a help: without it the button says "Ayuda") |
type |
all | required, one of the eleven above |
hint |
all | optional, at most 80 characters: the example or explanation under the field. On a section, up to 300, wrapped over several lines (Kino 0.9.51; builds before 0.9.51 refuse one over 80) |
required |
text, password, url, list |
optional true/false. A required setting with no value stops every call ("Falta configurar") |
default |
text, password, toggle, select |
optional. Never on url or list ("… no puede tener valor por defecto: usa "hint"") nor on the types without a value; it must fit its type (a select default is one of its values) |
options |
select only |
required: 1 to 20 { "value", "label" }, value 1..40 characters and unique, label 1..40 |
fields |
list only |
required: 1 to 4, each { key, label, type, hint?, required? } with type "text" or "url", no default ("Solo un ajuste de tipo list tiene "fields"") |
max |
list only |
optional whole number 1..50 (default 20): how many entries |
confirm |
action only, apiVersion 6 |
optional, 1 to 120 characters: asked before the action runs, with Cancelar focused ("Solo un ajuste de tipo action tiene "confirm"") |
url |
link only, apiVersion 12 |
required: https://, no user name or password, at most 2,048 characters |
title, titleEn, body, bodyEn |
help only, apiVersion 12 |
the modal's title (at most 60) and text (at most 2,000); body or bodyEn is required |
labelEn, hintEn, confirmEn |
those of label, hint, confirm |
optional, apiVersion 9 (Kino 0.9.55): the same text in English, with the same limits (English texts) |
devices |
all | optional, apiVersion 12: ["phone"], ["tv"] or both, the devices that draw it (one kind of device) |
linkOnly |
action |
optional true/false, apiVersion 12: never drawn, run only as a link's confirm (linkOnly) |
sync |
password, text |
optional true/false, apiVersion 13 (Kino 0.9.74): false keeps the value on this device (sync: false) |
Any other key in an entry is ignored. A manifest that breaks a rule is refused at install with a
message that names the setting (El ajuste "quality" necesita opciones); a list below apiVersion 4
a section/status/action below apiVersion 6 or a link/help below apiVersion 12 is refused too.
Limits: 12 settings with a value (text, password, url, toggle, select, list) plus, from
apiVersion 6, 16 without one (among them, from apiVersion 12, at most 4 link and 4 help).
There are no conditional fields: every setting is always shown, whatever another one holds. Use a
section with a hint to say which fields go together ("Opcional: sin cuenta ves el catálogo gratis"),
make them optional, and let validateSettings refuse a combination that makes no sense.
password or sealed secrets? A password setting is the person's credential: they type it,
your code reads it, it syncs to their other devices sealed end to end. A key that belongs to you, the
author (a fixed API key of the site's own player), goes in the manifest's sealed
secrets instead, and your code only ever holds a marker.
English texts (apiVersion 9, Kino 0.9.55)¶
Kino speaks Spanish or English since 0.9.54 (Ajustes ▸ App ▸ Idioma). From Kino 0.9.55, with "apiVersion": 9, each
text of your form can carry its English version next to it, under the same key with En at the end:
| Where | English keys | Limit |
|---|---|---|
| any setting | labelEn, hintEn |
those of label (1 to 40) and hint (80; 300 on a section) |
an action with confirm |
confirmEn |
1 to 120, and only next to confirm |
a select's option |
labelEn |
1 to 40 |
a list field |
labelEn, hintEn |
1 to 40 and 80 |
the manifest's section |
labelEn |
1 to 20 (The manifest) |
{ "key": "quality", "label": "Calidad", "labelEn": "Quality", "type": "select",
"hint": "La más alta gasta más datos", "hintEn": "The highest uses more data",
"options": [{ "value": "hd", "label": "Alta", "labelEn": "High" }, { "value": "sd", "label": "Normal" }] }
- The usual text is the Spanish one and the fallback: with the app in English, Kino shows every English version there is and, where one is missing, the usual text (above, the "Normal" option reads the same in both languages). With the app in Spanish nothing changes.
- Your code never notices: keys, types, values and
defaults are the same in both languages, andkino.configreturns the same. To know the language, readkino.lang. - From apiVersion 9: below 9 these keys are unknown and ignored without being checked, as on an older Kino (which
does not take
"apiVersion": 9either). - The same rules as the usual text: an empty one, one over the limit or one that is not a text refuses the manifest
at install ("\"labelEn\" del ajuste \"quality\" debe ser un texto de 1 a 40 caracteres"; on an option, "Una opción
del ajuste \"quality\" no es válida");
nullis the same as leaving it out.confirmEnonly goes on anaction("Solo un ajuste de tipo action tiene \"confirmEn\"") and next toconfirm("…necesita también \"confirm\""). - Kino only speaks Spanish and English: any other language key (
labelPt,labelFr) is an unknown key and ignored.
node sdk/validate.mjs checks the same limits and, once your plugin uses an English version, tells you how many texts
have one and which do not.
Three types that hold no value¶
From apiVersion 6 there are three types that hold no value (never in kino.config, never required,
no default), at most 16 of them on top of the 12 valued settings:
"settings": [
{ "key": "account", "label": "Tu cuenta", "type": "section", "hint": "Opcional: sin cuenta usas la sesión anónima" },
{ "key": "email", "label": "Correo", "type": "text" },
{ "key": "password", "label": "Contraseña", "type": "password" },
{ "key": "linked", "label": "Estado", "type": "status" },
{ "key": "logout", "label": "Cerrar sesión", "type": "action", "confirm": "¿Cerrar la sesión de esta cuenta?" }
]
section: a heading;hintis its explanation.status: a read-only line. Kino calls yoursettingsStatus()when the form opens (10 s) and shows the text you return under that key:{ linked: "Vinculada como ana@…" }(at most 200 characters). Until it answers the line reads "Cargando…"; a missing key or a value that is not a text shows "Sin información"; a timeout or an error shows "No se pudo consultar". The rest of the form keeps working either way. Required export when astatussetting exists.action: a button. Kino calls youraction(key)(30 s), one action at a time (the other buttons and Guardar wait), and shows themessageyou return (at most 300 characters) or "Listo"; if it throws or times out, the person sees the error text instead. Kino askssettingsStatus()again after every action (and when the form opens), so the status lines describe what it just did;refresh: trueis still accepted and changes nothing.confirm(1 to 120 characters) asks first, with Cancelar focused. Required export when anactionsetting exists.
A QR code: qr (apiVersion 13, Kino 0.9.74)¶
A fourth type that holds no value, counted among the 16: a QR code drawn on the form, on the device (nothing goes to a network to draw it). It is how a TV shows a login code for a phone to scan.
{ "key": "login", "label": "Escanéalo desde tu teléfono", "labelEn": "Scan it from your phone", "type": "qr", "refreshMs": 5000 }
- Its text is what your
settingsStatus()returns under that key, like astatusline, but kept whole: 1 to 512 characters with no control character; anhttp/httpsaddress only https on a public host (never the home network); any other text (an app link such asexampleapp://login?token=…, a pairing code) is drawn as it is. A longer text, a non-text or one that holds one of your sealed secrets draws no QR, and aqrwith no text draws nothing at all (no label, no placeholder line, no empty row), so a QR that only one step of a sign-in needs simply is not there in the others. refreshMs(2000 to 60000; only aqrsetting has it): Kino askssettingsStatus()when the form opens, after every action and every that many ms while the form is on screen and the app in front. A refresh never starts while the previous call is still running, and the QR on screen stays up until the new text replaces it. That is how a code that expires every 30 s stays scannable, and how a status line next to it turns into "Listo" once the code was used.- Required export:
settingsStatus. Showing a QR needs no capability; scanning one (kino.qr.scan) needsqrScan. The whole two-device recipe: QR codes.
Hiding items while they are not needed (hide, apiVersion 13, Kino 0.9.74)¶
Your settingsStatus() answer may carry hide: a list of keys of your own settings that the form (phone and TV) does
not draw while that answer is current. Use it for a form that changes with a step: the sign-in button, its QR and the
password step once the person is signed in, or "Cerrar sesión" while signed out.
export async function settingsStatus() {
if (signedIn()) return { status: "Conectado", hide: ["qr_login", "login_qr", "tg_password", "check_password"] };
return { status: "Falta iniciar sesión", hide: ["logout"] };
}
- Their stored values stay and nothing is deleted; they still count for the form's own rules (a
requiredone you hide still blocks Guardar). - Unknown keys and non-strings are ignored, at most 32 entries are read, and a failed answer hides nothing.
- Kino asks
settingsStatus()again after every action, so the form follows the step the action just reached. - Below apiVersion 13 the key is ignored.
sdk/contract.mjsexportsstatusHide(answer, manifest), which gives the keys the app would hide.
Configuration aids: link and help (apiVersion 12, Kino 0.9.74)¶
Two setting types help the person configure your plugin. Neither holds a value (never in
kino.config, never required, no default), and both count among the 16 settings without a value.
"settings": [
{ "key": "steps", "type": "help", "title": "Qué necesitas", "titleEn": "What you need",
"body": "1. Crea un bot con @BotFather y copia su token.\n2. Pégalo aquí y toca Guardar.",
"bodyEn": "1. Create a bot with @BotFather and copy its token.\n2. Paste it here and tap Save." },
{ "key": "botfather", "type": "link", "label": "Abrir @BotFather", "labelEn": "Open @BotFather", "url": "https://t.me/BotFather" },
{ "key": "botToken", "label": "Token del bot", "type": "password" }
]
link: a button that opensurlthrough the system only when the person taps it (on a phone,https://t.me/...opens the Telegram app when it is installed). Kino shows its own "Abrir enlace" and the host under the button, makes no request to that host, and does not count it as a network access of your plugin. On a TV (usually without a browser) the tap shows the address as text and as a QR to open on a phone.urlmust behttps://, without a user name or password, at most 2,048 characters;labelis required. An address that holds one of your stored secrets is not shown. Kino opens the canonical form of the address (host in lower case), the same one it names. There is no other way for a plugin to have Kino open an address.help: a small button ("Ayuda" / "Help", or your ownlabel) that opens a modal with your instructions, titled with your plugin's name. Plain text only: newlines are kept, markup is shown literally, nothing in it is tappable (use alinkfor an address).titleat most 60 characters,bodyat most 2,000 (bodyorbodyEnis required); a missing Spanish or English text falls back to the other; everything is scrubbed of your secrets. On a TV it scrolls with the remote, focus starts on Cerrar and Back closes it.
A link's label and a help's label, title and body may not hold control characters (a body keeps its
line breaks), invisible formatting or direction overrides; the manifest is refused otherwise. At most 4
links and 4 helps per plugin. Older Kino builds refuse apiVersion 12, so a plugin that uses them
declares "apiVersion": 12.
Keep the help short and practical: what the plugin needs and where to get it, in a few lines. If
the plugin talks to a server the person runs, the help does not teach how to build it: add a link to
the complete guide (the technical cap of 2,000 characters is not a target).
Settings for one kind of device (devices, apiVersion 12, Kino 0.9.74)¶
Any settings item (a field, a section, a status, an action, a link or a help) may say which devices
draw it: "devices": ["phone"], ["tv"] or both; without it the item shows everywhere.
{ "key": "botToken", "label": "Token del bot", "labelEn": "Bot token", "type": "password", "devices": ["phone"] }
It is only about drawing. On a device it leaves out, the form neither draws nor checks the item (a
hidden required field never blocks Guardar there), but its value is still stored, saved back
unchanged, synced to the person's other devices, handed over by sync.provision and read by your code
through kino.config. Use it for setup a TV cannot do well, like a token pasted on the phone: Sync-Gram
and Sync Servidor draw their setup only on the phone, and the TV receives the values with "Recibir
configuración" ("Receive settings"). An unknown device, an empty list or a repeated one refuses the manifest ("devices" of the
setting "<key>" must be a list of different devices: "phone", "tv"); below apiVersion 12 the key is
ignored. The Node kit renders no form: validate.mjs only checks the field.
A setting the 18+ code guards (unlockWith, apiVersion 14, Kino 0.9.74)¶
Available with Kino 0.9.74
Available from Kino 0.9.74. Below apiVersion 14 the key is ignored.
A toggle or a select may say "unlockWith": "adultCode": before the person moves it away from its
default (a toggle off its default, a select to any other option), Kino asks the device's 18+ code with its own
prompt (the «Código» field of Ajustes on the phone, the padlock's keyboard dialog on a TV; while the default code still
rules, the prompt says so, as every 18+ prompt does). The change applies only once the code is right; a wrong code says
«Código incorrecto» and keeps the old value, and Cancelar or Back leave the control as it was. Moving it back toward
the default never asks. Your plugin never sees the code, and giving it unlocks nothing else (no 18+ entry shows because
of it). Use it for a filter the person should not switch off on a whim, like the news example's «No mostrar noticias
+18» (default on).
{ "key": "hideAdult", "label": "No mostrar noticias +18", "labelEn": "Hide 18+ news", "type": "toggle", "default": true, "unlockWith": "adultCode" }
It works in Kino's settings form wherever it is drawn: your tab in Ajustes, and a screen's or a panel's
settings node. Your own code may only move the setting toward its default: an
answer's config that moves it away is dropped (is locked (unlockWith adultCode): only the person moves it away from
its default, in Kino's settings form), an action's setSettings that does is refused whole, and a field may not
bind it (bind "<key>" is locked (unlockWith adultCode): show it in a settings node): show it with
{ "type": "settings", "keys": ["<key>"] }. The value syncs to the person's other devices like any setting (and
travels with «Enviar a otro aparato»); the code is asked on each device at the moment of the change. unlockWith on any
other type, or a value other than "adultCode", refuses the manifest (Only a setting of type toggle or select has
"unlockWith" ("<key>"), "unlockWith" of the setting "<key>" must be one of: adultCode). The Node kit renders no
form: validate.mjs checks the field and run.mjs applies the same config, bind and setSettings rules.
Actions only a link runs (linkOnly, apiVersion 12, Kino 0.9.74)¶
An action may say "linkOnly": true: it is never drawn on any device and runs only as the confirm
of another action's link, after Kino's own question. A "find, then confirm" pair then shows
the person one button (Sync-Gram's Verificar mensaje en el chat); without it the confirm action is a
second button. linkOnly on anything but an action, or not a boolean, refuses the manifest.
Forgetting settings from an action (clearSettings)¶
An action may also forget settings of your own with clearSettings: up to 12 keys of your declared
valued settings (text, url, password, toggle, select, list). After the action returns, Kino
empties them exactly as if the person had emptied the fields and pressed Guardar (a password also
leaves the Keystore), closes your sandbox and forgets cookies and cached Home rows as for any saved
change (kino.storage survives), reloads the form and asks settingsStatus() again; your message is
still shown. It is how a "Cerrar sesión" button stops the next expired token from signing the person in
again with the saved account.
export async function action(key) {
if (key === "logout") {
await api.logout(); // tell the server first: a throw here keeps the saved account
return { message: "Sesión cerrada", clearSettings: ["email", "password"] };
}
}
(email and password must be optional settings here; mark the account required only if the plugin
cannot work signed out.)
Limits:
- Only the action's own plugin is ever touched.
- An entry that is not a string, is unknown, names a
section/status/action, names arequiredsetting (clearing it would make every later call fail), repeats, or comes after the twelfth is dropped with a log line (run.mjsshows[dropped by Kino]); a value that is not an array is ignored. - An action that throws or times out clears nothing.
Filling your own settings from an action (setSettings, Kino 0.9.74)¶
An action may also fill settings of your own with setSettings: up to 8 keys of your text or
select settings, each with a string value. It is how a "Vincular" action stores the chat it found, so
the person types nothing. Kino trims each value, checks it like a typed one (length, one of the
options) and saves the values through the form's own Guardar: they reach the person's other devices and
stay in the profile in use like typed values, and your sandbox closes as for any saved change. It is
additive (no new apiVersion): an older Kino ignores it.
return { message: "Vinculado", setSettings: { chatId: String(chat.id) } };
- Never a
url(its value becomes a server your plugin may reach, so only the person types one), atoggle, alistor a setting without a value; arequiredsetting is never emptied this way. Apasswordonly fromapiVersion13 (below); below it the whole field is refused. - Kino does not run your
validateSettingson these values (you chose them), and it refuses a value that contains one of your stored secrets instead of copying it into a plain, synced setting. - An unknown or secret key, a value that is not a string or fails its check, a key that is also in
clearSettings, a value that holds one of your stored secrets, or more than 8 keys refuse the whole field: nothing is applied, yourmessagestill shows and Kino adds its generic error under it. - It works from your settings form (any action, including the
confirmaction of a link).
Filling a password (apiVersion 13, Kino 0.9.74)¶
An action may fill one of your own password settings, for a value your plugin makes up instead of asking the person to type one:
return { message: "Clave creada", setSettings: { syncKey: kino.crypto.randomBytes(32) } }; // 64 hex characters
Kino stores it exactly like a typed password: sealed in the Keystore, synced sealed end to end to the person's other
devices (or kept on this device only when the setting says "sync": false), and masked in the form. It
is never logged, and every password value your answer names is scrubbed from that same answer's message and link,
so it is never shown back on the page. The usual rules apply (at most 500 characters, a required one never emptied, a
value holding another of your secrets refused). Only an action the person ran fills a setting: a settingsStatus answer
is never read for setSettings. node sdk/run.mjs . action <key> prints such a value masked. A sync provider that only
needs a random key does not need this: sync.generateKey makes Kino create it.
Linking: "Is this you?" (action.link, Kino 0.9.74)¶
Use it when an action finds who to link and the person must say it is them: for example a
sync provider whose bot reads the latest message ("write something to your bot")
and finds @ana. Your plugin never links on its own: it answers a candidate, and Kino asks.
export async function action(key) {
if (key === "findMe") {
const who = await bot.latestSender(); // null while nobody wrote yet
if (!who) return { message: "Escríbele algo a tu bot y vuelve a tocar Buscar" };
kino.storage.set("pending", who.id);
return { link: { candidate: "@" + who.username, confirm: "linkMe" } };
}
if (key === "linkMe") { // runs only after the person confirms
const chat = kino.storage.get("pending");
return { message: "Vinculado", setSettings: { chatId: String(chat) } };
}
}
- Kino shows its own question, "¿Eres tú, @ana?" / "Is this you, @ana?", and names your plugin in
it by the
nameof your manifest. It has "Sí, soy yo" / "Yes, it's me" and Cancelar (Cancelar focused). You cannot change its words. - Cancelar runs nothing: your plugin is not called and hears nothing. Only "Sí, soy yo" runs the
confirmaction, exactly once, like a press of that button (same settings, same 30 s). If it cannot start right then (another action or a save is running, or the person's unsaved edits cannot be saved), the question stays open and says so. candidate: a string, 1 to 64 characters after trimming, with runs of spaces collapsed to one. It may not hold control or invisible formatting characters, any space but the ordinary one, or the fillers that draw nothing (U+115F, U+1160, U+3164, U+FFA0, U+2800). It goes through the same secret scrubbing as your status lines and is shown as plain text.confirm: thekeyof anotheractionsetting of your plugin (not the one that is answering) that has noconfirmquestion of its own: an action that asks "¿Borrar todo?" can never be presented as "Is this you?".- Anything else refuses the link: your
messageis still shown, with Kino's generic error ("No se pudo completar. Inténtalo de nuevo.") under it. - A
messagein the same answer is shown too. Alinkin theconfirmaction's own answer is ignored (no chains). One question at a time: a newer link replaces a waiting one, and leaving the form drops it. - An older Kino ignores
link(it is additive, no newapiVersion), so also say inmessage(or a status line) what to do. - An action that only serves as a
confirmcan be hidden with"linkOnly": true: the person then sees one button, and only Kino's question runs the confirm action.
Checking before saving (validateSettings)¶
validateSettings(values) (optional, 20 s) runs before Kino saves. values holds only the valued
settings: strings trimmed, toggles as booleans, lists as arrays of objects.
- Return
nullto accept. { password: "La contraseña no es correcta" }refuses with that text under the field (at most 200 characters), or a text refuses with a general message. A key that is not one of your valued settings also refuses, its text shown as the general message.- Nothing is saved on a refusal and the person keeps what they typed.
- If it throws, times out or answers something Kino cannot read (an array, a number…), nothing is saved either, and the form offers "Guardar sin comprobar"; that button is offered only then, never after a refusal with messages.
Common rules¶
- Texts you return are shown after Kino removes any of your stored secrets from them.
- These three exports run even while a
requiredsetting is still empty, so a status line can say what is missing. - Saving any setting closes your sandbox, as always;
kino.storagesurvives. - If you declare
telemetry, a failure ofsettingsStatus,actionorvalidateSettingsis reported like any other function's (Logs and telemetry).
Try them with the kit (it prints what the app would keep): node sdk/run.mjs . settingsStatus,
node sdk/run.mjs . action logout, node sdk/run.mjs . validateSettings '{"email":"ana@x.co"}' (or node sdk/validate.mjs . --run … with
the same arguments, which also says what Kino shows and flags a call it never makes; --raw prints your answer
untouched). The kit does not apply the app's secret scrubbing, and
validateSettings receives exactly the JSON you type: the app sends only valued settings, trimmed. A
working example is plugins/sdk/test/settings-demo in Kino's repository.
A complete example¶
An account that is optional, a status line, a "Cerrar sesión" button, a quality choice, a switch and a
list of the person's own mirrors, all read the way kino.d.ts declares them:
{
"id": "mi-cuenta", "name": "Mi cuenta", "version": "1.0.0", "apiVersion": 6, "entry": "plugin.js",
"hosts": ["api.example.com"],
"capabilities": ["search", "resolve"],
"settings": [
{ "key": "account", "label": "Tu cuenta", "type": "section", "hint": "Opcional: sin cuenta ves el catálogo gratis" },
{ "key": "email", "label": "Correo", "type": "text", "hint": "ana@correo.com" },
{ "key": "password", "label": "Contraseña", "type": "password" },
{ "key": "linked", "label": "Estado", "type": "status" },
{ "key": "logout", "label": "Cerrar sesión", "type": "action", "confirm": "¿Cerrar la sesión de esta cuenta?" },
{ "key": "playback", "label": "Reproducción", "type": "section" },
{ "key": "quality", "label": "Calidad", "type": "select", "default": "auto",
"options": [{ "value": "auto", "label": "Automática" }, { "value": "hd", "label": "Alta" }, { "value": "sd", "label": "Ahorro de datos" }] },
{ "key": "spanishSubs", "label": "Solo subtítulos en español", "type": "toggle", "default": true },
{ "key": "mirrors", "label": "Espejos propios", "type": "list", "max": 5,
"fields": [{ "key": "url", "label": "Dirección", "type": "url", "required": true, "hint": "https://espejo.example.org" },
{ "key": "name", "label": "Nombre", "type": "text", "hint": "Espejo de la casa" }] }
]
}
const API = "https://api.example.com";
// Keyed by the account: settings can change under the plugin (another device, clearSettings).
const sessionKey = () => `session:${kino.config.get("email") ?? ""}`;
async function login(email, password) {
const r = await kino.fetch(`${API}/login`, { method: "POST", body: { json: { email, password } } });
if (r.status === 401) throw kino.error("auth_required", "login 401");
if (!r.ok) throw kino.error("unavailable", `login ${r.status}`);
return r.json().token;
}
async function session() {
await null; // the first await before anything can throw
const email = kino.config.get("email"); // undefined: signed out, free catalog
if (!email) return null;
const saved = kino.storage.get(sessionKey());
if (saved) return saved;
const token = await login(email, kino.config.get("password") ?? "");
kino.storage.set(sessionKey(), token, { ttlMs: 12 * 60 * 60 * 1000 });
return token;
}
export async function settingsStatus() { // one text per "status" key
const email = kino.config.get("email");
if (!email) return { linked: "Sin cuenta: ves el catálogo gratis" };
try {
await session();
return { linked: "Cuenta vinculada" };
} catch (e) {
return { linked: e.code === "auth_required" ? "El correo o la contraseña no coinciden" : "No se pudo revisar la cuenta ahora" };
}
}
export async function action(key) { // one call per "action" button
if (key !== "logout") return null;
const token = kino.storage.get(sessionKey());
if (token) await kino.fetch(`${API}/logout`, { method: "POST", headers: { Authorization: `Bearer ${token}` } });
kino.storage.remove(sessionKey());
return { message: "Sesión cerrada", clearSettings: ["email", "password"] };
}
export async function validateSettings(values) { // before saving: null accepts
await null;
if (values.email && !values.password) return { password: "Escribe la contraseña de esa cuenta" };
if (values.password && !values.email) return { email: "Escribe el correo de la cuenta" };
if (values.email) {
try {
await login(values.email, values.password);
} catch (e) {
if (e.code === "auth_required") return { password: "El correo o la contraseña no coinciden" };
throw e; // the person may "Guardar sin comprobar"
}
}
return null;
}
export async function search(query) {
const token = await session();
const r = await kino.fetch(`${API}/search?q=${encodeURIComponent(query.q)}`,
{ headers: token ? { Authorization: `Bearer ${token}` } : {} });
if (!r.ok) throw kino.error("unavailable", `search ${r.status}`);
return r.json().results.map((x) => ({ id: String(x.id), ref: String(x.id), title: x.title, kind: "movie" }));
}
export async function resolve(ref) {
const token = await session();
const quality = kino.config.get("quality"); // "auto", "hd" or "sd": a select always has a value
const r = await kino.fetch(`${API}/play/${encodeURIComponent(ref)}?q=${quality}`,
{ headers: token ? { Authorization: `Bearer ${token}` } : {} });
if (!r.ok) throw kino.error("not_found", `play ${r.status}`);
const s = r.json(); // { url, path, subtitles: [{ lang, url }] }
const mirrors = kino.config.get("mirrors") ?? []; // [{ url, name? }]: each url is a server the person typed
return {
url: s.url,
label: "Principal",
subtitles: kino.config.get("spanishSubs") ? s.subtitles.filter((t) => t.lang === "es") : s.subtitles,
alternatives: mirrors.slice(0, 8).map((m) => ({ url: m.url.replace(/\/+$/, "") + s.path, label: m.name || "Espejo" })),
};
}
What the person gets: a tab "Mi cuenta" in Ajustes with two headings; "Estado" reads "Sin cuenta: ves el catálogo gratis" until they type an account; Guardar checks the account before saving it; "Cerrar sesión" asks first, then empties the correo and the contraseña on every device of theirs; each mirror shows up as one more copy in the player's Servidor menu.
A value that stays on this device ("sync": false, apiVersion 13, Kino 0.9.74)¶
A password may say "sync": false to stay on the device where the person typed it: use it
for a value that only makes sense once, on one device, such as a two-step verification password your plugin sends right
away and then clears (clearSettings). Without it a password reaches the person's paired devices, sealed end to end,
like every other password (below).
{ "key": "tg_password", "label": "Contraseña de verificación", "type": "password", "sync": false }
- The value is never sent to a paired device, and a value another device sends never sets or clears it.
- It is in no backup and no kit.
- A sync provider's
sync.provisionmay still name it, for a one-shot secret handed once to a new device (a TV that should not type a two-step password): see Sync providers. It can never be thesync.keySecret("The \"keySecret\" of the \"sync\" field can't name a setting with \"sync\": false"). - Your plugin reads it with
kino.config.getand clears it as any password. - A
textmay say"sync": falsetoo, for a value that must stay on the device but is no secret to hide, such as a phone number the person types to sign in on that device: it is drawn as a plain text field (nothing masked) and kept exactly like a device-only password (never synced, never in a backup or a kit). It may not appear insync.provision("The \"provision\" of the \"sync\" field can't name a text setting with \"sync\": false"). syncon any other type refuses the manifest ("Only a setting of type password or text has \"sync\" (\"key\")"), and so does a value that is nottrueorfalse. Below apiVersion 13, and in a Kino build without it, the key is ignored and the password syncs as usual.node sdk/validate.mjschecks all of this like the app.
On the person's other devices¶
When the person pairs two of their devices (phone and TV), Kino keeps their plugins in step. What crosses, and what does not:
- Crosses: install, updates, on/off, uninstall, and the host approvals. Each device fetches your code itself; only the address and the approval travel. The other device installs silently when what it fetched asks for nothing beyond what the person approved on the first one; if you now ask for more (a new host, permission or capability), it waits in "Plugins de tus otros aparatos" for the normal consent sheet.
- Crosses: the values of
text,select,toggle,urlandlistsettings (alistthat has apasswordfield does not travel), andpasswordsettings (except apasswordortextwith"sync": false, apiVersion 13), sealed end to end with the key the devices agreed when they paired, never readable on the way. - Crosses: clears. A field the person empties, or an action's
clearSettings, empties it on their other devices too (passwords included). Arequiredsetting is never cleared remotely. A device running an older Kino build ignores clears and keeps its value. - Never crosses:
kino.storage, cookies, the cached Home rows. - A sync provider can also hand its settings to another device with "Enviar configuración" (the
ones its
sync.provisionnames): see Sync providers.
A value that arrives this way is applied without your validateSettings, and, like any saved
change, closes your sandbox. So write the plugin as if a setting can change under it at any time: key
any session you keep in kino.storage by the account it belongs to, and never put a device identity in
a setting, because it would be copied to the other device.
const sessionKey = `session:${kino.config.get("email") ?? ""}`; // not just "session"
A signed plugin installed from two different repositories on two devices counts as the
same plugin when both have the same id and the same author key: see
The same plugin at two addresses.