Screens and newer features without raising your apiVersion¶
Available with Kino 0.9.74
Available from Kino 0.9.74. Only Kino 0.9.74 or later reads the
enhancements block; an older Kino ignores it, like any key it does not know, and keeps installing and running
your plugin as always: it never refuses it because of this block.
A plugin that raises its apiVersion to 14 is refused by every older Kino («Este plugin necesita una versión más nueva de
Kino»). To keep those people, leave your apiVersion as it is and offer screens and the other apiVersion 14
features in an optional block only a newer Kino reads.
The enhancements block¶
"apiVersion": 8,
"capabilities": ["search", "home", "resolve"],
"enhancements": { "14": { "capabilities": ["screen", "library"], "screen": { "label": "Inicio", "menuOpens": "both" } } }
An older Kino ignores the key and never calls screen/screenEvent (the JS stays one file); this Kino merges the block and
checks it with apiVersion 14's rules. A block that fails is dropped and logged, never a refusal.
Another example, with a background job:
"apiVersion": 8,
"enhancements": { "14": {
"capabilities": ["screen", "schedule", "shared"],
"screen": { "label": "Mi plugin", "opensFrom": ["settings"] },
"jobs": [{ "id": "refresh", "label": { "es": "Actualizar", "en": "Refresh" }, "everyMin": 180, "everyOptions": [60, 180, 360] }]
} }
How Kino reads it¶
- The keys are the
apiVersionthat brought the feature: today,"14". A Kino that knows the key merges its block over the manifest, keys in numeric order. A key above that Kino's apiVersion is ignored. capabilitiesare added. Onlyscreen,library,playerPanelTab,playerControl,room,schedule,shared,ai,files(key"21"),progress(key"22") andplayerSlot(key"23", with itsslotblock, which replaces the manifest's) can be added this way.screen,settings(the whole list),panelandjobsreplace the manifest's.playerPanelTaband apanelwith"contributes": truecome together in one block, and so doscheduleand itsjobs(each needs the other). Only a block bringsjobs: a top-leveljobsbelow apiVersion 14 is never read.- Then everything is checked at that apiVersion, with the very same rules as the plain fields:
screen,jobs,panel, the capabilities. - Your
apiVersionnever moves, so nothing else changes behaviour. - Key
"20"(Kino 0.9.81):providesandconsumes, the plugin protocol. They replace the manifest's and are checked with apiVersion 20's rules:"apiVersion": 7, "enhancements": { "20": { "provides": { … } } }opens a door on Kino 0.9.81 and later while the plugin keeps installing as before on every older Kino (that is how TMDB 1.3.0 and later opens itsmoviesdoor). - Key
"20":visualBrowser(true), the manifest key for a browser window the person drives. It replaces the manifest's and is checked with apiVersion 20's rules, so a plugin that keeps an olderapiVersionoffers the window only to a Kino that has it:"enhancements": { "20": { "visualBrowser": true } }. Checkkino.visualBrowser?.availablebefore using it.
When a block is dropped¶
Your plugin is never refused because of an enhancements block. The block is dropped (with a log line) and the plugin
runs as its own manifest says when:
- it fails those rules (a bad screen, a capability that cannot be added, any other field);
- its key is at or below your own
apiVersion(declare each feature once); - its
settingschange the type of a setting your manifest declares (keep the list a superset of yours: values sync by key with devices on an older Kino); - its
screen.replacesnames Categorías and your own apiVersion lacks them (below 6); - your script lacks an export the block newly needs (
screen/screenEvent,job, orsettingsStatus/actionfor such settings). Kino checks it at install and at every start; - a job with
enabledBydoes not name one of yourtogglesettings.
node sdk/validate.mjs reports every block Kino would drop as a problem.
Consent¶
It is a plain manifest's. The red lines of library, playerPanelTab, playerControl, room, schedule and ai are
asked at install and on the update that adds them (shown first and open, below), never approved by Kino on its
own, and unticked in a kit import; shared is a plain line.
Their features follow the block: your jobs run, and kino.shared and kino.ai exist, only on a Kino that read it.
kino.library exists on every apiVersion 14 Kino, but until the person approves the line its calls reject with
permission_denied: someone who installed your plugin on an older Kino and then updated Kino is asked only with your
next version. So typeof kino.library === "object" is not enough: catch the refusal and work without it.
On an older Kino none of it exists: keep the work your plugin does without background jobs where it already is.
A settings list in a block¶
A settings list inside a block is read at the block's apiVersion: its English texts (labelEn, hintEn, confirmEn),
devices, linkOnly, help, link and qr items, "sync": false and unlockWith all apply on a Kino that read the
block, and are ignored on an older one, which reads your base list. So:
- Keep every key of the base list with its type (else the block is dropped:
settingRetyped) and itssync("settings" changes "sync" of the setting "<key>", also dropped: a value that syncs on one Kino and stays on the device on another would differ between the person's devices). A NEW key may say"sync": false. - The two runtime features that depend on what the list may declare follow the list too: a
settingsStatusanswer'shideand an action'ssetSettingsfilling apassword(both from apiVersion 13) are read at the block's apiVersion when the block replacedsettings, and at your own apiVersion otherwise (a block that only adds a screen changes nothing for them). setSettingsstill fills only apasswordthe list in effect declares, still refuses the whole field for an undeclared key or another type, never moves anunlockWithsetting off its default, and the form saves the value as a typed one (sealed, never shown back, device-only with"sync": false).- What else reads your own apiVersion stays so on purpose: the sealed
secretslimit, the cipher key rules, Categorías, and every feature outsidesettings.
See also the settings form.
Updates: new consents come first¶
When an update of your plugin adds a red line (one of the capabilities above, "fetchHosts": "any", browser,
tracking...) or a new host, Kino's update sheet shows it first and open, under «Nuevo en esta actualización»:
- By severity: any-host first, then the other capabilities, one grouped line for new insecure hosts, then the new hosts.
- Each line is a D-pad stop on the TV, with a «Hay más abajo» cue.
- What the person already approved stays behind «Ver detalles».
So one tap never approves something unseen. The update waits for the person; a plain line (shared) does not hold it back.
On a first install everything stays behind «Ver detalles», as before.
Describe in your release notes why you need the new reach. See also What people see and Publish.