Una ventana de navegador que la persona maneja (visualBrowser, apiVersion 20)¶
El navegador oculto está oculto: nadie lo ve y nadie puede escribir en él. Hay cosas que solo la persona puede hacer
en una página web: iniciar sesión, resolver una verificación, aceptar los términos de un sitio, elegir algo. Con
"apiVersion": 20 y "visualBrowser": true tu plugin puede abrir una ventana que la persona ve y usa,
kino.visualBrowser.open, y recibir lo que la página dejó (cookies, el HTML de la página, su última dirección), o pedirle a Kino
que escriba las cookies directo en uno de tus ajustes password.
Disponible desde Kino 0.9.81
apiVersion 20 llega con Kino 0.9.81. La ventana funciona en teléfono y tableta Android y,
de forma experimental, en Android TV. No existe en la app de escritorio ni en un aparato sin WebView.
El manifest¶
{
"apiVersion": 20,
"visualBrowser": true,
"hosts": ["accounts.google.com", "music.youtube.com"],
"settings": [{ "key": "cookieHeader", "label": "Cookies", "type": "password" }]
}
visualBrowser es true o false (por defecto false); por debajo de apiVersion 20 se ignora y cualquier otro valor se
rechaza con The "visualBrowser" field must be true or false. No es una capability: en la instalación solo se aprueba una línea
de consentimiento sencilla («Puede abrir una ventana web donde inicias sesión o terminas un paso en sus sitios»), porque Kino le
pregunta a la persona en su propia hoja en cada apertura.
Un plugin que conserva un apiVersion más bajo (para que todo Kino lo siga instalando) puede ofrecer la ventana solo a un Kino que
la tenga, con un enhancement: "enhancements": { "20": { "visualBrowser": true } }. En ambos casos, revisa
kino.visualBrowser?.available antes de usarla.
kino.visualBrowser.open(options)¶
if (kino.visualBrowser?.available) { // undefined en un Kino sin ella; false en el escritorio y en un aparato sin WebView
const r = await kino.visualBrowser.open({
url: "https://accounts.google.com/ServiceLogin?continue=https%3A%2F%2Fmusic.youtube.com",
title: "YouTube Music", // después del nombre de tu plugin en la barra de Kino
doneWhen: { cookies: ["SAPISID"] }, // opcional: la ventana se cierra sola cuando la página las tiene
// también: doneWhen: { localStorage: ["token"] } y collect: { localStorage: ["token"] } (los datos que el sitio guarda)
collect: { cookies: ["SID", "HSID", "SAPISID"], storeAs: { setting: "cookieHeader", format: "header" } },
userAgent: "browser", // o tu propio texto
timeoutMs: 600000, // 10 minutos como máximo
});
// r = { status: "done" | "closed" | "timeout", finalUrl?, cookies?, localStorage?, html?, stored?, storedNames?, userAgent? }
}
kino.visualBrowser es undefined sin la clave del manifest o en un Kino anterior a 0.9.81; kino.visualBrowser.available es
false en el escritorio y en un aparato sin WebView.
Lo que ve la persona¶
La hoja propia de Kino cada vez, con las palabras de Kino (nunca las tuyas): «<tu plugin> quiere abrir una ventana web»,
los sitios (los hosts de tu manifest), los nombres de las cookies y las claves de localStorage que pediste, si la ventana se presenta como un navegador
normal o con un texto propio y, con storeAs, que Kino guarda las cookies y tú no las ves. Solo después de Continuar se abre la
ventana, con la barra de Kino (el nombre de tu plugin, tu title, el host con un candado, Cerrar y, si no diste doneWhen, Listo)
que no puedes cambiar. Decir que No, Cerrar y Atrás te dan { status: "closed" }.
Las reglas¶
- Solo desde un toque de la persona: una
actionde ajustes, unapanelActiono unscreenEventque sigue a un toque o a un envío de la persona (la misma puerta que el escáner QR). Desde cualquier otra cosa (una búsqueda, el Home, un temporizador, un trabajo, la apertura o el "cargar más" de una pantalla, una llamada en segundo plano) la llamada lanzaforbidden. - Solo tus hosts. La primera
urly cada página a la que pase la ventana deben ser https en el puerto por defecto y de un host de loshostsde tu manifest (con comodines como allí). Cualquier otra se detiene y Kino lo dice; la red local nunca es alcanzable. Un inicio de sesión que pasa poraccounts.google.comnecesita declararlo. - Cookies. Los nombres de
collect.cookies(32 como máximo) se leen de los hosts por los que pasó la ventana y que tú declaras, también las HttpOnly, con 64 cookies como máximo y 16.384 caracteres entre nombres y valores; llegan solo condone.collect.htmles el DOM de la página (2.000.000 de caracteres como máximo) ycollect.finalUrlsu última dirección. - localStorage. Muchos sitios guardan el token de sesión en el
localStoragede la página y no en una cookie.collect.localStoragenombra claves (hasta 32, de 1 a 256 caracteres, sin caracteres de control); Kino lee solo esas claves de la página donde termina la ventana (que debe estar en uno de tus hosts), nunca todo el almacén, y solo condone. EllocalStoragede la respuesta es{ clave: valor }con las claves que existen (una clave que la página no tiene no aparece, nunca esnull), con un máximo de 65.536 caracteres de claves y valores juntos (lo que no cabe se deja fuera, sin cortarlo por la mitad). La hoja de Kino lista las claves junto a los nombres de las cookies.storeAssolo cubre las cookies: los valores delocalStoragevuelven a tu script, así que guárdalos enkino.storageo en un ajustepasswordque escribas tú, y nunca los registres. Es aditivo dentro de apiVersion 20 (Kino 0.9.87, provisional): un Kino anterior ignora las opciones y responde sinlocalStorage, así que comprueba que la clave venga en la respuesta antes de fiarte de ella. storeAs: Kino mismo escribe las cookies en tu ajustepasswordsetting(declarado en el manifest) comoname=value; name2=value2("header") o un objeto JSON ("json"), cuando tu llamada ya terminó (guardar un ajuste reinicia tu runtime); tu script recibestoredystoredNames(los nombres, nunca un valor). Un ajustepasswordadmite 500 caracteres: un texto más largo respondestore_failedy no se guarda nada. Los secretos sellados mantienen su regla: solo viajan a tus hosts declarados.storeAs.spill(opcional, para una lista de cookies de más de 500 caracteres; la de YouTube Music necesita unos 850): una lista de 1 a 3 ajustespasswordtuyos más (declarados, distintos, ninguno igual asetting; si no,bad_args). Kino corta el texto con formato en el límite del ajuste (500 caracteres) y los trozos son los valores de los ajustes en orden: primerosetting, luego cada uno despill; un ajuste al que el texto no llega se vacía, pero solo si ahora tiene un valor. Todos se guardan en un solo guardado (la sincronización registra un cambio), todo o nada: si(1 + spill.length) x 500no alcanza para el texto, la respuesta esstore_failedy no se guarda nada. Tu script sigue sin ver nunca un valor. Para leerlo de vuelta, concatena los valores de los ajustes en ese orden, sin separador (con"header"un corte puede caer dentro de una cookie, así que nunca partas ni recortes un trozo):[kino.config.cookieA, kino.config.cookieB, kino.config.cookieC, kino.config.cookieD].join("").storeAs.thenEvent(opcional): una pantalla que abrió la ventana no puede ver la cuenta nueva en la misma llamada, porque la escritura ocurre cuando la llamada ya terminó. Nombra unscreenEventy Kino se lo envía a tu pantalla abierta cuando el ajuste ya se escribió con éxito, conarg={ stored: ["SID", ...] }(solo nombres de cookies) y sinvalue; atiéndelo recargando tus datos. El nombre sigue las reglas de nombres de evento (de 1 a 128 caracteres deA-Z a-z 0-9 . _ ~ -, nuncaopen; si no,bad_args). Se envía solo cuando la llamada vino delscreenEventde una pantalla (desde una acción de ajustes o unapanelActionla opción se acepta y no se envía nada), nunca tras una escritura fallida o una ventana que no terminó endone, se descarta en silencio si tu pantalla ya se cerró o su cola de eventos está llena, y como máximo una vez por llamada. Es un seguimiento, no un toque: de su respuesta se descartango.url,go.copy,go.titleByIds,go.installPlugin,shareyenableJob;state,configy un toast funcionan, con el presupuesto de tiempo normal de un evento.- Un almacén limpio. La ventana empieza con las cookies de tus hosts vencidas y las vuelve a vencer al cerrarse (Android tiene un
solo almacén de cookies para la app, así que una cookie de una ruta distinta de
/sobrevive; no es el de tukino.fetch). - Nada más. Ningún script tuyo en la página, ninguna tecla expuesta, sin ventanas emergentes, descargas, selector de archivos,
cámara, micrófono, ubicación ni avisos. Una sola ventana a la vez en toda la app (
busy), 10 minutos como máximo (timeoutMs, que se baja a 600.000 o se sube a 5.000), y se cierra cuando la app queda un minuto en segundo plano o se apaga la pantalla. - El tiempo de la ventana es su propio
timeoutMs. Mientras la ventana está abierta, el límite de tiempo de la llamada que la abrió (el de una acción de ajustes, unapanelActiono unscreenEvent) no corre, así que un inicio de sesión de Google con verificación en dos pasos puede tardar lo que la persona necesite, hastatimeoutMs. Cuando la ventana se cierra, tu llamada tiene al menos 10 segundos para ejecutar el código posterior aopen; si se cuelga después de eso, se detiene como siempre. doneWhencierra la ventana solo:cookies(existen todas las cookies nombradas),localStorage(existen todas las claves nombradas en ellocalStoragede la página, comprobado más o menos cada 0,7 s) y/ourlMatches(la dirección coincide con el patrón, donde*es cualquier tramo de caracteres y el resto es literal; 200 caracteres como máximo). Basta con una.userAgent:"browser"es el texto del Chrome del teléfono, que Kino mantiene al día; o el tuyo, de 1 a 300 caracteres ASCII imprimibles, para que un sitio que cambia lo que acepta se arregle con una actualización del plugin. De cualquier forma se quita la marca del WebView (; wv) y no se envíaX-Requested-With(en un WebView que deja a Kino quitarlo). Sin él: el del WebView.
Errores, en e.code: bad_args (las opciones están mal), forbidden, unavailable (el aparato no tiene WebView, o es el
escritorio), busy y store_failed.
En un TV (experimental)¶
La ventana también se abre en Android TV, manejada con el control remoto: el D-pad se mueve entre los enlaces y campos de la página,
OK sobre un campo de texto abre el teclado del TV, Atrás retrocede en la página y luego cierra, y la barra de Kino (Cerrar y, si no
diste doneWhen, Listo) se alcanza con Arriba desde la página (o con la tecla Menú) y Abajo desde la barra. La hoja de Kino es la
misma, más grande y con foco. Límites: un sitio cuyos controles solo responden a un puntero (menús al pasar el cursor, widgets de
canvas, asas de arrastre) puede ser difícil o imposible de alcanzar, y un TV box sin WebView responde available === false. Deja
el ajuste de pegar las cookies como alternativa, y recuerda que las cookies que guardas viajan a los otros aparatos de la persona con
la sincronización, así que vincular en el teléfono también cubre el TV.
Receta: vincular una cuenta ("Vincular cuenta")¶
Un inicio de sesión al estilo de YouTube Music: el plugin guarda sus cookies en un ajuste password y ofrece un botón que lo llena.
"settings": [
{ "key": "link", "label": "Vincular cuenta", "labelEn": "Link account", "type": "action" },
{ "key": "cookieHeader", "label": "Cookies (pegarlas a mano si no puedes vincular)", "type": "password" }
]
async function action(key) {
if (key !== "link") return;
if (!kino.visualBrowser?.available) return { message: "Pega las cookies en el campo de abajo" };
const r = await kino.visualBrowser.open({
url: "https://accounts.google.com/ServiceLogin?continue=https%3A%2F%2Fmusic.youtube.com",
title: "YouTube Music",
doneWhen: { cookies: ["SAPISID"] },
collect: { cookies: ["SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-3PSID"], storeAs: { setting: "cookieHeader", format: "header" } },
userAgent: "browser",
});
if (r.status !== "done" || !r.stored) return { message: "No se vinculó la cuenta" };
return { message: "Cuenta vinculada" }; // Kino guarda el header cuando esta llamada termina
}
La lista completa de cookies de YouTube Music es más larga que un ajuste password (unos 850 caracteres), así que el plugin
declara cuatro (cookieA a cookieD) y deja que Kino reparta el texto entre ellos:
const r = await kino.visualBrowser.open({
url: "https://accounts.google.com/ServiceLogin?continue=https%3A%2F%2Fmusic.youtube.com",
title: "YouTube Music",
doneWhen: { cookies: ["SAPISID"] },
collect: {
cookies: ["SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-3PSID", "__Secure-3PAPISID", "__Secure-3PSIDTS", "LOGIN_INFO", "VISITOR_INFO1_LIVE", "YSC"],
storeAs: { setting: "cookieA", spill: ["cookieB", "cookieC", "cookieD"], format: "header", thenEvent: "account_linked" },
},
userAgent: "browser",
});
// Después, en cualquier llamada: los trozos son los valores de los ajustes en orden, unidos SIN separador.
const cookieHeader = [kino.config.cookieA, kino.config.cookieB, kino.config.cookieC, kino.config.cookieD].join("");
Lo mismo desde una pantalla (un botón de tu árbol cuyo screenEvent abre la ventana); thenEvent le avisa a la pantalla
cuando las cookies ya están guardadas, para que se recargue con la cuenta nueva:
async function screenEvent({ name, arg, state }) {
if (name === "link") {
const r = await kino.visualBrowser.open({
url: "https://accounts.google.com/ServiceLogin?continue=https%3A%2F%2Fmusic.youtube.com",
doneWhen: { cookies: ["SAPISID"] },
collect: { cookies: ["SID", "HSID", "SAPISID"], storeAs: { setting: "cookieHeader", format: "header", thenEvent: "account_linked" } },
userAgent: "browser",
});
return r.stored ? { toast: "Vinculando..." } : { toast: "No se vinculó la cuenta" };
}
if (name === "account_linked") {
// Kino escribió las cookies después de que terminó la llamada de arriba; arg.stored lista sus nombres. Ahora kino.config ve la cuenta nueva.
return { state: { account: await loadAccount() }, toast: "Cuenta vinculada" };
}
}
La advertencia honesta: Google puede negarse a iniciar sesión dentro de una ventana embebida diga lo que diga su user agent, y puede
cambiarlo sin avisar. Deja el ajuste de pegar las cookies como alternativa y envía userAgent con tu propio texto si uno más nuevo
funciona mejor (lo puedes publicar en una actualización del plugin, sin esperar un Kino nuevo).
Receta: un token que vive en localStorage¶
export async function action(key) {
if (key !== "link") return null;
if (!kino.visualBrowser?.available) return { message: "Este aparato no puede abrir la ventana de inicio de sesión" };
const r = await kino.visualBrowser.open({
url: "https://auth.miservicio.com/login", // un host de tu manifest
title: "Mi servicio",
doneWhen: { localStorage: ["access_token"] }, // se cierra sola cuando la página guardó la clave
collect: { localStorage: ["access_token", "refresh_token"] }, // solo vuelven estas claves
timeoutMs: 300000,
});
if (r.status !== "done") return { message: "No se vinculó la cuenta" };
const ls = r.localStorage;
// Un Kino anterior ignora la opción y responde sin `localStorage`: dilo en vez de fallar más tarde.
if (!ls) return { message: "Este Kino no puede leer el almacenamiento del sitio. Actualízalo." };
if (!ls.access_token) return { message: "El sitio no guardó el token" };
await kino.storage.set("auth", JSON.stringify({ access: ls.access_token, refresh: ls.refresh_token ?? null }));
return { message: "Cuenta vinculada" };
}
Kino abre la ventana, la persona inicia sesión y, en cuanto la página guarda access_token, la ventana se cierra y recibes los valores
de las claves que nombraste, nada más del almacenamiento del sitio.
Probarla¶
El kit de Node no tiene ventana: node sdk/validate.mjs revisa la clave del manifest, las opciones y la línea de consentimiento, e
imprime una nota; kino.visualBrowser.open responde unavailable en run.mjs a menos que una prueba tuya le pase a createKino una
opción visualBrowser (hace de la persona: responde { status: "done", localStorage: { token: "…" } } para probar tu código de collect.localStorage). Prueba la ventana real en un teléfono o un TV, y deja otra forma de entrar (pegar las
cookies en un ajuste password). Más en Probar en local.