Formulario de ajustes (apiVersion 6)¶
Los ajustes de siempre guardan valores que tu código lee con kino.config.
Desde "apiVersion": 6 (Kino 0.9.50) el formulario también puede mostrar cosas y hacer cosas,
y cada plugin instalado tiene su propia pestaña en Ajustes. Esta página tiene todos los tipos de
campo, los tres tipos sin valor, las dos ayudas para configurar de apiVersion 12,
las funciones que los llenan y los revisan, y un ejemplo completo.
Para una interfaz nueva, usa las pantallas
Desde apiVersion 14 (Kino 0.9.74) la forma preferida de construir la configuración, la bienvenida o
un tablero de tu plugin son las pantallas, que también pueden mostrar este mismo formulario con el
nodo settings. Este formulario sigue funcionando para compatibilidad.
Su propia pestaña en Ajustes¶
Cada plugin instalado y encendido tiene su propia pestaña en Ajustes (celular y TV), con el nombre
del plugin y su interruptor de Modo debug; cuando tiene settings, la pestaña
también muestra su formulario, y Plugins ▸ Configurar abre el mismo formulario. Por eso, desde Kino 0.9.50,
el error auth_required dice "Configura {plugin} en Ajustes ▸ {plugin}" cuando tu plugin declara
ajustes.
Todos los tipos de campo¶
El formulario muestra tus ajustes en el orden del manifiesto, cada uno con su label y, debajo, su
hint. Once tipos, y un duodécimo, qr, desde apiVersion 13 (Kino 0.9.74):
type |
Lo que ve la persona | Lo que devuelve kino.config.get(key) |
Desde |
|---|---|---|---|
text |
un campo de texto (máximo 500 caracteres) | el texto, o undefined |
apiVersion 1 |
password |
un campo de texto oculto (máximo 500), guardado cifrado en el aparato | el texto, o undefined |
apiVersion 1 |
url |
un campo de dirección (máximo 2.048): http/https; ese servidor pasa a ser un host al que tu plugin puede llegar (Los servidores de la persona) |
la dirección tal como se escribió, o undefined |
apiVersion 1 |
toggle |
un interruptor | true / false (false si no hay default) |
apiVersion 1 |
select |
una elección entre options |
el value escogido (la primera opción si no hay default) |
apiVersion 1 |
list |
una lista que la persona arma con "Agregar", cada entrada un diálogo con los fields de la lista |
un arreglo de { [clave del campo]: texto }, o undefined si está vacía |
apiVersion 4 |
section |
un título, con hint como explicación |
nada | apiVersion 6 |
status |
una línea de solo lectura que llena tu settingsStatus() |
nada | apiVersion 6 |
action |
un botón que corre tu action(key) |
nada | apiVersion 6 |
link |
un botón que abre una dirección https por el sistema, solo cuando la persona lo toca (Ayudas para configurar) |
nada | apiVersion 12 |
help |
un botón ("Ayuda") que abre tus instrucciones en una ventana (Ayudas para configurar) | nada | apiVersion 12 |
qr |
un código QR dibujado en el aparato con un texto que devuelve tu settingsStatus() (Un código QR) |
nada | apiVersion 13 (Kino 0.9.74) |
Lo que puede llevar cada entrada:
| Atributo | Tipos | Regla |
|---|---|---|
key |
todos | obligatorio, ^[a-z][a-zA-Z0-9_]{0,31}$, único en la lista |
label |
todos | obligatorio, de 1 a 40 caracteres (en un help es opcional: sin él, el botón dice "Ayuda") |
type |
todos | obligatorio, uno de los once de arriba |
hint |
todos | opcional, máximo 80 caracteres: el ejemplo o la explicación debajo del campo. En una section, hasta 300 y se parte en varias líneas (Kino 0.9.51; antes de 0.9.51 se rechaza una de más de 80) |
required |
text, password, url, list |
opcional true/false. Un ajuste obligatorio sin valor detiene toda llamada ("Falta configurar") |
default |
text, password, toggle, select |
opcional. Nunca en url ni en list ("… no puede tener valor por defecto: usa "hint"") ni en los tipos sin valor; tiene que servir para su tipo (el default de un select es uno de sus value) |
options |
solo select |
obligatorio: de 1 a 20 { "value", "label" }, value de 1 a 40 caracteres y sin repetir, label de 1 a 40 |
fields |
solo list |
obligatorio: de 1 a 4, cada uno { key, label, type, hint?, required? } con type "text" o "url", sin default ("Solo un ajuste de tipo list tiene "fields"") |
max |
solo list |
opcional, número entero de 1 a 50 (20 por defecto): cuántas entradas |
confirm |
solo action, apiVersion 6 |
opcional, de 1 a 120 caracteres: se pregunta antes de correr la acción, con Cancelar enfocado ("Solo un ajuste de tipo action tiene "confirm"") |
url |
solo link, apiVersion 12 |
obligatorio: https://, sin usuario ni contraseña, máximo 2.048 caracteres |
title, titleEn, body, bodyEn |
solo help, apiVersion 12 |
el título (máximo 60) y el texto (máximo 2.000) de la ventana; body o bodyEn es obligatorio |
labelEn, hintEn, confirmEn |
los de label, hint, confirm |
opcionales, apiVersion 9 (Kino 0.9.55): el mismo texto en inglés, con los mismos límites (Textos en inglés) |
devices |
todos | opcional, apiVersion 12: ["phone"], ["tv"] o los dos, los aparatos que lo dibujan (un tipo de aparato) |
linkOnly |
action |
opcional true/false, apiVersion 12: nunca se dibuja, solo corre como confirm de un link (linkOnly) |
sync |
password, text |
opcional true/false, apiVersion 13 (Kino 0.9.74): false deja el valor en este aparato (sync: false) |
Cualquier otra clave de una entrada se ignora. Un manifiesto que incumple una regla se rechaza al
instalar con un mensaje que nombra el ajuste (El ajuste "quality" necesita opciones); una list por
debajo de apiVersion 4, un section/status/action por debajo de apiVersion 6 o un link/help por
debajo de apiVersion 12 también se rechazan. Límites: 12 ajustes con valor (text, password, url,
toggle, select, list) y, desde apiVersion 6, 16 sin valor (entre ellos, desde apiVersion 12, hasta
4 link y 4 help).
No hay campos condicionales: todo ajuste se muestra siempre, tenga lo que tenga otro. Usa un
section con hint para decir qué campos van juntos ("Opcional: sin cuenta ves el catálogo gratis"),
déjalos opcionales, y deja que validateSettings rechace una combinación que no tenga
sentido.
¿password o secrets sellados? Un ajuste password es la credencial de la persona: ella la
escribe, tu código la lee y viaja sellada de punta a punta a sus otros aparatos. Una clave que es
tuya, de quien hizo el plugin (una clave fija del reproductor del sitio), va en los
secrets sellados del manifiesto, y tu código solo tiene un marcador.
Textos en inglés (apiVersion 9, Kino 0.9.55)¶
Kino habla español o inglés desde 0.9.54 (Ajustes ▸ App ▸ Idioma). Desde Kino 0.9.55, con "apiVersion": 9, cada
texto de tu formulario puede llevar al lado su versión en inglés, con la misma clave y En al final:
| Dónde | Claves en inglés | Límite |
|---|---|---|
| cualquier ajuste | labelEn, hintEn |
los de label (1 a 40) y hint (80; 300 en una section) |
un action con confirm |
confirmEn |
de 1 a 120, y solo junto a confirm |
una opción de un select |
labelEn |
de 1 a 40 |
un campo de una list |
labelEn, hintEn |
1 a 40 y 80 |
section del manifiesto |
labelEn |
de 1 a 20 (El manifiesto) |
{ "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" }] }
- El texto de siempre es el español y el de respaldo: con la app en inglés, Kino muestra cada versión en inglés que exista y, donde falte una, el texto de siempre (arriba, la opción «Normal» se ve igual en los dos idiomas). Con la app en español nada cambia.
- Tu código no se entera: las claves, los tipos, los valores y los
defaultson los mismos en los dos idiomas, ykino.configdevuelve lo mismo. Si quieres saber el idioma, leekino.lang. - Desde apiVersion 9: por debajo de 9 estas claves son desconocidas y se ignoran sin revisarlas, como en un Kino
anterior (que tampoco acepta
"apiVersion": 9). - Las mismas reglas que el texto de siempre: uno vacío, de más del límite o que no sea texto rechaza el manifiesto
al instalar ("\"labelEn\" del ajuste \"quality\" debe ser un texto de 1 a 40 caracteres"; en una opción, "Una
opción del ajuste \"quality\" no es válida");
nulles como no ponerlo.confirmEnsolo va en unaction("Solo un ajuste de tipo action tiene \"confirmEn\"") y conconfirmal lado ("…necesita también \"confirm\""). - Kino solo habla español e inglés: cualquier otra clave de idioma (
labelPt,labelFr) es una clave desconocida y se ignora.
node sdk/validate.mjs revisa los mismos límites y, cuando tu plugin usa alguna versión en inglés, te dice cuántos
textos la tienen y cuáles no.
Tres tipos que no guardan valor¶
Desde apiVersion 6 hay tres tipos que no guardan ningún valor (nunca están en kino.config, nunca son
required, sin default), máximo 16 de ellos además de los 12 ajustes con valor:
"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: un título;hintes su explicación.status: una línea de solo lectura. Kino llama tusettingsStatus()cuando se abre el formulario (10 s) y muestra el texto que devuelves bajo esa clave:{ linked: "Vinculada como ana@…" }(máximo 200 caracteres). Mientras no responde la línea dice "Cargando…"; una clave que falta o un valor que no es texto muestran "Sin información"; un tiempo agotado o un error muestran "No se pudo consultar". El resto del formulario sigue funcionando en todos los casos. Export obligatorio cuando existe un ajustestatus.action: un botón. Kino llama tuaction(key)(30 s), una acción a la vez (los otros botones y Guardar esperan), y muestra elmessageque devuelves (máximo 300 caracteres) o "Listo"; si lanza un error o se pasa del tiempo, la persona ve el texto del error. Kino vuelve a pedirsettingsStatus()después de cada acción (y al abrir el formulario), así que las líneas de estado describen lo que acaba de hacer;refresh: truese sigue aceptando y no cambia nada.confirm(de 1 a 120 caracteres) pregunta antes, con Cancelar enfocado. Export obligatorio cuando existe un ajusteaction.
Un código QR: qr (apiVersion 13, Kino 0.9.74)¶
Un cuarto tipo sin valor, que cuenta entre los 16: un código QR dibujado en el formulario, en el aparato (nada sale a la red para dibujarlo). Es la forma de que una TV muestre un código de inicio de sesión para que lo escanee un teléfono.
{ "key": "login", "label": "Escanéalo desde tu teléfono", "labelEn": "Scan it from your phone", "type": "qr", "refreshMs": 5000 }
- Su texto es lo que tu
settingsStatus()devuelve bajo esa llave, como una líneastatus, pero entero: de 1 a 512 caracteres sin caracteres de control; una direcciónhttp/httpssolo si es https en un host público (nunca la red de la casa); cualquier otro texto (un enlace de app comoexampleapp://login?token=…, un código para vincular) se dibuja tal cual. Un texto más largo, algo que no es texto, o uno que lleva uno de tus secretos sellados no dibuja QR, y unqrsin texto no dibuja nada (ni etiqueta, ni línea de relleno, ni fila vacía), así que un QR que solo necesita un paso de un inicio de sesión simplemente no está en los demás. refreshMs(de 2000 a 60000; solo un ajusteqrlo tiene): Kino preguntasettingsStatus()cuando se abre el formulario, después de cada acción y cada esa cantidad de ms mientras el formulario está en pantalla y la app al frente. Un refresco nunca empieza mientras la llamada anterior siga corriendo, y el QR en pantalla se queda hasta que el texto nuevo lo reemplaza. Así un código que vence cada 30 s sigue sirviendo, y una línea de estado al lado pasa a "Listo" cuando ya se usó el código.- Export obligatorio:
settingsStatus. Mostrar un QR no necesita capacidad; escanear uno (kino.qr.scan) necesitaqrScan. La receta completa entre dos aparatos: Códigos QR.
Esconder lo que no hace falta (hide, apiVersion 13, Kino 0.9.74)¶
La respuesta de tu settingsStatus() puede llevar hide: una lista de claves de tus propios ajustes que el formulario
(celular y TV) no dibuja mientras esa respuesta sea la vigente. Úsalo para un formulario que cambia según el paso: el
botón de iniciar sesión, su QR y el paso de la contraseña cuando la persona ya inició sesión, o "Cerrar sesión" mientras
no la ha iniciado.
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"] };
}
- Sus valores guardados se quedan y no se borra nada; siguen contando para las reglas del formulario (uno
requiredque escondes sigue bloqueando Guardar). - Las claves desconocidas y lo que no es texto se ignoran, se leen como mucho 32 entradas, y una respuesta que falla no esconde nada.
- Kino vuelve a preguntar
settingsStatus()después de cada acción, así que el formulario sigue el paso al que llegó la acción. - Por debajo de apiVersion 13 la clave se ignora.
sdk/contract.mjsexportastatusHide(answer, manifest), que da las claves que la app escondería.
Ayudas para configurar: link y help (apiVersion 12, Kino 0.9.74)¶
Dos tipos de ajuste le ayudan a la persona a configurar tu plugin. Ninguno guarda valor (nunca están en
kino.config, nunca son required, sin default), y los dos cuentan entre los 16 ajustes sin valor.
"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: un botón que abreurlpor el sistema solo cuando la persona lo toca (en un celular,https://t.me/...abre la app de Telegram si está instalada). Kino muestra su propio "Abrir enlace" y el host debajo del botón, no le hace ninguna petición a ese host y no lo cuenta como un acceso a la red de tu plugin. En un TV (casi nunca tiene navegador) el toque muestra la dirección como texto y como un QR para abrirla en el celular.urltiene que serhttps://, sin usuario ni contraseña, de máximo 2.048 caracteres;labeles obligatorio. Una dirección que lleva uno de tus secretos guardados no se muestra. Kino abre la forma canónica de la dirección (el host en minúsculas), la misma que nombra. No hay otra forma de que un plugin le pida a Kino abrir una dirección.help: un botón pequeño ("Ayuda" / "Help", o tu propiolabel) que abre una ventana con tus instrucciones, titulada con el nombre de tu plugin. Solo texto plano: se conservan los saltos de línea, las marcas se muestran tal cual y nada es tocable (para una dirección usa unlink).titlede máximo 60 caracteres,bodyde máximo 2.000 (bodyobodyEnes obligatorio); si falta el texto en español o en inglés se muestra el otro; a todo se le quitan tus secretos. En un TV se desplaza con el control, el foco empieza en Cerrar y Atrás la cierra.
La etiqueta de un link y la etiqueta, el título y el texto de un help no pueden llevar caracteres de
control (el texto conserva sus saltos de línea), formato invisible ni cambios de dirección del texto; si
no, se rechaza el manifiesto. Máximo 4 link y 4 help por plugin. Un Kino anterior rechaza
apiVersion 12, así que un plugin que los usa declara "apiVersion": 12.
Que la ayuda sea corta y práctica: qué datos necesita el plugin y dónde se consiguen, en pocas
líneas. Si el plugin habla con un servidor propio de la persona, la ayuda no le enseña a armarlo: pon un
link a la guía completa (el límite técnico de 2.000 caracteres no es una meta).
Ajustes para un tipo de aparato (devices, apiVersion 12, Kino 0.9.74)¶
Cualquier elemento de los ajustes (un campo, una sección, un estado, una acción, un link o un help)
puede decir en qué aparatos se dibuja: "devices": ["phone"], ["tv"] o los dos; sin él se muestra en
todos.
{ "key": "botToken", "label": "Token del bot", "labelEn": "Bot token", "type": "password", "devices": ["phone"] }
Solo cambia lo que se dibuja. En un aparato que deja fuera, el formulario no dibuja ni revisa ese
elemento (un campo required oculto nunca bloquea Guardar ahí), pero su valor sigue guardado, se guarda
igual al guardar, se sincroniza con los otros aparatos de la persona, viaja con sync.provision y tu
código lo lee con kino.config. Úsalo para la preparación que un TV no hace bien, como un token que se
pega en el celular: Sync-Gram y Sync Servidor dibujan su preparación solo en el celular, y el TV recibe los
valores con "Recibir configuración". Un aparato desconocido, una lista vacía o uno repetido rechazan
el manifiesto ("devices" of the setting "<key>" must be a list of different devices: "phone", "tv");
por debajo de apiVersion 12 la clave se ignora. El kit de Node no dibuja un formulario: validate.mjs
solo revisa el campo.
Un ajuste que guarda el código +18 (unlockWith, apiVersion 14, Kino 0.9.74)¶
Disponible con Kino 0.9.74
Disponible desde Kino 0.9.74. Por debajo de apiVersion 14 la clave se ignora.
Un toggle o un select puede decir "unlockWith": "adultCode": antes de que la persona lo mueva lejos de
su default (un toggle fuera de su valor por defecto, un select a cualquier otra opción), Kino pide el código +18
del aparato con su propia ventana (el campo «Código» de Ajustes en el celular, el diálogo de teclado del candado en un
TV; mientras rige el código por defecto, la ventana lo dice, como toda ventana +18). El cambio se aplica solo cuando el
código es correcto; un código equivocado dice «Código incorrecto» y deja el valor anterior, y Cancelar o Atrás dejan el
control como estaba. Volver hacia el valor por defecto nunca lo pide. Tu plugin nunca ve el código, y darlo no
desbloquea nada más (ninguna entrada +18 aparece por eso). Úsalo para un filtro que la persona no debería apagar a la
ligera, como el «No mostrar noticias +18» del ejemplo de noticias (encendido por defecto).
{ "key": "hideAdult", "label": "No mostrar noticias +18", "labelEn": "Hide 18+ news", "type": "toggle", "default": true, "unlockWith": "adultCode" }
Funciona en el formulario de ajustes de Kino dondequiera que se dibuje: tu pestaña en Ajustes y el
nodo settings de una pantalla o de un panel. Tu propio código solo puede mover el
ajuste hacia su valor por defecto: un config de una respuesta que lo aleja se descarta (is locked (unlockWith
adultCode): only the person moves it away from its default, in Kino's settings form), un setSettings de una
acción que lo aleja se rechaza entero, y un campo no puede hacerle bind (bind "<key>" is locked (unlockWith
adultCode): show it in a settings node): muéstralo con { "type": "settings", "keys": ["<key>"] }. El valor se
sincroniza con los otros aparatos de la persona como cualquier ajuste (y viaja con «Enviar a otro aparato»); el código
se pide en cada aparato en el momento del cambio. unlockWith en otro tipo, o un valor distinto de "adultCode",
rechaza el manifiesto (Only a setting of type toggle or select has "unlockWith" ("<key>"), "unlockWith" of the
setting "<key>" must be one of: adultCode). El kit de Node no dibuja un formulario: validate.mjs revisa el campo y
run.mjs aplica las mismas reglas de config, bind y setSettings.
Acciones que solo corre un link (linkOnly, apiVersion 12, Kino 0.9.74)¶
Una action puede decir "linkOnly": true: nunca se dibuja en ningún aparato y solo corre como el
confirm del link de otra acción, después de la pregunta de Kino. Así un par "buscar, luego
confirmar" le muestra a la persona un solo botón (Verificar mensaje en el chat de Sync-Gram); sin él, la
acción de confirmar es un segundo botón. linkOnly en algo que no es una acción, o que no es true o
false, rechaza el manifiesto.
Olvidar ajustes desde una acción (clearSettings)¶
Una acción también puede olvidar ajustes propios con clearSettings: hasta 12 claves de tus ajustes
con valor declarados (text, url, password, toggle, select, list). Cuando la acción responde,
Kino los vacía exactamente como si la persona hubiera vaciado los campos y oprimido Guardar (una
password también sale del Keystore), cierra tu sandbox y olvida las cookies y las filas de Inicio
guardadas como con cualquier cambio guardado (kino.storage sobrevive), vuelve a cargar el formulario y
vuelve a pedir settingsStatus(); tu message igual se muestra. Así un botón "Cerrar sesión" evita que
el siguiente token vencido vuelva a iniciar sesión con la cuenta guardada.
export async function action(key) {
if (key === "logout") {
await api.logout(); // avisa primero al servidor: un error aquí conserva la cuenta guardada
return { message: "Sesión cerrada", clearSettings: ["email", "password"] };
}
}
(Aquí email y password tienen que ser ajustes opcionales; marca la cuenta required solo si el
plugin no puede funcionar sin sesión.)
Límites:
- Solo se toca el plugin de la propia acción, nunca otro.
- Una entrada que no es texto, que no existe, que nombra un
section/status/action, que nombra un ajusterequired(vaciarlo haría fallar todas las llamadas siguientes), que se repite o que viene después de la duodécima se descarta con una línea en el log (run.mjsmuestra[dropped by Kino]); un valor que no es un arreglo se ignora. - Una acción que lanza un error o se pasa del tiempo no vacía nada.
Llenar ajustes propios desde una acción (setSettings, Kino 0.9.74)¶
Una acción también puede llenar ajustes propios con setSettings: hasta 8 claves de tus ajustes
text o select, cada una con un texto. Así una acción "Vincular" guarda el chat que encontró y la
persona no escribe nada. Kino quita los espacios de los extremos de cada valor, lo revisa como uno
escrito (largo, una de las opciones) y guarda los valores por el mismo Guardar del formulario: llegan a
los otros aparatos de la persona y quedan en el perfil en uso como los escritos a mano, y tu sandbox se
cierra como con cualquier cambio guardado. Es aditivo (sin apiVersion nueva): un Kino anterior lo
ignora.
return { message: "Vinculado", setSettings: { chatId: String(chat.id) } };
- Nunca un
url(su valor se vuelve un servidor al que tu plugin puede llegar, así que solo la persona lo escribe), untoggle, unalistni un ajuste sin valor; un ajusterequirednunca se vacía así. Unpasswordsolo desdeapiVersion13 (abajo); por debajo, todo el campo se rechaza. - Kino no corre tu
validateSettingscon estos valores (tú los escogiste), y rechaza un valor que contiene uno de tus secretos guardados en vez de copiarlo a un ajuste simple que se sincroniza. - Una clave desconocida o secreta, un valor que no es texto o que no pasa su revisión, una clave que
también está en
clearSettings, un valor que contiene uno de tus secretos o más de 8 claves rechazan todo el campo: no se aplica nada, tumessagese muestra igual y Kino agrega debajo su error genérico. - Funciona desde tu formulario de ajustes (cualquier acción, también la acción
confirmde un vínculo).
Llenar una contraseña (apiVersion 13, Kino 0.9.74)¶
Una acción puede llenar uno de tus propios ajustes password, para un valor que tu plugin inventa en vez de pedirle a la
persona que lo escriba:
return { message: "Clave creada", setSettings: { syncKey: kino.crypto.randomBytes(32) } }; // 64 caracteres hexadecimales
Kino lo guarda igual que una contraseña escrita: sellada en el Keystore, sincronizada sellada de punta a punta con los
otros aparatos de la persona (o solo en este aparato cuando el ajuste dice "sync": false) y con
asteriscos en el formulario. Nunca se registra, y cada contraseña que nombra tu respuesta se borra del message y del
link de esa misma respuesta, así que nunca se vuelve a mostrar en la página. Valen las reglas de siempre (como mucho
500 caracteres, uno required nunca se vacía, un valor que contiene otro de tus secretos se rechaza). Solo una acción
que corrió la persona llena un ajuste: la respuesta de settingsStatus nunca se lee para setSettings.
node sdk/run.mjs . action <clave> muestra ese valor con asteriscos. Un proveedor de sincronización que solo necesita
una llave aleatoria no necesita esto: con sync.generateKey Kino la crea.
Vincular: "¿Eres tú?" (action.link, Kino 0.9.74)¶
Úsalo cuando una acción encuentra a quién vincular y la persona tiene que decir que es ella: por
ejemplo un proveedor de sincronización cuyo bot lee el último mensaje ("escríbele
algo a tu bot") y encuentra a @ana. Tu plugin nunca vincula por su cuenta: responde un candidato, y
Kino pregunta.
export async function action(key) {
if (key === "findMe") {
const who = await bot.latestSender(); // null mientras nadie haya escrito
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") { // solo corre después de que la persona confirma
const chat = kino.storage.get("pending");
return { message: "Vinculado", setSettings: { chatId: String(chat) } };
}
}
- Kino muestra su propia pregunta, "¿Eres tú, @ana?" / "Is this you, @ana?", y nombra ahí a tu
plugin por el
namede tu manifiesto. Tiene "Sí, soy yo" y Cancelar (Cancelar enfocado). No puedes cambiar sus palabras. - Cancelar no corre nada: tu plugin no se llama ni se entera. Solo "Sí, soy yo" corre la acción
confirm, una sola vez, como si se oprimiera ese botón (los mismos ajustes, los mismos 30 s). Si no puede empezar en ese momento (otra acción o un guardado está corriendo, o los cambios sin guardar de la persona no se pueden guardar), la pregunta sigue abierta y lo dice. candidate: un texto de 1 a 64 caracteres sin los espacios de los extremos, con los espacios seguidos juntados en uno. No puede llevar caracteres de control ni de formato invisible, ningún espacio que no sea el normal, ni los rellenos que no dibujan nada (U+115F, U+1160, U+3164, U+FFA0, U+2800). Pasa por el mismo tapado de secretos que tus líneas de estado y se muestra como texto plano.confirm: lakeyde otro ajusteactionde tu plugin (no el que está respondiendo) que no tenga su propia preguntaconfirm: una acción que pregunta "¿Borrar todo?" nunca puede presentarse como "¿Eres tú?".- Cualquier otra cosa rechaza el vínculo: tu
messagese muestra igual, con el error genérico de Kino ("No se pudo completar. Inténtalo de nuevo.") debajo. - Un
messageen la misma respuesta también se muestra. Unlinken la respuesta de la propia acciónconfirmse ignora (no hay cadenas). Una pregunta a la vez: un vínculo nuevo reemplaza al que esperaba, y salir del formulario lo descarta. - Un Kino anterior ignora
link(es aditivo, sinapiVersionnueva): di también enmessage(o en una línea de estado) qué hacer. - Una acción que solo sirve de
confirmse puede ocultar con"linkOnly": true: la persona ve entonces un solo botón, y solo la pregunta de Kino corre la acción de confirmar.
Validar antes de guardar (validateSettings)¶
validateSettings(values) (opcional, 20 s) corre antes de que Kino guarde. values trae solo los
ajustes con valor: textos sin espacios en los extremos, toggles como booleanos, listas como arreglos de
objetos.
- Devuelve
nullpara aceptar. { password: "La contraseña no es correcta" }para rechazar con ese texto debajo del campo (máximo 200 caracteres), o un texto para rechazar con un mensaje general. Una clave que no es uno de tus ajustes con valor también rechaza, y su texto se muestra como mensaje general.- Con un rechazo no se guarda nada y la persona conserva lo que escribió.
- Si lanza un error, se pasa del tiempo o responde algo que Kino no puede leer (un arreglo, un número…), tampoco se guarda nada, y el formulario ofrece "Guardar sin comprobar"; ese botón solo aparece entonces, nunca después de un rechazo con mensajes.
Reglas comunes¶
- Los textos que devuelves se muestran después de que Kino les quita cualquiera de tus secretos guardados.
- Estos tres exports corren aunque un ajuste
requiredsiga vacío, así una línea de estado puede decir qué falta. - Guardar cualquier ajuste cierra tu sandbox, como siempre;
kino.storagesobrevive. - Si declaras
telemetry, una falla desettingsStatus,actionovalidateSettingsse reporta como la de cualquier otra función (Registro y telemetría).
Pruébalos con el kit (imprime lo que la app conservaría): node sdk/run.mjs . settingsStatus,
node sdk/run.mjs . action logout, node sdk/run.mjs . validateSettings '{"email":"ana@x.co"}' (o node sdk/validate.mjs . --run … con
los mismos argumentos, que además dice lo que muestra Kino y marca una llamada que Kino nunca hace; --raw
imprime tu respuesta sin tocar). El kit no aplica el tapado de secretos de la app, y validateSettings
recibe exactamente el JSON que escribes: la app solo envía los ajustes con valor, sin espacios en los
extremos. Un ejemplo que funciona es plugins/sdk/test/settings-demo en el repositorio de Kino.
Un ejemplo completo¶
Una cuenta opcional, una línea de estado, un botón "Cerrar sesión", una elección de calidad, un
interruptor y una lista de espejos propios de la persona, todo leído como lo declara
kino.d.ts:
{
"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" })),
};
}
Lo que recibe la persona: una pestaña "Mi cuenta" en Ajustes con dos títulos; "Estado" dice "Sin cuenta: ves el catálogo gratis" hasta que escriba una cuenta; Guardar revisa la cuenta antes de guardarla; "Cerrar sesión" pregunta primero y después vacía el correo y la contraseña en todos sus aparatos; cada espejo aparece como una copia más en el menú Servidor del reproductor.
Un valor que se queda en este aparato ("sync": false, apiVersion 13, Kino 0.9.74)¶
Un password puede decir "sync": false para quedarse en el aparato donde la
persona lo escribió: úsalo para un valor que solo tiene sentido una vez, en un aparato, como una contraseña de
verificación en dos pasos que tu plugin manda enseguida y después borra (clearSettings). Sin eso una contraseña llega a
los aparatos emparejados de la persona, sellada de punta a punta, como cualquier otra contraseña (abajo).
{ "key": "tg_password", "label": "Contraseña de verificación", "type": "password", "sync": false }
- El valor nunca se envía a un aparato emparejado, y un valor que manda otro aparato nunca lo pone ni lo borra.
- No va en ninguna copia de seguridad ni en ningún kit.
- El
sync.provisionde un proveedor de sincronización sí puede nombrarlo, para un secreto de un solo uso que va una vez a un aparato nuevo (un TV que no debería escribir una contraseña de dos pasos): mira Proveedores de sincronización. Nunca puede ser elsync.keySecret("The \"keySecret\" of the \"sync\" field can't name a setting with \"sync\": false"). - Tu plugin lo lee con
kino.config.gety lo borra como cualquier contraseña. - Un
texttambién puede decir"sync": false, para un valor que tiene que quedarse en el aparato pero no es un secreto que esconder, como un número de teléfono que la persona escribe para iniciar sesión en ese aparato: se dibuja como un campo de texto normal (sin asteriscos) y se guarda igual que una contraseña que se queda en el aparato (nunca se sincroniza, nunca va en una copia de seguridad ni en un kit). No puede ir ensync.provision("The \"provision\" of the \"sync\" field can't name a text setting with \"sync\": false"). syncen cualquier otro tipo rechaza el manifiesto ("Only a setting of type password or text has \"sync\" (\"key\")"), y también un valor que no seatrueofalse. Por debajo de apiVersion 13, y en un Kino que no lo tiene, la clave se ignora y la contraseña se sincroniza como siempre.node sdk/validate.mjsrevisa todo esto como la app.
En los otros aparatos de la persona¶
Cuando la persona empareja dos de sus aparatos (celular y TV), Kino mantiene sus plugins al día entre ellos. Lo que pasa y lo que no:
- Pasa: la instalación, las actualizaciones, encendido/apagado, la desinstalación y las aprobaciones de hosts. Cada aparato descarga tu código él mismo; solo viajan la dirección y la aprobación. El otro aparato instala en silencio cuando lo que descargó no pide nada más de lo que la persona aprobó en el primero; si ahora pides más (un host, permiso o capacidad nueva), espera en "Plugins de tus otros aparatos" con la hoja de consentimiento normal.
- Pasa: los valores de los ajustes
text,select,toggle,urlylist(unalistque tiene un campopasswordno viaja), y los ajustespassword(salvo unpasswordo untextcon"sync": false, apiVersion 13), sellados de punta a punta con la llave que los aparatos acordaron al emparejarse, nunca legibles en el camino. - Pasa: los vaciados. Un campo que la persona vacía, o el
clearSettingsde una acción, también se vacía en sus otros aparatos (contraseñas incluidas). Un ajusterequirednunca se vacía a distancia. Un aparato con una versión de Kino más vieja ignora los vaciados y conserva su valor. - Nunca pasa:
kino.storage, las cookies, las filas de Inicio guardadas. - Un proveedor de sincronización además puede pasarle sus ajustes a otro aparato con "Enviar
configuración" (los que nombra su
sync.provision): mira Proveedores de sincronización.
Un valor que llega así se aplica sin tu validateSettings y, como cualquier cambio guardado, cierra
tu sandbox. Así que escribe el plugin como si un ajuste pudiera cambiar en cualquier momento: ponle a
cualquier sesión que guardes en kino.storage como clave la cuenta a la que pertenece, y nunca pongas
una identidad del aparato en un ajuste, porque se copiaría al otro aparato.
const sessionKey = `session:${kino.config.get("email") ?? ""}`; // no solo "session"
Un plugin firmado instalado desde dos repositorios distintos en dos aparatos cuenta como el
mismo plugin cuando tiene el mismo id y la misma llave de autor: mira
El mismo plugin en dos direcciones.