A browser window the person drives (visualBrowser, apiVersion 20)¶
The hidden browser is hidden: nobody sees it and nobody can type in it. Some things only the person can do on a
web page: sign in, solve a challenge, accept a site's terms, pick something. With "apiVersion": 20 and
"visualBrowser": true your plugin may open a window the person sees and uses, kino.visualBrowser.open, and get back
what the page left behind (cookies, the page's HTML, its last address), or have Kino write the cookies straight into one of
your password settings.
Available from Kino 0.9.81
apiVersion 20 ships with Kino 0.9.81. The window works on an Android phone and tablet, and,
experimental, on Android TV. It does not exist on the desktop app or on a device without a WebView.
The manifest¶
{
"apiVersion": 20,
"visualBrowser": true,
"hosts": ["accounts.google.com", "music.youtube.com"],
"settings": [{ "key": "cookieHeader", "label": "Cookies", "type": "password" }]
}
visualBrowser is true or false (default false); it is ignored below apiVersion 20 and any other value is refused with
The "visualBrowser" field must be true or false. It is not a capability: nothing is approved at install except a plain
consent line («Puede abrir una ventana web donde inicias sesión o terminas un paso en sus sitios»), because Kino asks the person
in its own sheet at every open.
A plugin that keeps an older apiVersion (so every Kino still installs it) can offer the window only to a Kino that has it, with
an enhancement: "enhancements": { "20": { "visualBrowser": true } }. Either way, check
kino.visualBrowser?.available before using it.
kino.visualBrowser.open(options)¶
if (kino.visualBrowser?.available) { // undefined on a Kino without it; false on the desktop and on a device without a WebView
const r = await kino.visualBrowser.open({
url: "https://accounts.google.com/ServiceLogin?continue=https%3A%2F%2Fmusic.youtube.com",
title: "YouTube Music", // after your plugin's name in Kino's bar
doneWhen: { cookies: ["SAPISID"] }, // optional: the window closes by itself when the page holds them
// also: doneWhen: { localStorage: ["token"] } and collect: { localStorage: ["token"] } (the site's own saved data)
collect: { cookies: ["SID", "HSID", "SAPISID"], storeAs: { setting: "cookieHeader", format: "header" } },
userAgent: "browser", // or your own string
timeoutMs: 600000, // at most 10 minutes
});
// r = { status: "done" | "closed" | "timeout", finalUrl?, cookies?, localStorage?, html?, stored?, storedNames?, userAgent? }
}
kino.visualBrowser is undefined without the manifest key or on a Kino before 0.9.81; kino.visualBrowser.available is false
on the desktop and on a device without a WebView.
What the person sees¶
Kino's own sheet every time, in Kino's words (never yours): "<your plugin> wants to open a web window", the sites (your
manifest hosts), the cookie names and the localStorage keys you asked for, whether the window identifies itself as a regular browser or with a custom
string, and, with storeAs, that Kino keeps the cookies and you do not see them. Only after Continuar does the window open, with
Kino's bar (your plugin's name, your title, the host with a lock, Cerrar, and Listo when you gave no doneWhen) that you cannot
change. Saying No, Cerrar and Back all give you { status: "closed" }.
The rules¶
- Only from the person's own press: a settings
action, apanelActionor ascreenEventthat follows the person's tap or submit (the same gate as the QR scanner). From anything else (a search, Home, a timer, a job, a screen's open or load-more, a background call) the call throwsforbidden. - Your hosts only. The first
urland every page the window moves to must be https on the default port on a host of your manifesthosts(wildcards as there). Anything else is stopped and Kino says so; the local network is never reachable. A sign-in that goes throughaccounts.google.comneeds it declared. - Cookies.
collect.cookiesnames (at most 32) are read from the hosts the window was on that you declare, HttpOnly ones included, at most 64 cookies and 16,384 characters of names and values together; they come back withdoneonly.collect.htmlis the page's DOM (at most 2,000,000 characters),collect.finalUrlits last address. - localStorage. Many sites keep the session token in the page's
localStorage, not in a cookie.collect.localStoragenames keys (at most 32, each 1 to 256 characters, no control character); Kino reads only those keys from the page the window ends on (which must be on one of your hosts), never the whole store, and only withdone. The answer'slocalStorageis{ key: value }for the keys that exist (a key the page does not have is absent, nevernull), at most 65,536 characters of keys and values together (what does not fit is left out, never cut in half). Kino's sheet lists the keys next to the cookie names.storeAskeeps to the cookies: localStorage values come back to your script, so keep them inkino.storageor apasswordsetting you write yourself, and never log them. This is additive within apiVersion 20 (Kino 0.9.87, provisional): an older Kino ignores the options and answers nolocalStorage, so check for the key in the answer before relying on it. storeAs: Kino writes the cookies itself into yourpasswordsettingsetting(declared in the manifest) asname=value; name2=value2("header") or a JSON object ("json"), after your call has ended (saving a setting restarts your runtime); your script getsstoredandstoredNames(the names, never a value). Apasswordsetting holds 500 characters: a longer text answersstore_failedand nothing is stored. Sealed secrets keep their rule: they only travel to your declared hosts.storeAs.spill(optional, for a cookie list longer than 500 characters; YouTube Music's needs about 850): an array of 1 to 3 morepasswordsettings of yours (declared, distinct, none equal tosetting; elsebad_args). Kino cuts the formatted text at the setting limit (500 characters) and the pieces are the settings' values in order:settingfirst, then eachspillone; a setting the text does not reach is emptied, but only if it holds a value now. All of them are saved in one save (sync records one change), all or nothing: if(1 + spill.length) x 500cannot hold the text the answer isstore_failedand nothing is stored. Your script still never sees a value. To read it back, concatenate the settings' values in that order, with no separator (with"header"a cut may fall inside a cookie, so never split or trim a piece):[kino.config.cookieA, kino.config.cookieB, kino.config.cookieC, kino.config.cookieD].join("").storeAs.thenEvent(optional): a screen that opened the window cannot see the new account in the same call, because the write happens after the call ends. Name ascreenEventand Kino sends it to your open screen once the setting was written successfully, witharg={ stored: ["SID", ...] }(cookie names only) and novalue; handle it by reloading your data. The name follows the event-name rules (1 to 128 ofA-Z a-z 0-9 . _ ~ -, neveropen; elsebad_args). It is sent only when the call came from a screen'sscreenEvent(from a settings action or apanelActionthe option is accepted and nothing is sent), never after a failed write or a window that was notdone, dropped silently if your screen is closed by then or its event queue is full, at most once per call. It is a follow-up, not a press: its answer'sgo.url,go.copy,go.titleByIds,go.installPlugin,shareandenableJobare dropped;state,configand a toast work, with the normal event time budget.- A clean jar. The window starts with the cookies of your hosts expired and expires them again when it closes (Android has
one cookie jar for the app, so a cookie scoped to a path other than
/survives; it is not yourkino.fetchjar). - Nothing else. No script of yours in the page, no keystroke exposed, no pop-ups, downloads, file chooser, camera,
microphone, location or prompts. One window at a time in the whole app (
busy), at most 10 minutes (timeoutMs, brought down to 600,000 or up to 5,000), closed when the app is left in the background for a minute or the screen goes. - The window's time is its own
timeoutMs. While the window is up, the time bound of the call that opened it (a settings action's, apanelAction's, ascreenEvent's) does not run, so a Google sign-in with 2-step verification can take as long as the person needs, up totimeoutMs. When the window closes your call has at least 10 seconds left to run the code afteropenresolves; a hang after that is stopped as usual. doneWhencloses the window by itself:cookies(every named cookie exists),localStorage(every named key exists in the page's localStorage, checked about every 0.7 s) and/orurlMatches(the address matches the pattern, where*is any run of characters and the rest is literal; at most 200 characters). Any one of them is enough.userAgent:"browser"is the phone's Chrome string, kept up to date by Kino; or your own, 1 to 300 printable ASCII characters, so a site that changes what it accepts is fixed by a plugin update. Either way the WebView marker (; wv) is removed andX-Requested-Withis not sent (on a WebView that lets Kino remove it). Absent: the WebView's own.
Errors, as e.code: bad_args (the options are wrong), forbidden, unavailable (no WebView on the device, or the desktop),
busy and store_failed.
On a TV (experimental)¶
The window also opens on Android TV, driven by the remote: the D-pad moves between the page's links and fields, OK on a text
field opens the TV keyboard, Back goes back in the page and then closes, and Kino's bar (Cerrar, and Listo when you gave no
doneWhen) is reachable with Up from the page (or the Menu key) and Down from the bar. Kino's sheet is the same, larger and
focusable. Limits: a site whose controls only answer to a pointer (hover menus, canvas widgets, drag handles) may be hard or
impossible to reach, and a TV box without a WebView answers available === false. Keep the paste-the-cookies setting as the
fallback, and remember that the cookies you store travel to the person's other devices with sync, so linking on a phone also
covers the TV.
Recipe: link an account ("Vincular cuenta")¶
A YouTube Music style login: the plugin keeps its cookies in one password setting and offers a button that fills it.
"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 saves the header once this call returns
}
The full YouTube Music cookie list is longer than one password setting (about 850 characters), so the plugin declares four
(cookieA to cookieD) and lets Kino spill the text over them:
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",
});
// Later, in any call: the pieces are the settings' values in order, joined with NO separator.
const cookieHeader = [kino.config.cookieA, kino.config.cookieB, kino.config.cookieC, kino.config.cookieD].join("");
The same from a screen (a button of your tree whose screenEvent opens the window); thenEvent tells the screen when the
cookies are stored, so it can reload with the new account:
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 wrote the cookies after the call above ended; arg.stored lists their names. Now kino.config sees the new account.
return { state: { account: await loadAccount() }, toast: "Cuenta vinculada" };
}
}
The honest caveat: Google may refuse to sign in inside an embedded window whatever its user agent says, and it can change that
without notice. Keep the paste-the-cookies setting as the fallback, and send userAgent as your own string if a newer one works
better (you can ship that in a plugin update, with no Kino release).
Recipe: a token that lives in 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", // a host of your manifest
title: "Mi servicio",
doneWhen: { localStorage: ["access_token"] }, // closes by itself when the page has saved the key
collect: { localStorage: ["access_token", "refresh_token"] }, // only these keys come back
timeoutMs: 300000,
});
if (r.status !== "done") return { message: "No se vinculó la cuenta" };
const ls = r.localStorage;
// An older Kino ignores the option and answers no `localStorage`: say so instead of failing later.
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 opens the window, the person signs in, and as soon as the page has saved access_token the window closes and you get the
values of the keys you named, nothing else of the site's storage.
Testing it¶
The Node kit has no window: node sdk/validate.mjs checks the manifest key, the options and the consent line, and prints a note;
kino.visualBrowser.open answers unavailable in run.mjs unless a test of your own passes createKino a visualBrowser
option (it plays the person: answer { status: "done", localStorage: { token: "…" } } to test your collect.localStorage code). Test the real window on a phone or a TV, and keep another way in (pasting the cookies into a
password setting). More: Test it locally.