# AppMint hybrid HTML API
Every native method and API a page inside a generated app can use, extracted from the template
runtime itself (`WebViewActivity.kt` and the scripts it injects), so this list is always exactly
what ships — each with a runnable example.
**Read the "Writing HTML for your app" guide first** — it covers feature detection, the async
callback convention, and the rules that a method list cannot express.
Total: **208 bridge methods** across 2 namespace(s), plus
261 helper, web-standard, Capacitor and appmintNative APIs — 469 of 469 with examples.
## `window.AndroidNFC`
### `startScan`
```js
window.AndroidNFC.startScan(): Boolean
```
*(Web NFC)* Legacy availability probe, present only when the creator enabled NFC. Real NFC work goes through the standard NDEFReader polyfill (window.WebToApk.__nfc*), which is what a page should use; this only reports whether the adapter is on.
**Example**
Tells you whether the phone's NFC is switched on. It lives on `window.AndroidNFC`, not on `window.WebToApk`, and it does not read a tag — reading is done with `NDEFReader`.
**Returns:** `true` (synchronously) when the phone has NFC and it is on; `false` when the phone has no NFC, or when NFC is off (then the app also shows a short "Please enable NFC" message). **Needs:** **Web NFC Support** turned on in Step 4 (Access) when you build; without it `window.AndroidNFC` does not exist.
Check before showing an NFC button:
```js
function nfcReady() {
if (!window.AndroidNFC || typeof window.AndroidNFC.startScan !== 'function') return false;
return window.AndroidNFC.startScan();
}
document.getElementById('scan-tag').addEventListener('click', async function () {
if (!nfcReady()) { showStatus('Turn on NFC in the phone settings, then try again.'); return; }
var reader = new NDEFReader();
reader.addEventListener('reading', function (e) { showStatus('Tag ' + e.serialNumber); });
await reader.scan();
showStatus('Hold a tag to the back of the phone.');
});
```
Check right before a write: with NFC switched off the write would wait for a tap that never comes, while `startScan()` answers at once and shows the app's "Please enable NFC" message:
```js
document.getElementById('write-pass').addEventListener('click', async function () {
if (!window.AndroidNFC || typeof window.AndroidNFC.startScan !== 'function') {
showStatus('NFC is not available in this app.');
return;
}
if (!window.AndroidNFC.startScan()) { showStatus('NFC is off, or this phone has no NFC.'); return; }
showStatus('Tap a tag to write it...');
try {
await new NDEFReader().write('Visitor pass #1042');
showStatus('Tag written.');
} catch (err) {
showStatus('Write failed: ' + err.message);
}
});
```
Re-check when the user comes back and taps "I've turned it on":
```js
var retry = document.getElementById('nfc-retry');
retry.addEventListener('click', function () {
if (!window.AndroidNFC || typeof window.AndroidNFC.startScan !== 'function') {
showStatus('NFC is not available in this app.');
return;
}
if (window.AndroidNFC.startScan()) {
retry.hidden = true;
document.getElementById('nfc-panel').hidden = false;
startReading(); // your own NDEFReader.scan() code
} else {
showStatus('NFC is still off, or this phone has no NFC.');
}
});
```
**Notes:** `window.AndroidNFC` exists from the first script on the page. After the user turns NFC on in settings and comes back, tag reading starts by itself.
## `window.WebToApk`
### `__badgeSupported`
```js
window.WebToApk.__badgeSupported(): Boolean
```
Whether this launcher can show a badge count (navigator.setAppBadge exists only then).
**Example**
Internal transport behind the presence of `navigator.setAppBadge`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `true` when this phone's launcher shows badge counts. **Needs:** nothing to switch on.
**Use the public API:**
```js
if ('setAppBadge' in navigator) navigator.setAppBadge(unreadCount);
```
Show the "badge on app icon" setting only on phones whose launcher can show a count:
```js
function renderBadgeSetting() {
const row = document.getElementById('badge-setting');
// setAppBadge exists only when this launcher shows counts
row.hidden = !('setAppBadge' in navigator);
}
renderBadgeSetting();
```
Clear the count when the user opens the inbox, on any launcher that has one:
```js
function openInbox() {
showInbox();
if ('clearAppBadge' in navigator) {
navigator.clearAppBadge().catch(function (e) {
console.warn('badge not cleared', e.name); // NotAllowedError
});
}
}
```
**Notes:** The Badging API is installed only where the launcher can show a count (Samsung, Huawei, Xiaomi, OPPO, Sony, …); on Pixel-style launchers it is absent, like in a browser without badging.
### `__clipboardRead`
```js
window.WebToApk.__clipboardRead(): String
```
navigator.clipboard.read(): `{parts:[{type, text|base64}]}`, or `{denied:true}` for a page that is not one of this app's own origins.
**Example**
Internal transport behind `navigator.clipboard.read()`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `{parts:[{type, text|base64}]}`, or `{denied:true}` on a page that is not one of the app's own origins. **Needs:** nothing to switch on.
**Use the public API:**
```js
canvas.toBlob(async (png) => {
await navigator.clipboard.write([new ClipboardItem({ 'image/png': png })]);
});
const [item] = await navigator.clipboard.read();
if (item && item.types.includes('image/png')) preview(await item.getType('image/png'));
```
Paste formatted text into an editor, keeping the formatting when the clipboard has HTML:
```js
async function pasteRich(editor) {
try {
var items = await navigator.clipboard.read();
if (!items.length) { showMessage('The clipboard is empty'); return; }
var item = items[0];
if (item.types.includes('text/html')) {
editor.insertHtml(sanitize(await (await item.getType('text/html')).text()));
} else if (item.types.includes('text/plain')) {
editor.insertText(await (await item.getType('text/plain')).text());
}
} catch (e) {
showMessage('Could not read the clipboard');
}
}
```
Paste any copied picture (PNG, JPEG, WebP…) as a profile photo, and tell a refused read apart:
```js
document.getElementById('paste-photo').onclick = async function () {
try {
var items = await navigator.clipboard.read();
var item = items[0];
var type = item && item.types.find(function (t) { return t.indexOf('image/') === 0; });
if (!type) { showMessage('Copy a picture first'); return; }
uploadAvatar(await item.getType(type)); // a Blob of that type
} catch (e) {
if (e.name === 'NotAllowedError') showMessage('This page cannot read the clipboard');
else showMessage('Could not paste the picture');
}
};
```
**Notes:** Android 12+ shows its own "pasted from your clipboard" message when an app reads the clipboard.
### `__clipboardWrite`
```js
window.WebToApk.__clipboardWrite(partsJson: String): Boolean
```
navigator.clipboard.write(): [partsJson] is `[{type, text}|{type, base64}]` for one ClipboardItem — text/plain, text/html, or an image that is copied as a content URI.
**Example**
Internal transport behind `navigator.clipboard.write([ClipboardItem])`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `true` when the clip was placed. **Needs:** nothing to switch on.
**Use the public API:**
```js
canvas.toBlob(async (png) => {
await navigator.clipboard.write([new ClipboardItem({ 'image/png': png })]);
});
const [item] = await navigator.clipboard.read();
if (item && item.types.includes('image/png')) preview(await item.getType('image/png'));
```
Copy formatted text and its plain version in one item, so rich editors get the table and plain fields get the text:
```js
async function copyTable(table) {
if (!(navigator.clipboard && navigator.clipboard.write && window.ClipboardItem)) return;
try {
await navigator.clipboard.write([new ClipboardItem({
'text/html': new Blob([table.outerHTML], { type: 'text/html' }),
'text/plain': new Blob([table.innerText], { type: 'text/plain' })
})]);
showMessage('Table copied');
} catch (e) {
showMessage('Could not copy (' + e.name + ')'); // NotAllowedError when the write fails
}
}
```
Copy an image the page shows, such as a QR code, so it can be pasted into a chat:
```js
async function copyImage(img) {
try {
var blob = await (await fetch(img.src)).blob(); // an image/* type, up to 16 MB
await navigator.clipboard.write([new ClipboardItem({ [blob.type]: blob })]);
showMessage('Image copied');
} catch (e) {
showMessage('Could not copy the image');
}
}
```
**Notes:** Text, HTML and one image per item. The image is copied as a content URI through the app's FileProvider, so it pastes into WhatsApp, Gmail or Keep.
### `__closeNotification`
```js
window.WebToApk.__closeNotification(tag: String): Boolean
```
Notification.close(): removes a notification the page posted, by its tag.
**Example**
Internal plumbing behind `Notification.prototype.close()` — pages use `new Notification(...)` and call `close()` on it. It removes a notification from the shade by its tag.
**Returns:** `true` when the remove request was made (also when nothing had that tag); `false` on an internal error. **Needs:** nothing.
**Use the public API:**
```js
let uploadNote = null;
function showUploading() {
if (!('Notification' in window) || Notification.permission !== 'granted') return;
uploadNote = new Notification('Uploading…', { body: 'Keep the app open', tag: 'upload', silent: true });
uploadNote.onclose = function () { uploadNote = null; };
}
function uploadFinished() {
if (uploadNote) uploadNote.close(); // removes it from the notification shade
}
```
Open the right chat when the notification is tapped, then remove it from the shade:
```js
function notifyNewMessage(msg) {
if (!('Notification' in window) || Notification.permission !== 'granted') return;
const n = new Notification(msg.from, {
body: msg.text,
tag: 'chat-' + msg.threadId, // one notification per chat
data: { threadId: msg.threadId }
});
n.onclick = function () {
openThread(n.data.threadId);
n.close();
};
}
```
Show a short confirmation that removes itself after five seconds:
```js
function confirmCopied() {
if (!('Notification' in window) || Notification.permission !== 'granted') return;
const n = new Notification('Link copied', { body: 'Paste it anywhere', tag: 'copied', silent: true });
setTimeout(function () { n.close(); }, 5000);
}
```
**Notes:** do not call `WebToApk.__closeNotification` directly; the `__` methods may change without notice. `close()` fires the notification's `close` event.
### `__dlAbort`
```js
window.WebToApk.__dlAbort(token: String)
```
Drops download [token] (the page's read failed or it gave up).
**Example**
Documented together with `WebToApk.__dlBegin` — the example there shows this one too.
Internal transport behind ``, Blob downloads, `window.open(blobUrl)` and `AppMint.saveBlob` / `AppMint.downloadFile`: the file is streamed from the page to the app in slices, so a large export is never one giant string in memory. Pages use the standard download code; never call these directly, because the `__` methods may change without notice.
**Returns:** `__dlBegin(name, type, size)` returns a token (or `""` when the phone has no room); `__dlChunk(token, base64)` returns `false` if a slice could not be written; `__dlEnd(token, action)` finishes (`save` = Downloads, `open` = show it, `share`, `copy`). **Needs:** nothing.
**Use the public API:**
```js
const blob = new Blob([csvText], { type: 'text/csv' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'Report.csv';
a.click(); // lands in Downloads as "Report.csv"
```
Export a drawing from a canvas through the same route:
```js
canvas.toBlob(function (blob) {
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'drawing.png';
a.click();
setTimeout(function () { URL.revokeObjectURL(a.href); }, 10000);
}, 'image/png');
```
Save a JSON backup the user can keep, with a message when it is done:
```js
function exportBackup(data) {
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'backup-' + new Date().toISOString().slice(0, 10) + '.json';
document.body.appendChild(a);
a.click();
a.remove();
showMessage('Backup saved to Downloads.');
}
```
**Notes:** Implemented in the app shell (ShellDownloads.kt).
### `__dlBegin`
```js
window.WebToApk.__dlBegin(name: String, type: String, size: Double): String
```
Opens a download of [size] bytes named [name] ([type] = its MIME type) that the page will stream with __dlChunk. Returns a token, or "" when there is no room.
**Example**
Internal transport behind ``, Blob downloads, `window.open(blobUrl)` and `AppMint.saveBlob` / `AppMint.downloadFile`: the file is streamed from the page to the app in slices, so a large export is never one giant string in memory. Pages use the standard download code; never call these directly, because the `__` methods may change without notice.
**Returns:** `__dlBegin(name, type, size)` returns a token (or `""` when the phone has no room); `__dlChunk(token, base64)` returns `false` if a slice could not be written; `__dlEnd(token, action)` finishes (`save` = Downloads, `open` = show it, `share`, `copy`). **Needs:** nothing.
**Use the public API:**
```js
const blob = new Blob([csvText], { type: 'text/csv' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'Report.csv';
a.click(); // lands in Downloads as "Report.csv"
```
Export a drawing from a canvas through the same route:
```js
canvas.toBlob(function (blob) {
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'drawing.png';
a.click();
setTimeout(function () { URL.revokeObjectURL(a.href); }, 10000);
}, 'image/png');
```
Save a JSON backup the user can keep, with a message when it is done:
```js
function exportBackup(data) {
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'backup-' + new Date().toISOString().slice(0, 10) + '.json';
document.body.appendChild(a);
a.click();
a.remove();
showMessage('Backup saved to Downloads.');
}
```
**Notes:** Implemented in the app shell (ShellDownloads.kt).
### `__dlChunk`
```js
window.WebToApk.__dlChunk(token: String, base64: String): Boolean
```
One base64 slice of the download [token]; false when the transfer failed.
**Example**
Documented together with `WebToApk.__dlBegin` — the example there shows this one too.
Internal transport behind ``, Blob downloads, `window.open(blobUrl)` and `AppMint.saveBlob` / `AppMint.downloadFile`: the file is streamed from the page to the app in slices, so a large export is never one giant string in memory. Pages use the standard download code; never call these directly, because the `__` methods may change without notice.
**Returns:** `__dlBegin(name, type, size)` returns a token (or `""` when the phone has no room); `__dlChunk(token, base64)` returns `false` if a slice could not be written; `__dlEnd(token, action)` finishes (`save` = Downloads, `open` = show it, `share`, `copy`). **Needs:** nothing.
**Use the public API:**
```js
const blob = new Blob([csvText], { type: 'text/csv' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'Report.csv';
a.click(); // lands in Downloads as "Report.csv"
```
Export a drawing from a canvas through the same route:
```js
canvas.toBlob(function (blob) {
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'drawing.png';
a.click();
setTimeout(function () { URL.revokeObjectURL(a.href); }, 10000);
}, 'image/png');
```
Save a JSON backup the user can keep, with a message when it is done:
```js
function exportBackup(data) {
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'backup-' + new Date().toISOString().slice(0, 10) + '.json';
document.body.appendChild(a);
a.click();
a.remove();
showMessage('Backup saved to Downloads.');
}
```
**Notes:** Implemented in the app shell (ShellDownloads.kt).
### `__dlEnd`
```js
window.WebToApk.__dlEnd(token: String, action: String): Boolean
```
Finishes download [token] and acts on it: [action] "save" (Downloads, with the "Downloaded · Open" bar and notification), "open" (PDF viewer or the phone's app for the type), "share" (share sheet) or "copy" (image to the clipboard).
**Example**
Documented together with `WebToApk.__dlBegin` — the example there shows this one too.
Internal transport behind ``, Blob downloads, `window.open(blobUrl)` and `AppMint.saveBlob` / `AppMint.downloadFile`: the file is streamed from the page to the app in slices, so a large export is never one giant string in memory. Pages use the standard download code; never call these directly, because the `__` methods may change without notice.
**Returns:** `__dlBegin(name, type, size)` returns a token (or `""` when the phone has no room); `__dlChunk(token, base64)` returns `false` if a slice could not be written; `__dlEnd(token, action)` finishes (`save` = Downloads, `open` = show it, `share`, `copy`). **Needs:** nothing.
**Use the public API:**
```js
const blob = new Blob([csvText], { type: 'text/csv' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'Report.csv';
a.click(); // lands in Downloads as "Report.csv"
```
Export a drawing from a canvas through the same route:
```js
canvas.toBlob(function (blob) {
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'drawing.png';
a.click();
setTimeout(function () { URL.revokeObjectURL(a.href); }, 10000);
}, 'image/png');
```
Save a JSON backup the user can keep, with a message when it is done:
```js
function exportBackup(data) {
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'backup-' + new Date().toISOString().slice(0, 10) + '.json';
document.body.appendChild(a);
a.click();
a.remove();
showMessage('Backup saved to Downloads.');
}
```
**Notes:** Implemented in the app shell (ShellDownloads.kt).
### `__fsChild`
```js
window.WebToApk.__fsChild(uri: String, name: String, kind: String, create: Boolean): String
```
getFileHandle / getDirectoryHandle (with `create`).
**Example**
Internal transport behind `getFileHandle(name, {create})` and `getDirectoryHandle(name, {create})`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok, kind, name, uri, canWrite}` or `{ok:false, error}` (`NotFoundError`, `TypeMismatchError`, `NoModificationAllowedError`). **Needs:** a folder from `showDirectoryPicker()`.
**Use the public API:**
```js
const dir = await showDirectoryPicker();
const photos = await dir.getDirectoryHandle('photos', { create: true });
const file = await photos.getFileHandle('list.json', { create: true });
```
Check whether a file already exists in the folder before creating it:
```js
async function exists(dir, name) {
try {
await dir.getFileHandle(name); // no {create} = look up only
return true;
} catch (e) {
if (e.name === 'NotFoundError') return false;
if (e.name === 'TypeMismatchError') return true; // a folder already has that name
throw e;
}
}
```
Save the app settings as JSON into a "config" sub-folder, creating both as needed:
```js
async function saveSettings(root, settings) {
const config = await root.getDirectoryHandle('config', { create: true });
const file = await config.getFileHandle('settings.json', { create: true });
const w = await file.createWritable();
await w.write(JSON.stringify(settings, null, 2));
await w.close();
}
// root = await showDirectoryPicker() (from a button tap)
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsFile`
```js
window.WebToApk.__fsFile(uri: String): String
```
getFile(): `{ok, name, type, size, lastModified, url}` (the body streams from url).
**Example**
Internal transport behind `FileSystemFileHandle.getFile()`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok, name, type, size, lastModified, url}` — the body streams from `url` (the app's own origin, with ranges) — or `{ok:false, error}` (`NotFoundError`, `TypeMismatchError`, `foreign_origin`). **Needs:** a handle from one of the pickers.
**Use the public API:**
```js
const [handle] = await showOpenFilePicker();
const file = await handle.getFile();
console.log(file.name, file.size, await file.text());
```
Show a picked image on the page without reading it into a string:
```js
document.querySelector('#choose').addEventListener('click', async function () {
const [handle] = await showOpenFilePicker({ types: [{ accept: { 'image/*': [] } }] });
const file = await handle.getFile(); // a real File, streamed from the app
const img = document.querySelector('#preview');
if (img.src) URL.revokeObjectURL(img.src);
img.src = URL.createObjectURL(file);
img.alt = file.name + ' (' + file.type + ')';
});
```
Re-read a file you opened earlier and notice when it has changed or been deleted:
```js
async function reloadIfChanged(handle, lastSeen) {
try {
const file = await handle.getFile();
if (file.lastModified === lastSeen) return null; // unchanged
return { data: JSON.parse(await file.text()), lastModified: file.lastModified };
} catch (e) {
if (e.name === 'NotFoundError') alert(handle.name + ' was moved or deleted.');
else throw e;
return null;
}
}
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsList`
```js
window.WebToApk.__fsList(uri: String): String
```
A directory handle's entries: `{ok, entries:[{kind, name, uri, canWrite}]}`.
**Example**
Internal transport behind iterating a `FileSystemDirectoryHandle` (`entries()`, `keys()`, `values()`, `for await`). Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok, entries:[{kind, name, uri, canWrite}]}` or `{ok:false, error}`. **Needs:** a folder from `showDirectoryPicker()`.
**Use the public API:**
```js
const dir = await showDirectoryPicker();
for await (const [name, entry] of dir.entries()) console.log(entry.kind, name);
```
Count the files in a folder and all its sub-folders:
```js
async function countFiles(dir) {
let n = 0;
for await (const entry of dir.values()) {
if (entry.kind === 'file') n++;
else n += await countFiles(entry); // entry is a FileSystemDirectoryHandle
}
return n;
}
document.querySelector('#scan').addEventListener('click', async function () {
const dir = await showDirectoryPicker();
console.log(dir.name, 'holds', await countFiles(dir), 'files');
});
```
Build a sorted list of the photos in a folder the user chose:
```js
document.querySelector('#open-album').addEventListener('click', async function () {
const dir = await showDirectoryPicker({ startIn: 'pictures' });
const names = [];
for await (const name of dir.keys()) {
if (/\.(jpe?g|png|webp)$/i.test(name)) names.push(name);
}
names.sort(function (a, b) { return a.localeCompare(b); });
renderAlbum(dir, names); // dir.getFileHandle(name) opens each one
});
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsPermission`
```js
window.WebToApk.__fsPermission(rootUri: String, uri: String): String
```
queryPermission() / requestPermission(): `{ok, state:'granted'|'prompt'}` for a handle whose picked root is [rootUri] — 'granted' while the app holds that pick's grant, across relaunches (the grant is persisted; a handle comes back from IndexedDB).
**Example**
Internal transport behind `FileSystemHandle.queryPermission()` and `requestPermission()`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok:true, state:'granted'}` while the app holds the grant of the picked folder or file the handle comes from (kept across restarts), `{ok:true, state:'prompt'}` once it is gone, or `{ok:false, error:'foreign_origin'}`. A read-only file answers `'denied'` for `{mode:'readwrite'}` in the page, without a call. **Needs:** a handle from one of the pickers, also one read back from IndexedDB.
**Use the public API:**
```js
const dir = await kvGet('backupDir'); // a handle stored in IndexedDB earlier
if ((await dir.queryPermission({ mode: 'readwrite' })) === 'granted') {
const f = await dir.getFileHandle('backup.json', { create: true });
const w = await f.createWritable();
await w.write(JSON.stringify(state));
await w.close();
}
```
Ask again from a tap when the grant is gone — the folder picker opens at that folder, and only the same folder grants:
```js
document.getElementById('reconnect').addEventListener('click', async () => {
const dir = await kvGet('backupDir');
const state = await dir.requestPermission({ mode: 'readwrite' }); // 'granted' | 'denied'
status.textContent = state === 'granted' ? 'Backups resumed' : 'Choose a backup folder';
});
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt). See `showOpenFilePicker` for the whole File System Access API.
### `__fsPick`
```js
window.WebToApk.__fsPick(requestId: String, kind: String, optionsJson: String): String
```
Opens the [kind] picker (open | save | directory); handles arrive as `appmint:fs`.
**Example**
Internal transport behind `showOpenFilePicker()`, `showSaveFilePicker()` and `showDirectoryPicker()`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `{ok:true}` once the picker is on screen, or `{ok:false, error}` (`NotAllowedError` when one is already open, `foreign_origin`). The handles arrive as the `appmint:fs` event `{requestId, handles:[{kind, name, uri, canWrite}]}` or `{requestId, error:'cancelled'}`. **Needs:** nothing to switch on.
**Use the public API:**
```js
const [handle] = await showOpenFilePicker({ types: [{ accept: { 'image/*': ['.png', '.jpg'] } }] });
const file = await handle.getFile();
```
Save a report with a suggested name, from a button tap (the pickers need a user gesture):
```js
document.querySelector('#export').addEventListener('click', async function () {
try {
const handle = await showSaveFilePicker({
suggestedName: 'report.csv',
types: [{ description: 'CSV', accept: { 'text/csv': ['.csv'] } }]
});
const w = await handle.createWritable();
await w.write(buildCsv());
await w.close();
} catch (e) {
if (e.name !== 'AbortError') alert('Export failed: ' + e.message); // AbortError = cancelled
}
});
```
Let the user pick several photos at once, starting in the Pictures folder:
```js
document.querySelector('#add-photos').addEventListener('click', async function () {
let handles;
try {
handles = await showOpenFilePicker({
multiple: true,
startIn: 'pictures',
types: [{ accept: { 'image/*': ['.jpg', '.jpeg', '.png', '.webp'] } }]
});
} catch (e) { return; } // cancelled or already open
for (const h of handles) addToGallery(await h.getFile());
});
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt). The same page code works unchanged in desktop Chrome.
### `__fsRemove`
```js
window.WebToApk.__fsRemove(uri: String, name: String, recursive: Boolean): String
```
removeEntry(name, {recursive}).
**Example**
Internal transport behind `FileSystemDirectoryHandle.removeEntry(name, {recursive})`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok:true}` or `{ok:false, error}` (`NotFoundError`, `InvalidModificationError` for a non-empty folder without `recursive`). **Needs:** a folder from `showDirectoryPicker()`.
**Use the public API:**
```js
const dir = await showDirectoryPicker();
await dir.removeEntry('old-drafts', { recursive: true });
```
Delete one file and treat "already gone" as done:
```js
async function deleteFile(dir, name) {
try {
await dir.removeEntry(name);
} catch (e) {
if (e.name !== 'NotFoundError') throw e; // NotFoundError: nothing left to delete
}
}
```
Remove a folder, asking first only when it still has something in it:
```js
async function removeFolder(dir, name) {
try {
await dir.removeEntry(name); // succeeds for an empty folder
} catch (e) {
if (e.name !== 'InvalidModificationError') throw e;
if (!confirm('"' + name + '" is not empty. Delete it and everything inside?')) return false;
await dir.removeEntry(name, { recursive: true });
}
return true;
}
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsWritableAbort`
```js
window.WebToApk.__fsWritableAbort(token: String)
```
abort(): the swap is dropped; the document is untouched.
**Example**
Internal transport behind `FileSystemWritableFileStream.abort()` — the swap copy is dropped and the file stays as it was. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** nothing. **Needs:** an open writable stream.
**Use the public API:**
```js
const w = await handle.createWritable();
try { await w.write(await buildExport()); await w.close(); }
catch (e) { await w.abort(); }
```
Let the user cancel a long export; nothing half-written reaches the file:
```js
let cancelled = false;
document.getElementById('cancel').onclick = function () { cancelled = true; };
async function exportAll(handle, pages) {
const w = await handle.createWritable();
for (const page of pages) {
if (cancelled) { await w.abort(); return 'cancelled'; } // the file keeps its old content
await w.write(await renderPage(page));
}
await w.close();
return 'saved';
}
```
Download straight into a file with `pipeTo`; stopping the download aborts the write:
```js
const ctl = new AbortController();
document.getElementById('stop').onclick = function () { ctl.abort(); };
async function downloadInto(handle, url) {
const res = await fetch(url);
if (!res.ok) throw new Error('HTTP ' + res.status);
const w = await handle.createWritable();
try {
await res.body.pipeTo(w, { signal: ctl.signal }); // closes the file when the body ends
return 'saved';
} catch (e) {
return e.name === 'AbortError' ? 'stopped, file unchanged' : 'failed: ' + e.message;
}
}
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsWritableClose`
```js
window.WebToApk.__fsWritableClose(token: String): String
```
close(): the swap replaces the document.
**Example**
Internal transport behind `FileSystemWritableFileStream.close()` — the swap copy replaces the file. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok:true}` or `{ok:false, error}` (`NoModificationAllowedError`, `InvalidModificationError` when the file's app cannot shorten it). **Needs:** an open writable stream.
**Use the public API:**
```js
const w = await handle.createWritable();
await w.write(json);
await w.close(); // nothing changes on disk before this
```
Tell the user why a save did not go through (`close()` is where it can fail):
```js
async function saveText(handle, text) {
const w = await handle.createWritable();
await w.write(text);
try {
await w.close();
return true;
} catch (e) {
if (e.name === 'InvalidModificationError') alert('This file\'s app cannot make it shorter. Save a copy instead.');
else if (e.name === 'NoModificationAllowedError') alert('This file cannot be changed.');
else alert('Save failed: ' + e.message);
return false;
}
}
```
Write a file in several pieces; readers still see the old content until the one `close()`:
```js
async function saveRows(handle, rows) {
const w = await handle.createWritable();
await w.write('id,name,total\n');
for (const r of rows) await w.write(r.id + ',' + r.name + ',' + r.total + '\n');
console.log('before close:', (await handle.getFile()).size, 'bytes (old file)');
await w.close();
console.log('after close:', (await handle.getFile()).size, 'bytes');
}
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsWritableOpen`
```js
window.WebToApk.__fsWritableOpen(uri: String, keepExisting: Boolean): String
```
createWritable(): a swap file, copied from the file when [keepExisting].
**Example**
Internal transport behind `FileSystemFileHandle.createWritable({keepExistingData})`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok, token}` for a private swap copy, or `{ok:false, error}` (`NoModificationAllowedError` for a read-only file). **Needs:** a handle from one of the pickers.
**Use the public API:**
```js
const handle = await showSaveFilePicker({ suggestedName: 'report.csv' });
const w = await handle.createWritable({ keepExistingData: false });
await w.write('a,b\n1,2\n');
await w.close();
```
Append a line to the end of an existing log file, keeping what is already in it:
```js
async function appendLine(handle, line) {
const size = (await handle.getFile()).size;
const w = await handle.createWritable({ keepExistingData: true });
await w.seek(size); // write after the old content
await w.write(new Date().toISOString() + ' ' + line + '\n');
await w.close(); // only now does the file change
}
```
Save a canvas as a PNG, and leave the file untouched if anything goes wrong:
```js
document.querySelector('#save-png').addEventListener('click', async function () {
const handle = await showSaveFilePicker({
suggestedName: 'drawing.png',
types: [{ accept: { 'image/png': ['.png'] } }]
});
const blob = await new Promise(function (r) { document.querySelector('canvas').toBlob(r, 'image/png'); });
const w = await handle.createWritable();
try {
await w.write(blob);
await w.close();
} catch (e) {
try { await w.abort(); } catch (x) {} // nothing reaches the file before close()
alert('Could not save: ' + e.message);
}
});
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsWritableTruncate`
```js
window.WebToApk.__fsWritableTruncate(token: String, size: Double): String
```
truncate(size) on a writable stream.
**Example**
Internal transport behind `FileSystemWritableFileStream.truncate(size)`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok:true}` or `{ok:false, error}`. **Needs:** an open writable stream.
**Use the public API:**
```js
const w = await handle.createWritable({ keepExistingData: true });
await w.truncate(0);
await w.write('fresh start');
await w.close();
```
Keep only the first 1,000 bytes of a file and cut everything after them:
```js
async function keepFirstKilobyte(handle) {
const w = await handle.createWritable({ keepExistingData: true });
await w.truncate(1000); // a file shorter than this grows instead (see the next example)
await w.close();
}
```
Reserve space: truncating to a larger size grows the file, and the new bytes read back as zeros:
```js
async function makeEmptySlotFile(handle, slots, slotSize) {
const w = await handle.createWritable();
await w.truncate(slots * slotSize); // e.g. 100 slots of 256 bytes, all zero
await w.write({ type: 'write', position: 0, data: new Uint8Array([1, 0, 0, 0]) });
await w.close();
console.log('file is now', (await handle.getFile()).size, 'bytes');
}
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt).
### `__fsWritableWrite`
```js
window.WebToApk.__fsWritableWrite(token: String, position: Double, base64: String): String
```
One chunk of a writable stream's write(), at [position].
**Example**
Internal transport behind `FileSystemWritableFileStream.write()` — one chunk at a position in the swap copy. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{ok:true}` or `{ok:false, error}`. **Needs:** an open writable stream.
**Use the public API:**
```js
const w = await handle.createWritable({ keepExistingData: true });
await w.write({ type: 'write', position: 0, data: new Blob(['HEADER\n']) });
await w.close();
```
Add a line to the end of a log file the user picked (a file picker needs a tap):
```js
document.getElementById('addLine').addEventListener('click', async () => {
const [handle] = await showOpenFilePicker({
types: [{ description: 'Text', accept: { 'text/plain': ['.txt', '.log'] } }]
});
const size = (await handle.getFile()).size;
const w = await handle.createWritable({ keepExistingData: true });
await w.seek(size); // start writing after the old content
await w.write(new Date().toISOString() + ' checked in\n');
await w.close();
});
```
Save a canvas drawing as a new PNG with "Save as" (a Blob is written as its raw bytes):
```js
document.getElementById('saveDrawing').addEventListener('click', async () => {
const handle = await showSaveFilePicker({
suggestedName: 'drawing.png',
types: [{ description: 'PNG image', accept: { 'image/png': ['.png'] } }]
});
const blob = await new Promise(function (ok) { document.querySelector('canvas').toBlob(ok, 'image/png'); });
const w = await handle.createWritable();
await w.write(blob);
await w.close();
});
```
**Notes:** Implemented in the app shell (FileSystemAccess.kt). Large data is sent in chunks.
### `__idlePermission`
```js
window.WebToApk.__idlePermission(request: Boolean): String
```
IdleDetector.requestPermission() ([request] true, called under a user gesture) records the grant; false only reads it. "granted" | "prompt".
**Example**
Internal transport behind `IdleDetector.requestPermission()` and the `'idle-detection'` permission state. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `'granted'` or `'prompt'`. **Needs:** a user gesture for the request.
**Use the public API:**
```js
button.onclick = async () => {
const state = await IdleDetector.requestPermission();
console.log(state); // 'granted'
};
```
Feature-detect, and treat a refusal as "not allowed":
```js
async function askIdlePermission() {
if (!('IdleDetector' in window)) return false;
try {
return (await IdleDetector.requestPermission()) === 'granted';
} catch (err) {
return false;
}
}
```
Request it from a tap, then start detecting:
```js
startBtn.addEventListener('click', async () => {
if (!(await askIdlePermission())) { showMessage('Idle detection was not allowed.'); return; }
const idle = new IdleDetector();
idle.addEventListener('change', () => console.log(idle.userState));
await idle.start({ threshold: 60000 });
});
```
**Notes:** Implemented in the app shell (IdleAndRelatedApps.kt).
### `__idleState`
```js
window.WebToApk.__idleState(): String
```
IdleDetector: `{idleMs, locked}` from the app's own input and the keyguard.
**Example**
Internal transport behind `IdleDetector`: how long since the user last gave input, and whether the screen is locked. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** JSON `{idleMs, locked}`. Screen and app changes are pushed as the `appmint:idle` event with the same shape. **Needs:** nothing.
**Use the public API:**
```js
const idle = new IdleDetector();
idle.onchange = () => console.log(idle.userState, idle.screenState);
await idle.start({ threshold: 60000 });
```
Stop watching with an AbortController when the screen closes:
```js
const ctl = new AbortController();
const idle = new IdleDetector();
idle.addEventListener('change', () => {
if (idle.userState === 'idle') showAwayBanner();
});
await idle.start({ threshold: 60000, signal: ctl.signal });
// later: ctl.abort();
```
Lock the app when the screen locks:
```js
if ('IdleDetector' in window && (await IdleDetector.requestPermission()) === 'granted') {
const d = new IdleDetector();
d.onchange = () => { if (d.screenState === 'locked') showPinScreen(); };
await d.start({ threshold: 60000 });
}
```
**Notes:** Implemented in the app shell (IdleAndRelatedApps.kt).
### `__lockOrientation`
```js
window.WebToApk.__lockOrientation(type: String): String
```
screen.orientation.lock(type): "ok", "type" for a string that is not an OrientationLockType, or "unsupported" (Android TV is always landscape).
**Example**
Internal transport behind `screen.orientation.lock(type)`. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `'ok'`, `'type'` for a string that is not an orientation lock type, or `'unsupported'` (Android TV). **Needs:** nothing to switch on.
**Use the public API:**
```js
document.getElementById('play').addEventListener('click', async () => {
try { await screen.orientation.lock('landscape'); } catch (e) { /* NotSupportedError on TV */ }
});
document.getElementById('exit').addEventListener('click', () => screen.orientation.unlock());
```
Tell a bad lock type apart from a device that cannot rotate:
```js
async function lockTo(type) {
if (!screen.orientation || typeof screen.orientation.lock !== 'function') return 'unsupported';
try {
await screen.orientation.lock(type);
return 'ok';
} catch (e) {
if (e instanceof TypeError) return 'bad-type'; // not an OrientationLockType string
return 'unsupported'; // NotSupportedError (Android TV)
}
}
lockTo('portrait-primary').then((r) => console.log('orientation lock:', r));
```
Freeze the screen the way the user is holding it while they sign, then give rotation back:
```js
async function startSigning() {
const current = screen.orientation.type; // e.g. 'landscape-primary'
try { await screen.orientation.lock(current); } catch (e) { /* keep going unlocked */ }
showSignaturePad();
}
function finishSigning() {
hideSignaturePad();
screen.orientation.unlock();
}
```
**Notes:** Implemented in the app shell (WebApiPolyfills.kt). The same page code works unchanged in Chrome.
### `__nfcCancelWrite`
```js
window.WebToApk.__nfcCancelWrite()
```
Cancels the waiting write/lock (the polyfill calls it when the operation's `signal` aborts).
**Example**
Drops a queued NFC write or lock so the next tag tap is read normally. Pages cancel through the web standard — an `AbortController` `signal` — and the `NDEFReader` polyfill calls this for them.
**Returns:** nothing. **Needs:** **Web NFC Support** turned on in Step 4 (Access) when you build.
The standard way, which the app honours — the waiting `write()` rejects with `AbortError`:
```js
var controller = null;
async function writeWithCancel(text) {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
controller = new AbortController();
showStatus('Tap a tag to write it... (or press Cancel)');
try {
await new NDEFReader().write(text, { signal: controller.signal });
showStatus('Tag written.');
} catch (err) {
showStatus(err.name === 'AbortError' ? 'Cancelled.' : 'Write failed: ' + err.message);
}
}
document.getElementById('cancel').addEventListener('click', function () {
if (controller) controller.abort();
});
```
Give up by itself when no tag arrives in time; a timer that aborts the signal cancels the same way:
```js
async function writeWithTimeout(url, ms) {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
var controller = new AbortController();
var timer = setTimeout(function () { controller.abort(); }, ms);
showStatus('Tap a tag within ' + Math.round(ms / 1000) + ' seconds...');
try {
await new NDEFReader().write({ records: [{ recordType: 'url', data: url }] }, { signal: controller.signal });
showStatus('Tag written.');
} catch (err) {
showStatus(err.name === 'AbortError' ? 'Timed out. Tap Write to try again.' : 'Write failed: ' + err.message);
} finally {
clearTimeout(timer);
}
}
```
Cancel a waiting lock (or write) when the user leaves the screen, so a later tap does not change a tag:
```js
var pendingTagOp = null;
window.addEventListener('hashchange', function () {
if (pendingTagOp) { pendingTagOp.abort(); pendingTagOp = null; }
});
document.getElementById('lock').addEventListener('click', function () {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
if (pendingTagOp) pendingTagOp.abort();
var controller = pendingTagOp = new AbortController();
showStatus('Tap the tag to lock it...');
new NDEFReader().makeReadOnly({ signal: controller.signal })
.then(function () { showStatus('Tag locked.'); })
.catch(function (err) { if (err.name !== 'AbortError') showStatus('Lock failed: ' + err.message); })
.finally(function () { if (pendingTagOp === controller) pendingTagOp = null; });
});
```
**Notes:** Do not call `WebToApk.__nfcCancelWrite()` yourself: called directly it drops the native wait but cannot settle the page's Promise. The `signal` does both. Cancelling also drops a queued `makeReadOnly()`.
### `__nfcMakeReadOnly`
```js
window.WebToApk.__nfcMakeReadOnly(): String
```
Queues a permanent lock (`NDEFReader.makeReadOnly()`) for the next tag tap; returns its op id, "" when NFC is off in this app.
**Example**
Internal transport behind `NDEFReader.makeReadOnly()`. Pages use `new NDEFReader().makeReadOnly()`; never call this directly.
**Returns:** (through `makeReadOnly`) a Promise that resolves after the user taps a tag and it is locked, or rejects with a `DOMException`. **Needs:** **Web NFC Support** turned on in Step 4 (Access) when you build.
Locking is permanent. Write the tag first, then lock it, and ask the user before both:
```js
document.getElementById('publish-tag').addEventListener('click', async function () {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
if (!confirm('Write and lock this tag? A locked tag can never be changed.')) return;
var reader = new NDEFReader();
try {
showStatus('Tap the tag to write it...');
await reader.write({ records: [{ recordType: 'url', data: 'https://example.com/item/42' }] });
showStatus('Now tap the same tag again to lock it...');
await reader.makeReadOnly();
showStatus('Tag written and locked.');
} catch (err) {
showStatus('Failed: ' + err.message);
}
});
```
Lock a tag that is already written, and give up if no tag arrives within 20 seconds:
```js
async function lockTag() {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
if (!confirm('Lock this tag for good? It can never be changed again.')) return;
var controller = new AbortController();
var timer = setTimeout(function () { controller.abort(); }, 20000);
showStatus('Tap the tag to lock it...');
try {
await new NDEFReader().makeReadOnly({ signal: controller.signal });
showStatus('Tag locked.');
} catch (err) {
if (err.name === 'AbortError') showStatus('No tag was tapped. Try again when ready.');
else if (err.name === 'NotAllowedError') showStatus('This kind of tag cannot be locked.');
else showStatus('Lock failed: ' + err.message);
} finally {
clearTimeout(timer);
}
}
```
Read a tag first and only offer to lock it when it holds the expected link:
```js
async function checkThenLock(expectedUrl) {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
var reader = new NDEFReader();
var scanning = new AbortController();
var lockBtn = document.getElementById('lock-btn');
reader.onreading = function (e) {
var rec = e.message.records.find(function (r) { return r.recordType === 'url'; });
var url = rec ? new TextDecoder().decode(rec.data) : null;
showStatus(url ? 'Tag points to ' + url : 'This tag holds no link.');
lockBtn.disabled = url !== expectedUrl;
};
await reader.scan({ signal: scanning.signal });
showStatus('Hold the tag to the phone to check it.');
lockBtn.onclick = async function () {
if (!confirm('Lock this tag? It can never be changed again.')) return;
scanning.abort();
showStatus('Tap the tag again to lock it...');
try { await reader.makeReadOnly(); showStatus('Tag locked.'); }
catch (err) { showStatus('Lock failed: ' + err.message); }
};
}
```
**Notes:** Each step needs its own tap. The call returns an operation id and the result arrives through `window.__appmintNfcDone`. Rejections: `NotSupportedError` "Tag does not support NDEF", `NotAllowedError` "This tag cannot be made read-only" (many tags cannot be locked), `NetworkError` when the tag moves away. Starting a `write()` while a lock waits replaces the lock, which then rejects with `AbortError`. A `signal` passed to `makeReadOnly({ signal })` cancels the wait.
### `__nfcState`
```js
window.WebToApk.__nfcState(): String
```
"on", "off" (NFC switched off in the phone's settings) or "none" (no NFC, or not enabled in this app) — what `NDEFReader.scan()` checks first.
**Example**
Internal check behind `NDEFReader.scan()`: whether this app can use NFC right now. Pages call `scan()` and read its rejection instead.
**Returns:** `'on'`, `'off'` (NFC is switched off in the phone's settings) or `'none'` (the phone has no NFC, or the app was built without Web NFC Support). **Needs:** **Web NFC Support** turned on in Step 4 (Access) when you build.
The standard way — `scan()` rejects with the same answer:
```js
async function startReading() {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
try {
await new NDEFReader().scan();
showStatus('Hold a tag to the back of the phone.');
} catch (err) {
if (err.name === 'NotReadableError') showStatus('Turn on NFC in the phone settings, then try again.');
else if (err.name === 'NotSupportedError') showStatus('This phone has no NFC.');
else showStatus('NFC error: ' + err.message);
}
}
```
Check once when the screen opens, to choose between the NFC panel, a "turn on NFC" hint and hiding NFC altogether. Aborting the probe's scan right away leaves nothing running:
```js
async function nfcStatus() {
if (!('NDEFReader' in window)) return 'none';
var probe = new AbortController();
try {
await new NDEFReader().scan({ signal: probe.signal });
return 'on';
} catch (err) {
return err.name === 'NotReadableError' ? 'off' : 'none';
} finally {
probe.abort();
}
}
async function refreshNfcUi() {
var state = await nfcStatus();
document.getElementById('nfc-panel').hidden = state !== 'on';
document.getElementById('nfc-off-hint').hidden = state !== 'off';
}
refreshNfcUi();
document.addEventListener('visibilitychange', function () {
if (document.visibilityState === 'visible') refreshNfcUi(); // back from the phone settings
});
```
Read tags only while one screen is open, and tell an empty or unreadable tag apart from NFC being off:
```js
var tagScreen = null;
async function openTagScreen() {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
tagScreen = new AbortController();
var reader = new NDEFReader();
reader.onreading = function (e) {
var n = e.message.records.length;
showStatus(n ? 'Tag ' + e.serialNumber + ' holds ' + n + ' record(s).' : 'This tag is empty.');
};
reader.onreadingerror = function () { showStatus('This tag cannot be read. Try another one.'); };
try {
await reader.scan({ signal: tagScreen.signal });
showStatus('Hold a tag to the back of the phone.');
} catch (err) {
showStatus(err.name === 'NotReadableError' ? 'NFC is off. Turn it on in the phone settings.' : 'NFC error: ' + err.message);
}
}
function closeTagScreen() {
if (tagScreen) { tagScreen.abort(); tagScreen = null; }
}
```
**Notes:** Plumbing for the polyfill; use `scan()`. `window.AndroidNFC.startScan()` answers the same question as a boolean and shows a "Please enable NFC" message when NFC is off.
### `__nfcWrite`
```js
window.WebToApk.__nfcWrite(messageJson: String): String
```
Queues [messageJson] (`{records:[…], overwrite}`, built by `NDEFReader.write()`) for the next tag tap and returns its op id; "" when NFC is not enabled in this app.
**Example**
Internal transport behind `NDEFReader.write(message)`. Pages use `new NDEFReader().write(...)`; never call this directly.
**Returns:** (through `write`) a Promise that resolves after the user taps a tag and it is written, or rejects with a `DOMException`. **Needs:** **Web NFC Support** turned on in Step 4 (Access) when you build.
```js
document.getElementById('write-table-tag').addEventListener('click', async function () {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
showStatus('Tap a tag to write it...');
try {
await new NDEFReader().write({
records: [
{ recordType: 'url', data: 'https://example.com/menu' },
{ recordType: 'text', data: 'Table 12', lang: 'en' },
{ recordType: 'mime', mediaType: 'application/json',
data: new TextEncoder().encode(JSON.stringify({ table: 12 })) }
]
});
showStatus('Tag written.');
} catch (err) {
showStatus('Write failed: ' + err.message);
}
});
```
Write only to a blank tag, so a tag that already holds data is never replaced by mistake:
```js
async function writeToBlankTag(url) {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
showStatus('Tap a blank tag...');
try {
await new NDEFReader().write(
{ records: [{ recordType: 'url', data: url }] },
{ overwrite: false }
);
showStatus('Tag written.');
} catch (err) {
if (err.name === 'NotAllowedError') showStatus('That tag already holds data or is locked. Use a blank tag.');
else if (err.name === 'NetworkError') showStatus('Hold the tag still until it is written.');
else showStatus('Write failed: ' + err.message);
}
}
```
Write a smart poster, a link together with its title, as one record:
```js
document.getElementById('write-poster').addEventListener('click', async function () {
if (!('NDEFReader' in window)) { showStatus('NFC is not available in this app.'); return; }
showStatus('Tap a tag to write the poster...');
try {
await new NDEFReader().write({
records: [{
recordType: 'smart-poster',
data: { records: [
{ recordType: 'url', data: 'https://example.com/events/spring-fair' },
{ recordType: 'text', data: 'Spring Fair tickets', lang: 'en' }
] }
}]
});
showStatus('Poster tag written.');
} catch (err) {
showStatus(err.name === 'NotSupportedError' ? 'This tag is too small or cannot hold NFC data.' : 'Write failed: ' + err.message);
}
});
```
**Notes:** The polyfill checks the records, turns them into `{records:[{recordType, id, data(base64), encoding, lang, mediaType, records?}], overwrite}` and passes the JSON string here. The call returns an operation id; the result comes back to the page through `window.__appmintNfcDone(id, errorName, message)`, so an answer for a replaced write never settles a newer one. Unformatted tags are formatted first. Rejections: `NotAllowedError` ("Tag is read-only", or a tag with records when `overwrite` is false), `NotSupportedError` ("Tag does not support NDEF", "Tag too small (N bytes available)"), `NetworkError` (the tag moved away), `SyntaxError` (a record the tag format cannot hold). The app also shows its own short "Ready to write" and "NFC tag written" messages.
### `__ocrAvailable`
```js
window.WebToApk.__ocrAvailable(): Boolean
```
TextDetector / recognizeText(): Google Play services is here (the OCR module's home).
**Example**
Internal transport behind `TextDetector`: whether Google Play services (where the recognizer comes from) is on this phone. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** `true` or `false`. When `false`, `TextDetector` is not installed at all. **Needs:** nothing.
**Use the public API:**
```js
if ('TextDetector' in window) scanButton.hidden = false;
```
Choose between the scan flow and a typed form once, at start-up. When the phone has no Google Play services the detector is simply absent, so the page must offer another way in:
```js
function setUpReceiptEntry() {
var canScan = typeof window.TextDetector === 'function';
document.getElementById('scan-receipt').hidden = !canScan;
document.getElementById('type-receipt').hidden = canScan;
if (!canScan) document.getElementById('entry-hint').textContent =
'Text scanning is not available on this phone. Type the total below.';
}
document.addEventListener('DOMContentLoaded', setUpReceiptEntry);
```
A detector that exists can still answer that recognition is unavailable at the moment of the call. Tell the two failures apart by the error name:
```js
async function readLabel(img) {
if (typeof window.TextDetector !== 'function') return null;
try {
var lines = await new TextDetector().detect(img);
return lines.map(function (l) { return l.rawValue; }).join('\n');
} catch (e) {
if (e.name === 'NotSupportedError') showMessage('Text recognition is not available right now.');
else showMessage('Could not read the label: ' + e.message);
return null;
}
}
```
**Notes:** Implemented in the app shell (TextRecognitionBridge.kt).
### `__ocrRecognize`
```js
window.WebToApk.__ocrRecognize(requestId: String, base64: String)
```
Recognises the text in [base64] (PNG/JPEG); the answer arrives as `appmint:ocr {requestId, blocks|error}`.
**Example**
Internal transport behind `TextDetector.detect()`: recognises the text in a PNG/JPEG. Pages use the standard API; never call this directly — the `__` methods may change without notice.
**Returns:** nothing; the answer arrives as the `appmint:ocr` event `{requestId, blocks:[{text, box, corners, lines}]}` or `{requestId, error}` (`unavailable`, `bad-image`, `failed: …`). **Needs:** nothing.
**Use the public API:**
```js
const lines = await new TextDetector().detect(document.getElementById('receipt'));
console.log(lines.map((l) => l.rawValue));
```
Read the text of a photo the user picks. `detect()` accepts a `Blob`/`File` as well as an `![]()
`, `