Pantallas y funciones nuevas sin subir tu apiVersion¶
Disponible con Kino 0.9.74
Disponible desde Kino 0.9.74. Solo un Kino 0.9.74 o posterior lee el bloque
enhancements; una versión anterior de Kino lo ignora, como cualquier clave que no conoce, y sigue instalando
y corriendo tu plugin como siempre: nunca lo rechaza por este bloque.
Un plugin que sube su apiVersion a 14 es rechazado por todo Kino anterior («Este plugin necesita una versión más nueva
de Kino»). Para no perder a esas personas, deja tu apiVersion como está y ofrece las pantallas y las
demás funciones de apiVersion 14 en un bloque opcional que solo lee un Kino más nuevo.
El bloque enhancements¶
"apiVersion": 8,
"capabilities": ["search", "home", "resolve"],
"enhancements": { "14": { "capabilities": ["screen", "library"], "screen": { "label": "Inicio", "menuOpens": "both" } } }
Un Kino anterior ignora la clave y nunca llama screen/screenEvent (el JS sigue siendo un solo archivo); este Kino
mezcla el bloque y lo revisa con las reglas de apiVersion 14. Un bloque que falla se descarta y se anota en el registro,
nunca es un rechazo.
Otro ejemplo, con un trabajo en segundo plano:
"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] }]
} }
Cómo lo lee Kino¶
- Las claves son el
apiVersionque trajo la función: hoy,"14". Un Kino que conoce la clave mezcla su bloque sobre el manifiesto, en orden numérico de claves. Una clave por encima del apiVersion de ese Kino se ignora. capabilitiesse suman. Solo se pueden agregar asíscreen,library,playerPanelTab,playerControl,room,schedule,shared,ai,files(clave"21"),progress(clave"22") yplayerSlot(clave"23", con su bloqueslot, que reemplaza el del manifiesto).screen,settings(la lista entera),panelyjobsreemplazan los del manifiesto.playerPanelTaby unpanelcon"contributes": truevan juntos en el mismo bloque, y tambiénscheduley susjobs(cada uno necesita al otro). Losjobssolo los trae un bloque: unjobsen el nivel de arriba por debajo de apiVersion 14 nunca se lee.- Después todo se revisa con ese apiVersion, con las mismas reglas que los campos normales:
screen,jobs,panel, las capacidades. - Tu
apiVersionnunca se mueve, así que nada más cambia de comportamiento. - Clave
"20"(Kino 0.9.81):providesyconsumes, el protocolo entre plugins. Reemplazan los del manifiesto y se revisan con las reglas del apiVersion 20:"apiVersion": 7, "enhancements": { "20": { "provides": { … } } }abre una puerta en Kino 0.9.81 y posteriores mientras el plugin se sigue instalando como siempre en todo Kino anterior (así abre TMDB 1.3.0 y posteriores su puertamovies). - Clave
"20":visualBrowser(true), la clave del manifest para una ventana de navegador que la persona maneja. Reemplaza la del manifest y se revisa con las reglas del apiVersion 20, así que un plugin que conserva unapiVersionmás bajo ofrece la ventana solo a un Kino que la tenga:"enhancements": { "20": { "visualBrowser": true } }. Revisakino.visualBrowser?.availableantes de usarla.
Cuándo se descarta un bloque¶
Tu plugin nunca se rechaza por un enhancements. El bloque se descarta (con una línea en el registro) y el plugin corre
como dice su propio manifiesto cuando:
- falla esas reglas (una pantalla mala, una capacidad que no se puede agregar, cualquier otro campo);
- su clave es igual o menor que tu propio
apiVersion(declara cada función una sola vez); - su
settingscambia el tipo de un ajuste que tu manifiesto declara (mantén la lista como un superconjunto de la tuya: los valores se sincronizan por clave con aparatos que tienen un Kino anterior); - su
screen.replacesnombra Categorías y tu propio apiVersion no las tiene (por debajo de 6); - a tu script le falta un export que el bloque necesita de nuevo (
screen/screenEvent,job, osettingsStatus/actionpara esos ajustes). Kino lo revisa al instalar y en cada arranque; - un trabajo con
enabledByno nombra uno de tus ajustestoggle.
node sdk/validate.mjs reporta como problema cada bloque que Kino descartaría.
El consentimiento¶
Es el de un manifiesto normal. Las líneas rojas de library, playerPanelTab, playerControl, room, schedule y ai
se preguntan al instalar y en la actualización que las agrega (se muestran primero y abiertas, abajo), nunca
las aprueba Kino por su cuenta, y al importar con el kit empiezan sin marcar; shared es una línea simple.
Sus funciones siguen al bloque: tus trabajos corren, y kino.shared y kino.ai existen, solo en un Kino que lo leyó.
kino.library existe en todo Kino de apiVersion 14, pero hasta que la persona aprueba la línea sus llamadas rechazan con
permission_denied: a quien instaló tu plugin en un Kino anterior y después actualizó Kino se le pregunta solo con tu
siguiente versión. Así que typeof kino.library === "object" no basta: atrapa el rechazo y funciona sin él.
En un Kino anterior nada de esto existe: deja donde ya está el trabajo que tu plugin hace sin trabajos en segundo plano.
Una lista settings en un bloque¶
Una lista settings dentro de un bloque se lee con el apiVersion del bloque: sus textos en inglés (labelEn, hintEn,
confirmEn), devices, linkOnly, los elementos help, link y qr, "sync": false y unlockWith se aplican en un
Kino que leyó el bloque, y se ignoran en uno anterior, que lee tu lista base. Por eso:
- Mantén cada clave de la lista base con su tipo (si no, el bloque se descarta:
settingRetyped) y con susync("settings" changes "sync" of the setting "<key>", también se descarta: un valor que se sincroniza en un Kino y se queda en el aparato en otro sería distinto entre los aparatos de la persona). Una clave NUEVA sí puede decir"sync": false. - Las dos funciones que dependen de lo que la lista puede declarar siguen a la lista: el
hidede una respuesta desettingsStatusy elsetSettingsde una acción que llena unpassword(las dos desde apiVersion 13) se leen con el apiVersion del bloque cuando el bloque reemplazósettings, y con tu propio apiVersion si no (un bloque que solo agrega una pantalla no les cambia nada). setSettingssigue llenando solo unpasswordque declara la lista vigente, sigue rechazando el campo entero por una clave no declarada o de otro tipo, nunca mueve un ajusteunlockWithde su valor por defecto, y el formulario guarda el valor como uno escrito (sellado, nunca se muestra de vuelta, solo en el aparato con"sync": false).- Lo demás que lee tu propio apiVersion se queda así a propósito: el límite de
secretssellados, las reglas de la llave de cifrado, Categorías, y toda función fuera desettings.
Mira también el formulario de ajustes.
Actualizaciones: los consentimientos nuevos van primero¶
Cuando una actualización de tu plugin agrega una línea roja (una de las capacidades de arriba, "fetchHosts": "any",
browser, tracking…) o un host nuevo, la hoja de actualización de Kino la muestra primero y abierta, bajo «Nuevo en
esta actualización»:
- En orden de gravedad: cualquier host primero, después las demás capacidades, una línea agrupada para los hosts nuevos inseguros, y luego los hosts nuevos.
- Cada línea es una parada del D-pad en la TV, con un aviso «Hay más abajo».
- Lo que la persona ya aprobó se queda detrás de «Ver detalles».
Así un solo toque nunca aprueba algo que no se vio. La actualización espera a la persona; una línea simple (shared) no la
detiene. En una primera instalación todo sigue detrás de «Ver detalles», como antes.
Explica en las notas de tu versión por qué necesitas el alcance nuevo. Mira también Lo que ve la persona y Publicar.