# AppMint integration guide - complete

Source: https://freewebtoapk.com/docs/ · generated from the guide shipped inside the AppMint app · 2026-09-20
47 chapters, 358 steps, plus the 152-method bridge API reference.

---

# Free AI App Builder

> Describe an app in plain words and get a real APK, with no key and no account.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/free-ai-app-builder

Build Android apps and games for free - get a key from OpenRouter or Arena AI and pick a free model

### 1. Build your app for free

You can create a full Android app or game here without paying anyone - including us.

The AI that writes your app runs on your own free account with one of two gateways: OpenRouter or Arena AI. Both hand out an API key for free, and both carry models that cost nothing to use. You bring the key, we do the rest.

It takes about two minutes to set up, and you only ever do it once.

### 2. Step 1 - Create your free key

Pick either gateway. You only need ONE of them:

- OpenRouter - one key unlocks Claude, GPT, Gemini, Llama, DeepSeek and hundreds more. Its free models have ids ending in ":free", and AppMint lists those first so they are easy to spot.

- Arena AI - a newer gateway with the same one-key idea and a clean model list.

Sign up with an email or a Google account, then open the keys page and create a key. Copy it straight away - most sites show a key only once.

[Get a free OpenRouter key](https://openrouter.ai/keys)

### 3. Step 1b - Or use Arena AI instead

Prefer Arena AI? Sign up at arena.ai, open the dashboard and create a virtual API key. Paste that key into AppMint exactly the same way as an OpenRouter key - everything after this step is identical.

[Get an Arena AI key](https://portal.api.preview.arena.ai/dashboard/keys)

### 4. Step 2 - Tap 'Create with AI'

Back on the AppMint home screen, tap 'Create with AI' to open the AI App Studio. This is where you describe your app and watch it get built.

### 5. Step 3 - Add your key

In the AI App Studio:

1. Tap the provider name at the bottom of the screen (it shows the current provider).
2. Choose OpenRouter or Arena AI from the list.
3. Paste your key and tap 'Save & Test'.

A green tick means the key works. Your key is stored encrypted on your device and is sent only to the gateway you chose - never to us.

### 6. Step 4 - Choose a free model

Once the key is accepted, AppMint loads the full model list from your account.

On OpenRouter, look for models ending in ":free" - they are sorted to the top and cost nothing. On Arena AI, pick any model from the list.

A 📷 marker means the model can also read images, which is what powers Screenshot → App.

### 7. Step 5 - Describe it, and build

Type what you want in plain words - "a habit tracker with streaks and a dark theme", "a 2D endless runner game" - and tap Generate.

Preview it live, ask for changes in the same box, then tap 'Build App' to turn it into a real APK you can install or publish to Google Play.

No credits are used and nothing is charged: the whole run happens on your own free key.

### 8. Good to know

- Free models are shared by a lot of people, so they can be slower or briefly busy at peak times. Try again in a moment, or switch to another free model.
- Bigger apps ask more of the model - if a large app struggles on a free model, a paid model on the same key handles it comfortably.
- You can swap providers or keys whenever you like; your projects stay put.
- Prefer to skip setup entirely? AppMint AI needs no key or account at all - see the AppMint AI section below.


---

# AppMint AI (How Credits Work)

> What one Mint buys, what a typical app costs to generate, and why editing is cheaper than creating.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/how-credits-work

No setup, no API keys - buy credits and build apps instantly

### 1. What is AppMint AI?

AppMint AI is the easiest way to build an app - no accounts, no API keys, no setup. You just buy credits and start building. We run the AI for you in the background and you pay only for what you use.

### 2. How credits work

Credits are like prepaid balance. Every time the AI builds or edits your app, it uses some credits - and we show you exactly how many ('Used 45 credits · 7,910 left').

There is no fixed 'number of apps' because usage depends on how big your app is and how many changes you make. A small app costs little; a large app with lots of edits costs more. You can spend your whole balance on one big app if you want.

### 3. Buying credits

Tap 'Buy Credits' and pick a pack:

- Starter - $2.30 (100 credits - approximately 2-3 full apps)
- Maker - $5.74 (450 credits - approximately 8 full apps)

The 'approximately N apps' figures are estimates only - your real usage is metered. Payment is handled securely by Google Play, or via web checkout (Dodo) which is cheaper than the in-app price; there is no subscription.

### 4. Standard vs Best Quality

Pick a quality level before you build:

- Standard - great for most apps and the cheapest. Recommended.
- Best Quality - uses a smarter model for tricky apps, but spends credits faster.

You can switch any time. Image → App (turning a screenshot or drawing into an app) works on both.

### 5. AppMint AI vs Free vs Your Own Key

You have three ways to build:

- AppMint AI - best quality, no setup, pay-as-you-go credits, always badge-free. (Recommended.)
- Free providers - Groq (free key from console.groq.com) or Cloudflare Workers AI (free tier from dash.cloudflare.com). Great for testing ideas.
- Your Own AI Key - bring a Claude, OpenAI, Grok, or DeepSeek key.

All providers are available to everyone. Apps built with your own key include a small AppMint badge unless you have a Pro plan. AppMint AI apps are always badge-free.

### 6. Your balance is always safe

Your credit balance is stored on our secure server, not just on your phone - so it follows your purchase. If you reinstall the app, your remaining credits are restored. We never see or store any AI provider keys on your device for AppMint AI; everything runs server-side.


---

# AI App Studio (Bring Your Own Key)

> Run the AI pipeline on your own OpenAI, Anthropic or OpenRouter key instead of Mints.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/ai-app-studio-own-key

Generate apps with Groq (Free), OpenRouter, Claude, OpenAI, Grok or DeepSeek using your own API key

### 1. What is the AI App Studio?

The AI App Studio lets you describe an app in plain words and have an AI build it for you - then preview it live and turn it into an APK, all inside this app.

It uses a 'bring your own key' model: you connect your own AI account, so generation costs are billed directly by the AI provider, not by us.

### 2. Choose an AI provider

Pick one of the supported providers:

- Groq - FREE tier available, very fast (recommended to start)
- Cloudflare Workers AI - FREE tier available, open models (Llama, etc.)
- Claude (Anthropic)
- OpenAI (ChatGPT)
- Grok (xAI)
- DeepSeek

You need an account with that provider. Groq and Cloudflare both offer generous free tiers; the others have pay-as-you-go pricing.

### 3. Get your API key

Create an API key in your provider's console, then copy it:

- Groq (FREE): console.groq.com/keys
- Cloudflare (FREE): dash.cloudflare.com → AI / Workers AI. Copy your Account ID and create an API token with the Workers AI permission, then enter them in the app as accountId:token.
- Claude: console.anthropic.com/settings/keys
- OpenAI: platform.openai.com/api-keys
- Grok: console.x.ai
- DeepSeek: platform.deepseek.com/api_keys

⚠️ Keep your key private - treat it like a password.

[Open Anthropic Console](https://console.anthropic.com/settings/keys)

### 4. Connect your key in the app

In the AI App Studio:

1. Select your provider from the dropdown
2. Paste your API key
3. Tap 'Save & Test'

The key is stored encrypted on your device and is sent only to your chosen provider - never to us. You can change or remove it any time.

### 5. Pick a model

After the key is validated, the studio fetches the list of available models from your provider. Choose one and it stays fixed for the whole session for consistent results. Models marked 📷 also support image input (used by Screenshot → App and Inspire-from-Website).

### 6. Generate your app

Choose how to start:

- Create from Prompt - describe the app
- Improve My App - upload existing HTML/ZIP and refine
- Screenshot → App - turn an image into an app
- Inspire from Website - browse a site, capture screens
- Remix a Template - start from a ready-made app

Tap Generate, then refine with follow-up instructions. Use 'View Live' to preview the running app at any time.

### 7. Build the APK

When you're happy with the preview, tap 'Build App'. The generated project is handed to the normal APK wizard - set your icon, name, package and options as usual, then generate. Your APK and AAB appear in the Downloads section like any other build.

### 8. Costs & privacy

✅ You pay your AI provider directly for usage - there is no extra charge from us.  
✅ Your API key never leaves your device except to call your provider.  
✅ A Mints counter shows usage per session so you can keep costs in check.  
✅ Simple-HTML apps are cheapest; React/framework apps use more Mints.

### 9. Free tiers & automatic fallback

The free providers have different limits:

- Groq - about 8,000 tokens per MINUTE. A large app can hit this mid-build.
- Cloudflare - 10,000 Neurons per DAY (resets at 00:00 UTC), with no per-minute cap.

If Groq hits its per-minute limit and you have a Cloudflare key saved, the studio automatically retries your request on Cloudflare - so a busy moment on one free provider doesn't block you. For the most consistent results on big apps, add your own paid key (Claude or OpenAI).


---

# Writing HTML for your app

> How a page inside the app differs from a page in a browser tab, and the rules that keep it working.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/writing-html-for-your-app

What the app runtime exposes to your page - contacts, SMS, notifications, device info, biometrics - and the rules for calling it correctly

### 1. Rule 1 - always check first

window.WebToApk only exists inside your built app. In a browser it is missing.

So always check before you call. If you do not, your page breaks everywhere except inside the app.

Some things need no check at all: navigator.vibrate(), speechSynthesis and Notification already work - the app connects them for you. Just use the normal web code.

```
// GOOD — safe everywhere
if (window.WebToApk) {
  WebToApk.playClick();
}

// BAD — this breaks your page in a browser
WebToApk.playClick();
```

### 2. Rule 2 - some answers come back later

Reading contacts, SMS or the call log takes time. So these do not answer straight away. If they did, your app would freeze.

You give the call a name (an id). The answer arrives later as an event. You listen for that event.

Event names: appmint:contacts, appmint:calllog, appmint:sms, appmint:sms-received, appmint:notification-action.

```
// 1. Listen for the answer
window.addEventListener('appmint:contacts', function (e) {
  if (e.detail.error) {
    alert('Problem: ' + e.detail.error);
    return;
  }
  console.log(e.detail.contacts);
});

// 2. Ask the question ('my1' is any name you choose)
WebToApk.listContacts('my1', 50, 0);
```

### 3. Rule 3 - two switches must be ON

A phone feature needs TWO things:

1. You turned it on in Step 3 (Permissions) when you built the app. If not, you get error 'not_enabled' and the user sees nothing.

1. The user said Yes on the phone. If they said No, you get error 'permission_denied'.

Always handle both errors so the user knows what happened.

Easier way: pickContact() and composeSms() need NO permission at all. Use them when they fit - they do the same job with less trouble.

```
window.addEventListener('appmint:contacts', function (e) {
  if (e.detail.error === 'not_enabled') {
    alert('Turn on Contacts when you build the app');
  } else if (e.detail.error === 'permission_denied') {
    alert('Please allow contacts access');
  } else {
    showContacts(e.detail.contacts);
  }
});
```

### 4. Notifications with pictures and buttons

notify() takes a list of options. You can add a big picture, an icon, buttons, and a progress bar.

channel can be: urgent, default, quiet, or ongoing.

Use ongoing:true for a notification the user cannot swipe away. Note: they can still remove it from Android settings. No app can make one that is impossible to remove.

Use tag to give it a name. Sending again with the same tag replaces the old one instead of adding a new one.

```
WebToApk.notify(JSON.stringify({
  title: 'Order shipped',
  body: 'Arriving Tuesday',
  channel: 'urgent',
  image: 'https://mysite.com/box.jpg',
  actions: [{ id: 'track', label: 'Track' }],
  tag: 'order-482'
}));

// Know which button the user pressed
window.addEventListener('appmint:notification-action', function (e) {
  if (e.detail.actionId === 'track') showTracking();
});
```

### 5. Phone information and fingerprint

getDeviceInfo() needs no permission. It gives you the Android version, the version ID (buildId), the phone model, screen size, battery level, and more.

About device ID: there is NO IMEI or serial number. Android blocked this for every app from Android 10. Use getInstallId() instead - a fixed ID for this install that stays the same after updates.

```
var info = JSON.parse(WebToApk.getDeviceInfo());
info.android.release;      // "14"
info.android.buildId;      // "TQ3A.230805.001"  <- version ID
info.hardware.model;       // "Pixel 7"
info.runtime.batteryLevel; // 82

// Fingerprint
window.__webToApkAuth = window.__webToApkAuth || {};
window.__webToApkAuth['unlock'] = function (json) {
  var r = JSON.parse(json);
  if (r.ok) showMyApp();
};
WebToApk.authenticateBiometricEx('unlock', JSON.stringify({
  title: 'Unlock',
  allowDeviceCredential: true
}));
```

### 6. Make your page fill the screen

When you turn on Fullscreen, the app hides the Android bars for you. But add this CSS so your content is not hidden under the phone's notch.

Important: Fullscreen hides the ANDROID bars (clock, battery, back buttons). Your app's own coloured bar at the top is a different switch called 'Show top bar'. If you still see a bar after turning on Fullscreen, that is the one to turn off.

Also: test your app rotated. The notch moves to the side in landscape.

```
body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  min-height: 100vh;   /* old phones */
  min-height: 100dvh;  /* correct when bars are hidden */
}
```

### 7. Downloads keep the filename you chose

Your normal download code already works. When your page saves a file - a PDF report, a CSV export, a backup - the app catches it and opens the Android 'Save as…' sheet with YOUR filename already filled in.

This covers every usual way of doing it: <a download="...">, a.click() from code, html2pdf / jsPDF, FileSaver.js saveAs(), and window.open() on a blob URL. A File object brings its own name with it.

If you would rather ask directly instead of building an <a> tag, use AppMint.downloadFile().

One thing to know: the name lives only in your page's JavaScript - Android never sees it on its own. So set download= (or pass a name) every time, or the file is saved as 'download'.

```
// The usual way — saves as Site_Report_2026-08.pdf
const blob = await html2pdf().from(el).outputPdf('blob');
const a = document.createElement('a');
a.download = 'Site_Report_2026-08.pdf';
a.href = URL.createObjectURL(blob);
a.click();

// Or ask directly
AppMint.downloadFile(base64String, 'Ledger_Q3.csv', 'text/csv');
AppMint.saveBlob(myBlob, 'Backup.json');
```

### 8. Make the Back button do what YOUR app expects

If your app changes screens by showing and hiding elements (no URL changes, no history.pushState), Android's Back button cannot see those screens - its history is empty, so Back exits the app from anywhere.

Register a back handler and decide yourself: return true when you handled the press (closed a menu, went back a screen), return false to let the normal behaviour run - page history back, then the exit confirmation, then exit.

Apps that use history.pushState for every screen do not need this: Back already walks their history. And don't worry about freezing the app - if your handler ever hangs, the phone's Back keeps working natively after a short moment.

```
AppMint.setBackHandler(() => {
  if (isMenuOpen)   { closeMenu();  return true; }   // consumed
  if (screen !== 'home') { goTo('home'); return true; }
  return false;   // nothing open — normal exit behaviour
});

// Or listen instead: e.preventDefault() consumes the press
window.addEventListener('appmint:back', e => {
  if (closeTopmost()) e.preventDefault();
});
```

### 9. Receive what people share to your app - links, photos, videos, files

Turn on 'Receive shares from other apps' in the build wizard and tick what your app accepts: text and links, data files (JSON, CSV, TXT, XML, Markdown, GPX, TCX, FIT), photos, videos, audio, documents (PDF, Word, Excel, PowerPoint). Your app then appears in the Share menu of every other app for exactly those kinds - a notes app for text, a player for videos.

A link or text (sharing a YouTube video from the YouTube app sends its link) is read with WebToApk.getSharedText() and announced as appmint:shared. A file is asked for with AppMint.getOpenedFile() - ask whenever you are ready, the file waits for you. This matters for React, Vue and Angular apps: they finish starting AFTER the page loads, so an app that only listened for the event used to miss the file and just show its home screen.

f.kind tells you what arrived: image, video, audio, document or data. Photos, videos and audio come as f.url - a streamable, seekable address you put straight into <video src>, <img src> or <audio src>, so a 300 MB clip never has to fit in memory; f.getFile() fetches the File when you really need the bytes. Data files and documents also come with f.file, plus f.text for text formats and f.base64 for small binaries as shortcuts. A photo shared with a caption delivers the caption as shared text too.

```
// A link or text someone shared
const shared = JSON.parse(WebToApk.getSharedText() || 'null');
if (shared) saveLink(shared.url || shared.text);
window.addEventListener('appmint:shared', e => saveLink(e.detail.url || e.detail.text));

// A photo, video, audio clip, document or data file — ask on startup, however late
const f = await AppMint.getOpenedFile();   // null if opened normally
if (f) {
  if (f.kind === 'video')         player.src = f.url;                 // streams, seekable
  else if (f.kind === 'image')    img.src = f.url;
  else if (f.kind === 'document') await upload(await f.getFile());   // a real File
  else importActivity(f.text ?? await f.file.text());               // data files
}

// Or listen, if you prefer
window.addEventListener('appmint:fileopen', e => handle(e.detail));
```

### 10. Bluetooth sensors - standard Web Bluetooth

Heart-rate straps, cadence and speed pods, power meters, smart trainers, scales - anything that speaks Bluetooth LE.

Use navigator.bluetooth, exactly the same code you would write for Chrome on a desktop. AppMint provides it inside the app; a plain Android WebView has none, which is why this code does nothing in other app builders.

The device chooser is drawn by the app, like the browser's - your page can only reach the device the user picked.

Turn on the Bluetooth permission in Step 3. If your code mentions navigator.bluetooth, AppMint turns it on for you when you pick your ZIP.

Not available: getDevices(), watchAdvertisements() and requestLEScan() - they reject with NotSupportedError, so check before using them.

```
const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['heart_rate'] }]
});
const server  = await device.gatt.connect();
const service = await server.getPrimaryService('heart_rate');
const chr     = await service.getCharacteristic('heart_rate_measurement');

chr.addEventListener('characteristicvaluechanged', e => {
  const v = e.target.value;   // a DataView
  const bpm = (v.getUint8(0) & 1) ? v.getUint16(1, true) : v.getUint8(1);
  document.getElementById('bpm').textContent = bpm;
});
await chr.startNotifications();

device.addEventListener('gattserverdisconnected', () => showReconnect());
```

### 11. Photo upload - the Android photo picker, no permission

Use a normal file input. Nothing else to add.

In the app, <input type="file" accept="image/*"> opens the Android photo picker: the user's photos in a grid, and your page gets only the ones they choose. No storage permission, no 'Allow access to photos?' popup. It works on old phones too - Google Play services installs the picker there.

- accept="image/*" - photos only
- accept="video/*" - videos only
- accept="image/*,video/*" - both
- add multiple - the user can pick several
- add capture="environment" - opens the camera instead (needs Camera ticked in Step 3)

Mix in other files (accept="image/*,.pdf") and the normal file picker opens instead, so the PDF can be chosen too.

```
<input type="file" id="photos" accept="image/*" multiple>

<script>
document.getElementById('photos').onchange = function (e) {
  for (const file of e.target.files) {
    const img = document.createElement('img');
    img.src = URL.createObjectURL(file);
    document.body.appendChild(img);
  }
};
</script>
```

### 12. Scan a QR code or barcode - one line

AppMint.scanCode() opens Google's scanner screen. The user points the camera, and you get the code back.

No camera permission. No video element. Nothing to draw. The scanner zooms in by itself for small codes. The first time on a phone, Google Play services downloads the scanner (a few seconds).

The answer has value (the text in the code) and format (qr_code, ean_13, …). For common QR codes you also get the parts ready: url, wifi (ssid, password), phone, email, sms, geo, contact.

If ok is false, code tells you why: cancelled (the user closed it), unavailable (no Google Play services, or the download failed), busy (a scan is already open).

AppMint.scanCode only exists inside the app - check for it first.

```
async function scan() {
  if (!window.AppMint || !AppMint.scanCode) return;   // in a browser

  const r = await AppMint.scanCode({ formats: ['qr_code'] });
  if (!r.ok) return;                                  // closed, or no scanner

  console.log(r.value);          // the text inside the code
  if (r.url) location.href = r.url.url;
}

// Any code type: AppMint.scanCode()
// Let the user type it when it will not scan: AppMint.scanCode({ manualInput: true })
```

### 13. Passkeys - sign in with fingerprint or face, no password

If your website already has passkeys, they now work inside your app too. A normal Android WebView cannot do passkeys; AppMint connects navigator.credentials to Android's passkey manager, so libraries like SimpleWebAuthn, Hanko, Corbado or Auth0 work unchanged.

You need a server that makes passkey options and checks the answer (for example SimpleWebAuthn on your backend). A passkey cannot be checked inside the page.

Two things to set up once:

1. Your website must say it trusts the app. Put the file from AppMint.passkey.assetLinks() at https://YOUR-DOMAIN/.well-known/assetlinks.json. Take it from the app installed FROM Google Play - Play signs your app with its own key, so the file from a test APK will not match Play users. The domain must be your server's rpID, exactly (www and no-www are different).

1. Your server must accept the app's origin. The answer from the app says origin 'android:apk-key-hash:…' instead of https://… - get that value from AppMint.passkey.origin() and add it to your server's allowed origins.

Errors: NotAllowedError = the user cancelled or has no passkey on this phone. InvalidStateError = this passkey already exists. SecurityError = assetlinks.json does not list the app.

Passkeys need Android 9 or newer with Google Play services - AppMint.passkey.isAvailable() tells you. Passkey autofill in a text field (mediation: 'conditional') is not available in apps; start sign-in from a button.

```
// Your normal passkey code works as it is:
const cred = await navigator.credentials.get({ publicKey: options });

// Or with your server's JSON options (SimpleWebAuthn style):
const options = await (await fetch('/passkey/login-options')).json();
const answer = await AppMint.passkey.get(options);
await fetch('/passkey/login-verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(answer)
});

// Once, on the Play-installed app — copy these to your server setup:
console.log(JSON.stringify(AppMint.passkey.assetLinks(), null, 2));
console.log(AppMint.passkey.origin());
```

### 14. {exampleCount} ready-made examples - open them here

Working code you can copy: send an SMS, read contacts, show a notification with a picture, fingerprint lock, phone information, saving files, Bluetooth sensors, and more. Each one is short and explained in simple words.

Opens inside AppMint. You can search it, and you can select the text to copy it into your page.

The same screen also has 'All methods' - the full list of all {methodCount} things your app can call. That list is built from the app runtime itself, so it always matches exactly what your app can do.

[Open examples & method list](appmint:api-reference)

### 15. Save the examples to your phone or computer

Saves three files to Downloads/AppMint/Guides:

- Examples - the {exampleCount} examples above
- Method list - all {methodCount} methods
- index.html - a ready test page

The test page has buttons for device info, vibration, notifications and the contact picker. Build it as an app to see everything working, then change it into your own app. It also opens fine in a normal browser - nothing breaks, it just says it is not inside the app.

**Download** (in the app these are saved to your phone by the button on this step):

- [AppMint-examples.md](https://freewebtoapk.com/docs/files/hybrid_examples.md) - 32 KB
- [AppMint-all-methods.md](https://freewebtoapk.com/docs/files/hybrid_api_reference.md) - 59 KB
- [index.html](https://freewebtoapk.com/docs/files/hybrid_starter.html) - 6 KB


---

# React & Framework Apps

> Build settings, routing and asset paths for framework projects that have to run from a file:// origin.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/react-and-framework-apps

Convert React, Next.js, Astro & Vue Projects

### 1. ✅ Supported Frameworks

You can convert apps built with these popular frameworks:

- React (Vite) - Most popular, recommended
- Next.js - React-based, pages & app router
- Astro - Fast static sites with React components
- Vue.js (Vite) - Vue single-page apps

All of these work automatically - just upload your project ZIP!

### 2. 📦 Two Ways to Upload

Option A - Upload Source Code (Easiest):  
Just zip your project folder as-is and upload it. Our cloud will build it for you automatically.

Option B - Upload Pre-Built Files:  
Run 'npm run build' on your computer first, then zip the output folder (dist/, build/, or out/) and upload that.

💡 Option A is recommended for most users - no terminal or coding needed!

### 3. 📁 How to Prepare Your ZIP

1. Open your project folder on your computer
2. Select ALL files inside (including package.json, src/, public/, etc.)
3. Right-click → 'Compress' or 'Send to ZIP'

⚠️ Make sure package.json is at the root of the ZIP, not inside a subfolder.

You can also download your project from GitHub as a ZIP directly.

### 4. 🚀 Generate Your APK

1. Select 'Offline ZIP' mode in Step 1
2. Choose your project ZIP file
3. The app will detect your framework automatically
4. Fill in App Name, Icon, Splash Screen, etc.
5. Click 'Generate APK' - done!

📶 Internet is required during generation for source code projects.

### 5. 🎯 Tips for Best Results

- Keep your app a single-page app (SPA) - it works best
- If your app uses a backend/API, keep the backend hosted online
- Images and assets in the 'public/' folder are included automatically
- Test your app in a browser first to make sure it works

### 6. ❌ What Won't Work

- Server-side features (database queries, server APIs built into the app)
- Apps that need Node.js or a server to run
- WordPress, Shopify, or CMS-based websites
- Svelte and Angular projects (coming soon!)

If your app works in a browser without a server, it will work as an APK!

### 7. 📥 Download Sample Projects

Try these ready-made sample projects to test the feature. Download any ZIP below, then use it in Step 1 with 'Offline ZIP' mode to generate an APK instantly!

[⬇️ React (Vite) Sample](https://freewebtoapk.com/samples/vite-react-test-app.zip)

### 8. 📥 Next.js Sample

A multi-page Next.js app with routing - great for testing page navigation in your generated APK.

[⬇️ Next.js Sample](https://freewebtoapk.com/samples/nextjs-test-app.zip)

### 9. 📥 Astro Sample

A fast static site built with Astro and React components - perfect for content-heavy apps.

[⬇️ Astro Sample](https://freewebtoapk.com/samples/astro-test-app.zip)

### 10. 📥 Single HTML Sample

Minimal single-file offline test (just index.html). Great for quick sanity checks when troubleshooting blank screens.

[⬇️ Single HTML Sample](https://freewebtoapk.com/samples/single-html-test.zip)

### 11. 📥 HTML + CSS Sample

Simple two-file offline test (index.html + style.css) to verify external CSS loading in generated apps.

[⬇️ HTML + CSS Sample](https://freewebtoapk.com/samples/html-css-test.zip)


---

# App Icon & Splash Screen

> Adaptive icons, the splash screen, and the sizes Android actually uses.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/app-icon-and-splash-screen

Image Size Requirements & Best Practices

### 1. App Icon - Required Size

The app icon is resized to multiple densities automatically. For the best result:

✅ Size: 512 × 512 pixels  
✅ Format: PNG with transparency (ARGB)  
✅ Shape: Square (1:1 aspect ratio)

⚠️ Non-square images are automatically center-cropped before scaling. This means edges and sides outside the center square WILL be cut off. Always use a square image to avoid unwanted cropping.

```
Recommended: 512 × 512 px PNG

Images larger than 4096 × 4096 px are rejected.
Non-square images → center-cropped to square → scaled to 512×512.
```

### 2. App Icon - What Happens Internally

After you upload your icon, the generator creates icons at all required Android densities:

- mdpi  - 48 × 48 px
- hdpi  - 72 × 72 px
- xhdpi - 96 × 96 px
- xxhdpi - 144 × 144 px
- xxxhdpi - 192 × 192 px

Starting from a sharp 512×512 source ensures all densities are crisp. Using a smaller source (e.g. 96×96) will result in blurry icons on high-density screens.

```
Source: 512 × 512 px
  → mdpi   (48px)    ✅ crisp
  → hdpi   (72px)    ✅ crisp
  → xhdpi  (96px)    ✅ crisp
  → xxhdpi (144px)   ✅ crisp
  → xxxhdpi(192px)   ✅ crisp
```

### 3. Splash Screen Image - Required Size

The splash screen image fills the entire screen background. For the best result:

✅ Size: 1080 × 1920 pixels  
✅ Aspect ratio: 9:16 (portrait)  
✅ Format: PNG

⚠️ Images with a different aspect ratio will appear stretched or cropped on most phone screens. A 9:16 image fits nearly all Android phones without distortion.

```
Recommended: 1080 × 1920 px PNG (9:16 portrait)

Common wrong sizes that cause stretching:
  ❌ 1080 × 1080 (square)
  ❌ 1920 × 1080 (landscape)
  ❌ 512 × 512   (too small / wrong ratio)
```

### 4. Splash Screen - Design Tips

Since the splash image fills the whole screen, follow these design guidelines:

- Place your logo/branding in the center of the image - safe zone is roughly 600×600 px in the middle
- Keep edges simple (solid color or gentle gradient) so they look good if slightly cropped on unusual screen ratios
- Avoid putting important text near the very top or bottom - status bar and navigation bar may overlap these areas
- Use PNG-24 (24-bit with alpha) for sharp results

### 5. No Splash Image - Color Only Mode

If you don't upload a splash image, the splash screen will show:

- A solid background using your chosen splash color
- Your app icon in the center
- Your app name below the icon

This is the default mode and looks professional on all screen sizes without any image size concerns.

### 6. Quick Checklist Before Generating

Before you tap Generate, confirm:

☑️ Icon is exactly square (equal width and height)  
☑️ Icon is at least 512 × 512 px  
☑️ Icon is saved as PNG  
☑️ Splash image is 1080 × 1920 px (or any 9:16 ratio)  
☑️ Splash image is saved as PNG  
☑️ Logo/branding centered in the splash image  
☑️ No critical content near splash image edges


---

# ZIP to APK

> Upload a React, Vue or plain HTML project and have it bundled into an APK unchanged.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/import-a-zip-project

Turn a web project ZIP into a real APK

### 1. When to use it

You already have a web project - React, Vite, Next.js (static export), Astro, or plain HTML/CSS/JS - and want it as a real Android app. Zip the project (or its built output folder) and import it. No AI round, no Mints.

### 2. How

Home → ZIP to APK → Choose project ZIP. Set the app name, icon and package, then build - you get a real signed APK, ready for the Play Store. Free builds carry a small watermark until you Unlock.

### 3. What your ZIP needs

An index.html at the top level (or a standard build-output folder like dist/ zipped from inside), with assets referenced by relative paths. If it opens in a browser from the folder, it will work as an app.

### 4. Source projects are built on your phone

A ZIP with a package.json (React, Vite) is compiled on the device: its packages install and Vite runs in the built-in toolchain, which needs an arm64 phone and an internet connection for the install. If the code reads VITE_* variables, an Environment step appears so you can fill them in. A prebuilt dist/ folder skips all of this.

### 5. Update it later

Menu → Zip to APK Updater lists every app you built from a ZIP. Replace the ZIP (from your phone or a direct link), change the version or the icon, then Rebuild - same package name and signing key, so the update installs over the app people already have.

### 6. Everything else still applies

ZIP-imported apps get the same powers as AI-built ones - notifications, AdMob, In-App Selling, deep links, Remote Update. The guides in this list work for both.


---

# HTML to APK

> Paste one self-contained HTML page, or upload the .html file, and get a signed APK - no AI round, no Mints.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/html-to-apk

Paste code or upload one HTML file

### 1. When to use it

You have one self-contained page: a tool, a calculator or a mini-game that ChatGPT, Claude or Gemini wrote for you, or code you wrote yourself. Paste it or upload the .html file and get a real signed APK. No AI round, no Mints.

### 2. How

Home → HTML to APK. Paste your code into the box, or tap Upload HTML File (any size - it is streamed into the build, never loaded into memory). Then name the app, pick the icon and package, and build. Free builds carry a small watermark until you Unlock.

### 3. Keep it to one file

Only the HTML itself is packaged. Put your CSS in a <style> tag and your JavaScript in a <script> tag, or load libraries from full https:// URLs. A page that points at ./style.css or local images is flagged before the build. For several files, zip the folder and use ZIP to APK instead.

### 4. Libraries from a CDN

Scripts, fonts and styles loaded from https:// need an internet connection when the app opens them. For an app that works fully offline, inline them into the page.

### 5. Camera, microphone and location

The build reads your page: getUserMedia, <input capture>, navigator.geolocation and Web Bluetooth arm the matching Android permissions automatically, so the system prompt appears when your page asks for them.

### 6. Update it later

Menu → Single HTML Updater lists every app you built this way. Replace HTML (upload a file or paste code), then Rebuild - same package name and signing key, so the update installs over the app people already have. Raise the version first if you publish on Google Play.


---

# JSX / React Runtime

> Run raw JSX with no build step by loading React and Babel at runtime.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/jsx-react-runtime

Run Raw JSX & React Code Directly Without a Build Step

### 1. What Is JSX Runtime?

JSX is a syntax extension used by React that lets you write HTML-like code inside JavaScript. Browsers and WebView cannot run JSX directly - it needs to be compiled first.

The JSX Runtime feature loads React and Babel Standalone into your app at runtime, so raw JSX code just works - no build tools needed.

### 2. When to Use This

Enable JSX Runtime when:

- You write React/JSX code in the Custom JS field
- Your HTML files contain <script type="text/babel"> tags
- You generated JSX code with AI
- You want to use React components without setting up a build pipeline

⚠️ NOT needed if you upload a ZIP project - the built-in esbuild bundler already handles JSX for ZIP uploads.

### 3. How to Enable

1. Go to Step 4 (Advanced Features) in the wizard
2. Toggle ON '⚛️ JSX / React Runtime'
3. Write your JSX in the Custom JS field or in your HTML
4. Generate your APK as normal

The app will load React 18 + Babel from CDN on first page load.

### 4. Writing JSX in Custom JS

With JSX Runtime enabled, you can write React code directly in the Custom JS field:

const App = () => (  
<div>

```
<h1>Hello from React!</h1>
<p>This JSX is compiled at runtime</p>
```

</div>  
);

const root = ReactDOM.createRoot(  
document.getElementById('root')  
);  
root.render(<App />);

Babel will automatically transpile the JSX before execution.

### 5. Using <script type="text/babel"> in HTML

If your website or offline HTML uses script tags with JSX, mark them with type="text/babel":

<script type="text/babel">  
function Greeting({ name }) {

```
return <h1>Hello, {name}!</h1>;
```

}  
ReactDOM.createRoot(document.getElementById('app'))

```
.render(<Greeting name="World" />);
```

</script>

Babel Standalone automatically finds and compiles these tags.

### 6. Important Notes

- Requires internet connection on first load (CDN)
- Adds ~200-500ms startup delay for Babel compilation
- React 18 and ReactDOM 18 are loaded automatically
- Works alongside all other features (ads, push, side menu, etc.)
- For production apps with large codebases, consider using the ZIP upload with esbuild bundling instead - it's faster and works offline


---

# Stripe Payments

> Take card payments for physical goods and services, where Play billing is not required.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/stripe-payments

Charge users in AI-generated apps with your own Stripe account - keys stay server-side, fulfillment is webhook-verified

### 1. What this gives your app

Lets apps you generate charge real money - paywalls, 'Pro' upgrades, buy buttons - through Stripe Checkout.

It's YOUR Stripe account: your keys, your money, paid straight to you. AppMint takes no cut and no payment liability (no Stripe Connect). You connect Stripe ONCE in Settings; every app you generate reuses it - you only describe what to sell, never re-enter keys.

The AI writes all the payment code. Your secret key never ships inside the app - it lives in your Supabase backend.

### 2. First connect Supabase (required)

Stripe payments need a secure server to hold your secret key and to confirm payments - that server is your Supabase project. So connect and enable Supabase first (Settings → BACKEND - SUPABASE) - the chapter '🗄️ Supabase Backend (Connect It Once)' at the top of this guide walks through it.

If Supabase isn't active you'll see 'Stripe keys saved, but payments also need Supabase active'. AppMint pushes your Stripe secret into your Supabase functions automatically on deploy - it's never put in the generated app.

### 3. Get your Stripe keys (start in test)

On a computer:

1. Open the Stripe Dashboard and stay in test mode / a sandbox while you build (Stripe now calls the test environment a 'sandbox'; older accounts show a Test/Live toggle). No real charges happen here.
2. Go to Developers → API keys.
3. Copy the 'Publishable key' (starts with pk_test_…) and reveal + copy the 'Secret key' (starts with sk_test_…).

Use the standard Secret key (sk_…), not a Restricted key (rk_…) - AppMint validates and pushes the sk_ secret. No merchant approval is needed to build and test the whole flow before activating live payments.

[Open Stripe API keys](https://dashboard.stripe.com/test/apikeys)

### 4. Connect Stripe in AppMint

Open AI Studio → Settings → scroll to 'PAYMENTS - STRIPE (OPTIONAL)' → 'CONNECT STRIPE (YOUR ACCOUNT)':

1. Leave 'Live mode' OFF for now (off = Test).
2. Paste your publishable key into the pk_test_… field.
3. Paste your secret key into the sk_test_… field (kept encrypted on this device).
4. Turn ON 'Enable Stripe payments for generated apps'.
5. Tap 'Validate & save Stripe keys'. AppMint checks the format, makes sure both keys are the same mode, and verifies the secret with Stripe. On success you'll see '● Connected (TEST)'.

### 5. What AppMint wires up for you

When you generate an app with payments, AppMint does the plumbing automatically - you don't touch Supabase or Stripe dashboards:

- Pushes your STRIPE_SECRET_KEY into your Supabase Edge Functions (encrypted, server-side only).
- Deploys a 'create-checkout' function (starts a Stripe Checkout session) and a 'stripe-webhook' function (confirms payments).
- Registers the webhook with Stripe and stores its signing secret.
- Creates an 'entitlements' table so the app knows who paid.

The publishable key (pk_) is the only Stripe value that ships in the app - that key is safe to be public.

### 6. Describe your paywall - the AI builds it

Just say what you want in plain English. The AI adds the buy button, the checkout call, and gates the paid features for you:

- 'Charge $5 one-time to unlock the Pro theme.'
- 'A $9/month subscription that removes ads.'
- 'Sell a downloadable PDF for $19.'

You never paste keys or prices into the chat as config - only the intent. Access is unlocked only after Stripe confirms the payment via the webhook, never from a client-side 'paid' flag, so it can't be faked.

### 7. Test a payment end-to-end

While in Test mode, no real money moves. Run the full flow:

1. Open your app and tap the buy/upgrade button.
2. On the Stripe Checkout page, pay with the test card:

```
 4242 4242 4242 4242, any future expiry, any CVC, any ZIP.
```

1. You're returned to the app and the paid feature unlocks.
2. Check Stripe Dashboard (Test mode) → Payments - you'll see the test charge.

If it unlocks, your webhook + entitlements are wired correctly.

```
4242 4242 4242 4242   exp: any future date   CVC: any 3 digits
```

### 8. Go Live when you're ready

1. Activate your Stripe account for live payments (Stripe Dashboard → 'Activate' / complete business details).
2. In Stripe, switch from sandbox/test to live mode and copy your LIVE keys (pk_live_… and sk_live_…) from Developers → API keys.
3. In AppMint → Settings → Payments: turn ON 'Live mode', paste the pk_live_/sk_live_ keys, and tap 'Validate & save'. The badge turns to '● Connected (LIVE)'.
4. Rebuild your app.

AppMint blocks mixing test and live keys, and switching mode re-points the deployed secret - test and live never coexist on one app, so you can't accidentally ship test keys.

### 9. If something doesn't work

- 'Stripe keys saved, but payments also need Supabase active' → enable Supabase first (step 2).

- 'You selected TEST but the keys are LIVE' (or vice-versa) → the mode toggle must match your keys' prefix (pk_test/sk_test vs pk_live/sk_live).

- 'Stripe rejected the key' → the secret key is wrong or revoked. Re-copy it from Developers → API keys.

- Payment succeeds but the feature stays locked → the webhook didn't reach Supabase. Rebuild/redeploy so AppMint re-registers the webhook, and confirm the app's Supabase project is the one you connected.

- Can't activate a live account → Stripe does NOT onboard merchants in some countries (including India). Test mode still works everywhere for building; for live payments there you'd need a Stripe-supported country or a different provider.


---

# AdMob Integration

> Banner, interstitial and rewarded ads, the consent rules, and the mistakes that stop ads serving.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/admob-ads

Monetization Setup

### 1. Create AdMob Account

Sign up for a Google AdMob account. You'll need a Google account to get started. AdMob is Google's mobile advertising platform.

[Go to AdMob](https://admob.google.com)

### 2. Add Your App

In AdMob dashboard:

- Click 'Apps' in the sidebar
- Click 'Add App'
- Select 'No' for 'Is your app listed on a supported app store?'
- Enter your app name
- Select 'Android' as platform
- Click 'Add'

### 3. Get App ID

After creating your app:

- Copy the App ID shown (format: ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX)
- This is different from your Ad Unit ID
- You'll use this in AndroidManifest.xml

```
App ID format:
ca-app-pub-1234567890123456~1234567890
```

### 4. Create Ad Unit (Banner)

In your AdMob app:

- Click 'Ad units' tab
- Click 'Add ad unit'
- Select 'Banner'
- Enter ad unit name (e.g., 'Main Banner')
- Click 'Create ad unit'
- Copy the Ad Unit ID

```
Banner Ad Unit ID format:
ca-app-pub-1234567890123456/1234567890
```

### 5. Setup in Web2APK Generator

In the generator app:

1. Enable 'Ads' toggle in Step 3
2. Select ad placement (Top or Bottom)
3. Paste your AdMob Banner Ad Unit ID
4. Continue with other settings and generate your APK

```
Ad Unit ID (not App ID):
ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY
```

### 6. Test Ads in Your App

During development, use Google's official test IDs to avoid policy violations. Copy-paste these into the generator:

📋 AdMob App ID:  
ca-app-pub-3940256099942544~3347511713

📋 Banner Ad Unit ID:  
ca-app-pub-3940256099942544/6300978111

📋 Interstitial Ad Unit ID:  
ca-app-pub-3940256099942544/1033173712

📋 Rewarded Ad Unit ID:  
ca-app-pub-3940256099942544/5224354917

📋 Publisher ID:  
pub-3940256099942544

📋 Developer Website:  
https://example.com

These test IDs show real-looking ads without generating revenue or violating policies. Replace with your real IDs for production.

```
Test IDs for Generator:

AdMob App ID:       ca-app-pub-3940256099942544~3347511713
Banner Ad ID:       ca-app-pub-3940256099942544/6300978111
Interstitial ID:    ca-app-pub-3940256099942544/1033173712
Rewarded Ad ID:     ca-app-pub-3940256099942544/5224354917
Publisher ID:       pub-3940256099942544
Developer URL:      https://example.com
```

### 7. Interstitial Ads

Interstitial ads are full-screen ads that cover the entire app interface. Users can close them to return to the app.

📺 How to Enable:

1. Toggle ON 'Enable Interstitial Ad' in Step 3
2. Enter your Interstitial Ad Unit ID (or leave empty for test ads)
3. Choose a trigger mode:

🔄 After Navigations (default):  
The ad shows after every N page navigations. For example, if set to 4, the ad appears after the 4th, 8th, 12th page load, and so on.

📱 App Open:  
The ad shows once immediately after the splash screen, when the app first opens.

⚠️ You can enable either Interstitial OR Rewarded - not both at the same time.

```
Example: Action Count = 4

Page 1 → No ad
Page 2 → No ad
Page 3 → No ad
Page 4 → 📺 Interstitial Ad shown!
Page 5 → No ad
Page 6 → No ad
Page 7 → No ad
Page 8 → 📺 Interstitial Ad shown!
...
```

### 8. Rewarded Ads

Rewarded ads are full-screen video ads that users watch in exchange for a reward. They provide higher revenue than banner or interstitial ads.

🎁 How to Enable:

1. Toggle ON 'Enable Rewarded Ad' in Step 3
2. Enter your Rewarded Ad Unit ID (or leave empty for test ads)
3. Choose a trigger mode:

🔄 After Navigations (default):  
Similar to interstitial - the ad shows after every N page loads. Set the 'Action Count' to control frequency. Default is 4.

📱 App Open:  
The reward video shows once when the app first opens after splash.

💡 What is Action Count?  
The number of page navigations between each ad. Lower = more ads (more revenue but worse UX). Higher = fewer ads (better UX but less revenue). Recommended: 3-5.

⚠️ Google policy: rewarded ads need the user's OK. In After Navigations and App Open modes your app first shows a 'Watch an ad?' prompt with a 'No thanks' button; the ad plays only if they accept. For a 'watch ad to earn' button with no automatic ads, use On Demand.

```
Revenue comparison (approximate):

Banner Ads:       $0.10 - $0.50 per 1000 views
Interstitial Ads: $1 - $5 per 1000 views
Rewarded Ads:     $5 - $15 per 1000 views

Recommended Action Count:
Aggressive:  2-3 (more ads, more revenue)
Balanced:    4-5 (recommended)
Conservative: 6-10 (fewer ads, better UX)
```

### 9. Consent & Privacy Policy (Required)

⚠️ AdMob requires a consent mechanism for users in the EEA, UK, Switzerland, and US states.

This is handled automatically by the generated app using Google's User Messaging Platform (UMP). The app will:

- Show a consent dialog to EEA/UK/Switzerland users before displaying ads
- Show an opt-out dialog to users in applicable US states
- Only request ads after consent is obtained

What YOU must do:

1. In AdMob console → Privacy & messaging → Create a European regulations message
2. In AdMob console → Privacy & messaging → Create a US state regulations message
3. Set your Privacy Policy URL in the generator (Step 3 or Step 4)
4. Make sure your privacy policy mentions AdMob advertising

⚠️ Without this setup, AdMob may show a policy warning: 'Consent requirement: No CMP'

[Open AdMob Privacy & messaging](https://admob.google.com)

### 10. Ad Review Process

After publishing your app:

- AdMob will review your app (usually takes 24-48 hours)
- Initially, you'll see test ads
- Once approved, real ads will start showing
- Keep your app content policy-compliant

### 11. Enable Payments

To receive ad revenue:

- Go to 'Payments' in AdMob dashboard
- Add payment method (bank account or other options)
- Verify your address
- Set up tax information
- Payments are made monthly after reaching $100 threshold

### 12. Best Practices

✅ Banner Placement: Bottom banner is less intrusive and has better user experience

✅ Interstitial/Rewarded: Choose one, not both. Rewarded ads earn more but require user engagement

✅ Action Count: Start with 4-5 navigations between ads. Too frequent = bad reviews

✅ Test First: Always test with test ad units during development

✅ Monitor Performance: Check AdMob dashboard regularly for earnings and metrics

⚠️ Don't Click: Never click your own ads - this violates AdMob policy

⚠️ Quality Content: Ensure your app provides value and follows AdMob policies

💡 Pro Tip: Combine Banner (always visible) + Interstitial or Rewarded (periodic) for maximum revenue

### 13. Troubleshooting

Common issues and solutions:

- No ads showing: Check if you're using correct Ad Unit ID (not App ID)
- Test ads work but real ads don't: Wait for AdMob review to complete
- Ad request failed: Verify internet connection and AdMob account status
- Account suspended: Review AdMob policies and appeal if needed

[AdMob Help Center](https://support.google.com/admob)

### 14. Developer-controlled ads: place every ad yourself

Download the complete demo page below (Coin Runner): a banner inside the layout, an interstitial between levels, a 'Watch ad to earn 50 coins' button, a 300×250 rectangle, the app-open switch and a live log of every result. Zip it, upload it as an Offline ZIP, choose Developer-controlled with the prefilled test IDs, build - every button explains itself.

The options above are the Automatic mode: the app shows the banner and the full-page or rewarded ad for you. If you want every AdMob format and the freedom to put each one exactly where your page needs it, choose 'Ad Control → Developer-controlled' in Step 3 instead.

In this mode NOTHING is automatic. Enter one ad unit ID for each format you use - banner, medium rectangle (300×250), interstitial, rewarded, rewarded interstitial, app-open - and leave the rest empty. Your page then drives everything through window.AppMintAds:

- AppMintAds.banner.attach('#slot', {size:'banner'|'medium_rectangle'}) - a banner placed over the element you name, in a card, between list items, anywhere. It follows the element on scroll; detach() removes it. Up to two at once.
- await AppMintAds.load('interstitial') → {ok:true} or {ok:false, code:'no_fill'|'network'|'invalid_unit'|'consent'|'ad_free'|'disabled'}
- await AppMintAds.show('rewarded') → {shown:true, earned:true, reward:{type,amount}} or {shown:false, reason}
- AppMintAds.isReady('interstitial') - enable your button off this
- AppMintAds.appOpen.setEnabled(false) - pause the app-open ad while the user is mid-task

AppMintAds exists only inside the installed app - always feature-detect (if (window.AppMintAds) …) so the page still works in a browser. Google's rules still apply and the app enforces them: a rewarded ad only plays from the user's own tap (your 'Watch ad' button IS the opt-in), interstitials keep a 60-second gap, and never put an ad on top of a core action.

```
// Feature-detect: AppMintAds exists only in the installed app
const ads = window.AppMintAds;

// 1. A banner INSIDE your layout — <div id="ad-slot"></div> reserves the space
if (ads) {
  const r = await ads.banner.attach('#ad-slot', { size: 'banner' });
  console.log(r.ok ? 'banner ' + r.width + 'x' + r.height : 'no banner: ' + r.code);
}

// 2. A full-page ad at a natural break (between levels), never on every tap
async function levelFinished() {
  if (ads && ads.isReady('interstitial')) await ads.show('interstitial');
  showNextLevel();          // continues whether or not an ad was shown
}

// 3. A 'Watch ad to earn 50 coins' button — the tap is the user's opt-in
watchBtn.onclick = async () => {
  if (!ads) return;                                 // browser: no native ads
  // From a tap the ad plays. Without one (a timer, a route change) the app shows
  // AdMob's "Watch an ad? / No thanks" intro first and answers code 'declined'.
  const r = await ads.show('rewarded');
  if (r.earned) addCoins(r.reward.amount || 50);   // grant ONLY when earned
  else if (r.reason === 'ad_free') addCoins(50);    // premium user: grant without an ad
  else toast('No ad available right now');          // no popup, no Skip button
};

// 4. Preload and keep the button honest
ads?.load('rewarded').then(r => { watchBtn.disabled = !r.ok; });
```

**Download** (in the app these are saved to your phone by the button on this step):

- [admob-developer-demo.html](https://freewebtoapk.com/docs/files/admob-developer-demo.html) - 12 KB

### 15. Ad status events: know what happened to every request

Every developer-controlled ad reports its full life cycle on ONE event, appmint:ad, so you can log fills, react to failures and drive your own UI:

{ type, phase, slot?, code?, adCode?, message?, width?, height?, reward?, earned? }

- type: banner | mrec | interstitial | rewarded | rewarded_interstitial | app_open
- phase: loading → loaded | failed → opened → impression → clicked → closed, plus rewarded (a reward was earned) and show_failed
- code (on failed): no_fill | network | invalid_unit | internal - adCode is AdMob's own number, message its text
- slot: which banner slot, for banner/mrec

The promises give you the same answer per call; the event gives you everything, including ads you did not call show() for (an app-open ad, a banner refresh). In the Automatic mode AppMintAds still exists but answers code 'automatic_mode' - use the WebToApk.showInterstitialAd()/showRewardedAd() calls and the appmint:reward / appmint:ad-closed / appmint:ad-unavailable events there.

```
window.addEventListener('appmint:ad', e => {
  const a = e.detail;
  console.log(a.type, a.phase, a.code || '', a.message || '');
  if (a.phase === 'failed' && a.code === 'no_fill') analytics.track('ad_no_fill', a);
  if (a.type === 'rewarded' && a.phase === 'rewarded') console.log('earned', a.reward);
  if (a.type === 'banner' && a.phase === 'loaded') console.log('banner ' + a.width + 'x' + a.height + ' in ' + a.slot);
});

// What can this build serve? (guard it — in a browser AppMintAds is undefined)
if (window.AppMintAds) console.log(AppMintAds.config());
// → { control: 'developer', formats: { banner: true, mrec: false, interstitial: true, ... } }
```


---

# app-ads.txt Verification

> The one file AdMob needs on your domain before it will pay full rates.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/app-ads-txt

AdMob Publisher Verification (Required)

### 1. Why app-ads.txt is Required

Google AdMob now REQUIRES app-ads.txt file verification for all apps that show ads. Without this verification:

❌ Your ads may not serve properly  
❌ You may lose potential revenue  
❌ Your AdMob account may face restrictions

✅ With app-ads.txt: Higher ad fill rates and better CPM

### 2. Get Your Publisher ID

Your Publisher ID is the first part of your AdMob App ID:

- If your App ID is: ca-app-pub-1234567890123456~1234567890
- Your Publisher ID is: pub-1234567890123456

You need to enter this in the generator app.

```
Format:
pub-1234567890123456

Example:
ca-app-pub-1234567890123456~9876543210
         ↓
pub-1234567890123456
```

### 3. Get Your Developer Website

You must have a website URL where you'll host the app-ads.txt file. This can be:

- Your personal website
- Your company website
- A simple GitHub Pages site
- Any domain you own

Note: The website must be publicly accessible and use HTTPS.

```
Valid examples:
https://yourwebsite.com
https://yourdomain.com
https://username.github.io
```

### 4. Generate app-ads.txt in Generator

In the Web2APK Generator app (Step 3 - AdMob section):

1. Enter your AdMob Publisher ID (pub-XXXXXXXXXXXXXXXX)
2. Enter your Developer Website URL
3. Click 'Generate app-ads.txt' button
4. The file content will be displayed in a dialog
5. For premium users: File is automatically saved to Downloads/WebToApk/{AppName}/app-ads.txt

### 5. Upload to Your Website

Upload the app-ads.txt file to your website's root directory:

- File must be at: https://yourdomain.com/app-ads.txt
- Not in a subdirectory
- Must be plain text file
- Must be publicly accessible (no login required)

```
Correct:
https://yoursite.com/app-ads.txt ✅

Incorrect:
https://yoursite.com/folder/app-ads.txt ❌
https://yoursite.com/files/app-ads.txt ❌
```

### 6. File Content Format

Your app-ads.txt file should contain this exact format:

```
google.com, pub-1234567890123456, DIRECT, f08c47fec0942fa0

Replace 'pub-1234567890123456' with YOUR actual Publisher ID
```

### 7. Verify in AdMob Dashboard

After uploading the file:

1. Go to AdMob dashboard
2. Navigate to Settings > Account Information
3. Look for 'app-ads.txt' status
4. It may take 24-48 hours for Google to verify
5. Status should show 'Verified' when done

### 8. Test Your File

Before waiting for AdMob verification, test your file:

- Open browser and go to: https://yourdomain.com/app-ads.txt
- You should see the file content
- If you get 404 error, file is not in the correct location
- If you see HTML instead of text, wrong file type

[AdMob app-ads.txt Guide](https://support.google.com/admob/answer/9787911)

### 9. Common Issues & Solutions

❌ File not found (404): Upload to root directory, not in a folder

❌ Wrong format: Use EXACTLY the format shown (comma-separated, no extra lines)

❌ Wrong Publisher ID: Double-check your AdMob Publisher ID

❌ Website not accessible: Ensure HTTPS and no password protection

✅ Multiple Publisher IDs: Add each on a new line in the file

✅ Subdomain: If using subdomain (app.yoursite.com), file must be there too

### 10. GitHub Pages Example

If you don't have a website, use GitHub Pages (FREE):

1. Create a GitHub repository named: yourusername.github.io
2. Upload app-ads.txt file to the root
3. Enable GitHub Pages in repository settings
4. Your file will be at: https://yourusername.github.io/app-ads.txt
5. Use this URL as your Developer Website in the generator

[GitHub Pages Setup](https://pages.github.com)


---

# Sell In-App Products (IAP)

> Sell one-time unlocks and subscriptions from your own page, with live Play prices and offline entitlement checks.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/in-app-purchases

Google Play purchases from your own website or ZIP app

### 1. 📥 Get the guide + working demo app

Everything in this guide is also a PDF you can read offline, plus a complete demo app you can build and run today.

Tap below and both are saved to your phone under Downloads/AppMint/Guides:

- AppMint-InApp-Purchases-Guide.pdf - the full guide, including the Play Console steps and the React / Next.js examples
- iap-demo-index.html - a small game that sells three things: remove ads (one-time), a level pack (one-time) and a monthly season pass

To try the demo: zip iap-demo-index.html on its own, upload it in the stepper, and follow the guide. It is the fastest way to see a real purchase work end to end before you touch your own app.

**Download** (in the app these are saved to your phone by the button on this step):

- [AppMint-InApp-Purchases-Guide.pdf](https://freewebtoapk.com/docs/files/AppMint-InApp-Purchases-Guide.pdf) - 257 KB
- [iap-demo-index.html](https://freewebtoapk.com/docs/files/iap-demo-index.html) - 10 KB

### 2. What is this? (in plain words)

Your app can sell things - a Pro upgrade, extra levels, a subscription - and Google collects the money and pays it to you every month.

WE WILL BUILD ONE EXAMPLE TOGETHER, all the way through this guide:

```
A game that sells two things
  • 'Levels 11-20'      ₹99  paid once, kept forever
  • 'Remove ads'        ₹49  every month
```

You will end up adding four lines to your page. That is the whole job - there is no purchase code to write, and if you have never done this before you will still be fine.

You do NOT need to know programming beyond copy-paste, and you do NOT need a server, a database or a payment company account. Google Play does the hard parts:

- Shows the payment screen (card / UPI / carrier billing)
- Converts your price into every country's currency
- Remembers who bought what - even after reinstall
- Sends the money to your bank

AppMint takes 0% - the sale goes straight to YOUR Google Play account.

Works the same for Website → APK, ZIP → APK and AI-built apps.

### 3. What you need before you start

Just four things:

1. Your website or HTML/ZIP app (the thing you turn into an APK).
2. Something to sell - decide what buyers get (e.g. 'Pro version': no limits, extra content).
3. A Google Play developer account - one-time $25 fee at play.google.com/console. You need this to publish ANY app on the Play Store, not just paid ones.
4. About 1 hour, total, spread over the steps below.

Important to know up-front: in-app purchases only work when your app is installed FROM the Play Store. That's a Google rule for everyone, not an AppMint limit.

### 4. Step 1 - Invent your product ID

A product ID is just a short name you make up for the thing you sell. You'll type this same name in two places later (your page + Play Console), so keep it simple and write it down.

Rules: only lowercase letters, numbers, underscores. Must start with a letter or number.

Copy one of these:

- pro_unlock - 'Pro version' upgrade (good default - the code below already uses it)
- remove_ads - ad-free upgrade
- level_pack_2 - extra content pack
- coins_100 - game currency pack
- premium_monthly - monthly subscription

The price is NOT part of the ID - you'll set the price in Step 5, and you can change it any time without touching your code.

### 5. Step 2 - Mark your button (no code to write)

You do NOT write any purchase code. Your app already carries the purchase engine - you just label your own HTML so it knows what to sell.

Copy the block below into your page and change only:

(1) pro_unlock → your product ID, in data-iap-buy  
(2) the words on the button and inside the paid section

That's it. The button then shows Google's real price in the buyer's own currency, opens Google's payment screen when tapped, reveals the paid section after payment (and again at every launch for people who already bought), takes it back if a subscription lapses or a payment is refunded, and shows a clear message if anything goes wrong.

THE FOUR LABELS:

- data-iap-buy="id" - makes this the buy button (required)
- data-iap-label="…{price}…" - button text; {price} becomes Google's real price
- data-iap-owned="…" - button text after buying
- data-iap-show - a section that appears only after buying (start it 'hidden')

Also available: data-iap-hide (disappears after buying), data-iap-container (a wrapper that only appears inside the app), data-iap-text (put it on the <span> holding the text if your button also has icons).

SELLING SEVERAL DIFFERENT THINGS? Add a button for each. They are independent - an app can remove ads AND sell level packs AND run a subscription, and buying one never affects the others. Point a section at one product with data-iap-show="level_pack_2".

Only the IDs you type into 'Remove Ads (IAP) → Product ID' switch the ads off. Everything else you sell unlocks whatever your page does with it, and the ads keep running.

TWO PLANS FOR THE SAME THING (monthly vs lifetime)? Give both buttons the same data-iap-group="adfree" - then buying either hides the other, so nobody pays twice. Without a group nothing is hidden, which is what unrelated products need.

```
<!-- (1) CHANGE pro_unlock to your product ID -->
<button data-iap-buy="pro_unlock"
        data-iap-label="Unlock Pro — {price}"
        data-iap-owned="✓ Unlocked">
  Unlock Pro
</button>

<!-- (2) CHANGE the words. Appears only after buying. -->
<div data-iap-show hidden>
  🎉 Pro content here — visible after buying.
</div>

<!-- Optional: disappears after buying -->
<div data-iap-hide>
  Upgrade to remove the ads.
</div>

<!-- DIFFERENT THINGS: independent — buying one never affects the others -->
<button data-iap-buy="remove_ads"   data-iap-label="Remove ads — {price}">Remove ads</button>
<button data-iap-buy="level_pack_2" data-iap-label="Levels 11-20 — {price}">Get levels</button>

<div data-iap-show="level_pack_2" hidden>Levels 11-20 unlocked!</div>

<!-- SAME THING, TWO PLANS: one group, so buying either hides the other -->
<button data-iap-buy="remove_ads_monthly"  data-iap-group="adfree"
        data-iap-label="Remove ads — {price}/month"
        data-iap-owned="✓ Ad-free (monthly)">Remove ads monthly</button>

<button data-iap-buy="remove_ads_lifetime" data-iap-group="adfree"
        data-iap-label="Remove ads forever — {price}"
        data-iap-owned="✓ Ads removed forever">Remove ads forever</button>
```

### 6. The 4 things people usually sell

Pick whichever matches you. The only difference between them is where you create the product in Play Console - your page code is the same shape every time.

1. REMOVE ADS, PAID ONCE (forever)

Create it under: In-app products  
Also type the id into: Remove Ads (IAP) → Product ID

1. REMOVE ADS, MONTHLY

Create it under: Subscriptions  
Also type the id into: Remove Ads (IAP) → Product ID

1. UNLOCK LEVELS / CONTENT, PAID ONCE

Create it under: In-app products  
Do NOT type it into the Remove Ads box - your ads keep running.

1. UNLOCK LEVELS / CONTENT, MONTHLY

Create it under: Subscriptions  
Do NOT type it into the Remove Ads box - your ads keep running.

You can sell ALL FOUR in the same app, and as many products as you like. Buying one never affects the others.

```
<!-- 1. remove ads, paid once -->
<button data-iap-buy="remove_ads_lifetime"
        data-iap-label="Remove ads forever — {price}"
        data-iap-owned="✓ Ads removed">Remove ads forever</button>

<!-- 2. remove ads, monthly -->
<button data-iap-buy="remove_ads_monthly"
        data-iap-label="Remove ads — {price}/month"
        data-iap-owned="✓ Ad-free">Remove ads monthly</button>

<!-- 3. levels, paid once -->
<button data-iap-buy="level_pack_2"
        data-iap-label="Levels 11-20 — {price}"
        data-iap-owned="✓ Unlocked">Get levels 11-20</button>

<!-- 4. all levels, monthly -->
<button data-iap-buy="all_levels_monthly"
        data-iap-label="All levels — {price}/month"
        data-iap-owned="✓ Subscribed">Subscribe</button>
```

### 7. Which purchases remove the ads?

This is the one thing people get wrong, so it is worth 30 seconds.

Your ads are NOT part of your web page. They are real Android ads sitting on top of it, so nothing in your page can switch them off. Only ONE thing can:

```
wizard Step 3 → Remove Ads (IAP) → Product ID
```

Whatever id you type in that box removes the ads when someone buys it. Every other id you sell just unlocks whatever your page does with it, and the ads carry on.

Selling both an ad-free plan AND level packs? Type only the ad-free id in that box. In our example:

```
Product ID box:  remove_ads_monthly
NOT in the box:  level_pack_2
```

Offering two ad-free plans (monthly AND lifetime)? Put both in that one box, separated by a comma - owning either one removes the ads:

```
remove_ads_monthly,remove_ads_lifetime
```

Not selling ad removal at all? Leave that toggle off entirely and just use '💰 Sell In-App Products'.

```
Selling levels only:
  Remove Ads (IAP)          OFF
  Sell In-App Products      ON

Selling ad removal only:
  Remove Ads (IAP)          ON   → Product ID: remove_ads_monthly
  Sell In-App Products      ON

Selling both, with two ad-free plans:
  Remove Ads (IAP)          ON   → Product ID: remove_ads_monthly,remove_ads_lifetime
  Sell In-App Products      ON
  (level_pack_2 stays out of the box)
```

### 8. Full example - plain HTML page

Here is our whole example app: sells 'Levels 11-20' once, and 'Remove ads' monthly. Copy it, change the two ids and the words, and you are done.

Read what each label does:

- data-iap-buy    → what this button sells
- data-iap-label  → the text; {price} becomes Google's real price
- data-iap-owned  → the text after they have paid
- data-iap-show="level_pack_2" → this box appears only after THAT product is bought
- data-iap-hide   → this box disappears once anything is bought

Notice there is no <script> and no purchase code. Your app already contains it.

```
<h2>Get more levels</h2>

<button data-iap-buy="level_pack_2"
        data-iap-label="Levels 11-20 — {price}"
        data-iap-owned="✓ Levels 11-20 unlocked">
  Levels 11-20
</button>

<div data-iap-show="level_pack_2" hidden>
  🎉 Levels 11 to 20 are yours. Have fun!
</div>

<h2>Tired of ads?</h2>

<button data-iap-buy="remove_ads_monthly"
        data-iap-label="Remove ads — {price}/month"
        data-iap-owned="✓ No more ads">
  Remove ads
</button>

<div data-iap-hide>
  Ads help keep this game free.
</div>
```

### 9. Full example - React or Next.js

THE EASY WAY: the exact same labels work in React and Next.js, because they are only markup. No useState, no useEffect, no 'use client'. Buttons React adds later are picked up automatically.

That is all most apps need - use the first block below and stop there.

THE CONTROLLED WAY (second block): only if you want React itself to draw the price and switch the screen. Then:

- In Next.js put 'use client' on line 1 of the file, or the build fails.
- Only touch window.AppMintIAP inside useEffect - in the component body it runs on the server, where window does not exist.
- onChange(fn) hands you the state right away and again on every change, and returns the unsubscribe function React wants.
- In Next.js, build as a static export: output: 'export' in next.config.js.

```
// ── EASY WAY — just JSX, nothing else ──────────────────────────
export default function Shop() {
  return (
    <>
      <button data-iap-buy="level_pack_2"
              data-iap-label="Levels 11-20 — {price}"
              data-iap-owned="✓ Unlocked">Levels 11-20</button>

      <div data-iap-show="level_pack_2" hidden>🎉 Levels 11-20 are yours!</div>
    </>
  );
}

// ── CONTROLLED WAY — React draws everything ───────────────────
'use client';                       // Next.js: must be line 1
import { useEffect, useState } from 'react';

export default function Shop() {
  const [iap, setIap] = useState({ available: false, products: {} });

  useEffect(() => {
    if (typeof window === 'undefined' || !window.AppMintIAP) return;
    window.AppMintIAP.start({
      plans: [{ id: 'level_pack_2' }, { id: 'remove_ads_monthly' }]
    });
    return window.AppMintIAP.onChange(setIap);
  }, []);

  if (!iap.available) return null;   // outside the app there is nothing to buy

  const levels = iap.products?.level_pack_2;   // always optional-chain
  return levels?.owned
    ? <p>🎉 Levels 11-20 are yours!</p>
    : <button onClick={() => window.AppMintIAP.buy('level_pack_2')}>
        Levels 11-20 {levels?.price}
      </button>;
}
```

### 10. Quick check in your browser

Open your page in a normal browser (Chrome on your PC or phone).

You should see the buy button sitting there doing nothing, and your paid section still hidden. Both are correct: outside the app there is nothing to buy, so nothing can be bought by accident.

Inside the app it is a different page entirely: the button gets the real price, opens Google's payment screen, and hides itself once the buyer owns it. Your website keeps working normally for ordinary visitors either way.

Want the offer to vanish completely on the web? Wrap it in a <div data-iap-container hidden> - that wrapper is revealed only inside the app.

### 11. Step 3 - Turn purchases ON in the STEPPER

⚠️ DO NOT SKIP THIS. If you skip it your buttons still appear, but every tap answers 'In-app purchases are not enabled in this app.' and you take no money.

The STEPPER is the Step 1 → Step 2 → Step 3 screens you use to build your app. Purchases live in STEPPER STEP 3.

DO THIS IN ORDER:

1. Open the stepper and go to STEPPER STEP 3 (the screen with Ads, Notifications and Permissions).

1. Scroll down to the card headed 'Remove Ads (IAP)'.

CANNOT SEE THAT CARD? Turn the 'Ads' switch ON - the purchase card only appears while Ads is on. If your app has no ads at all: turn Ads ON, do point 3, then turn Ads back OFF. Your purchase setting stays on.

1. Turn ON the golden '💰 Sell In-App Products' switch.

THIS IS THE SWITCH THAT LETS YOU SELL ANYTHING. Nothing works without it.

- Uploading a ZIP or an AI-built app: AppMint scans your files, finds your buy buttons, turns this on for you and lists your product ids. Check it is on anyway.
- Using a website URL: turn it on yourself - a live website cannot be scanned during the build.

1. ONLY IF you are also selling ad removal: turn ON 'Remove Ads (IAP)' as well, and type your ad-free product id into the 'Play Store Product ID' box. Two ad-free plans? Type both ids separated by a comma, e.g. remove_ads_monthly,remove_ads_lifetime

Never put a level pack or Pro-feature id in that box - it would switch your ads off for free.

1. If the 'License Key' box is showing, paste your key there (Play Console → Monetize → Monetization setup → Licensing). It lets your app check that a payment is genuine.

1. Finish the stepper and export the AAB file - NOT the APK. Google Play only accepts AAB, and purchases only ever work through the Play Store.

BEFORE YOU BUILD, look at STEPPER STEP 3 one more time and confirm '💰 Sell In-App Products' is ON. That single switch is the most common reason a creator's buttons do nothing.

```
STEPPER STEP 3 — what to set

  Ads ......................... ON  (needed to see the card below)
  💰 Sell In-App Products ..... ON  ← REQUIRED for selling anything

  Selling ad removal too?
  Remove Ads (IAP) ............ ON
  Play Store Product ID ....... remove_ads_monthly
         (two plans) .......... remove_ads_monthly,remove_ads_lifetime
  License Key ................. paste from Play Console

  Export ...................... AAB  (not APK)
```

### 12. Step 4 - Put your app on Google Play

In your Play Console (the website where developers manage their apps):

1. 'Create app' → fill in the name and basic questions.
2. In the left menu: 'Testing' → 'Internal testing' → 'Create new release' → upload your AAB file → 'Save' and roll it out.
3. Still in Internal testing → 'Testers' tab → add your own Gmail → copy the 'join' link for later.

Internal testing is a private area - nobody can see your app yet. It exists so YOU can try purchases before going public.

[Open Play Console](https://play.google.com/console)

### 13. Step 5 - Create your product and set the price

Now tell Google what you are selling. Which menu you use depends on whether they pay once or every month.

PAID ONCE (levels, Pro, coins, remove-ads-forever)

1. Play Console → your app → 'Monetize' → 'Products' → 'In-app products'.
2. 'Create product'.
3. Product ID: type EXACTLY the id from your page - level_pack_2. Same spelling, same case. Google never lets you change or reuse it.
4. Name: what buyers see, e.g. 'Levels 11-20'. Description: one line.
5. Set your price in your own currency - Google converts it for every country.
6. Press 'Activate'.

EVERY MONTH (remove ads monthly, all-levels subscription)

1. Play Console → 'Monetize' → 'Products' → 'Subscriptions'.
2. 'Create subscription'. Product ID: remove_ads_monthly.
3. Save, then add a BASE PLAN: type 'Auto-renewing', billing period 'Monthly', your price.
4. Press 'Activate' on the base plan AND on the subscription itself. Miss either one and your app cannot see it.

Repeat for every id you used. Your page code does not change - the app asks Google which kind each id is.

WANT MONTHLY *AND* YEARLY? Create TWO separate subscriptions (all_levels_monthly and all_levels_yearly) rather than two base plans inside one subscription. One subscription with several base plans always offers the first one, with no way to pick.

Change any price later in Play Console - your app shows the new price by itself, no rebuild needed.

### 14. Step 6 - Test it (you won't be charged)

1. Play Console → left menu 'Setup' → 'License testing' → add your Gmail to the testers list.
2. On your phone: open the internal-testing join link from Step 4, accept, and install your app FROM the Play Store.
3. Open the app. Your buy button appears with the real price.
4. Tap it - Google's payment sheet opens and says 'Test card, always approves'. Buy it. Your pro content appears. You pay nothing.
5. Bonus check: uninstall and reinstall the app - the pro content unlocks by itself at launch. That's Google restoring the purchase.

⚠️ If you install the APK directly (sideload) instead of from the Play Store, the buy button will NOT appear. That's normal - always test through the Play Store link.

### 15. Step 7 - Go live and get paid

1. When testing looks good: Play Console → 'Production' → create a release with the same AAB → roll out. (First-time apps go through Google's review - usually a few days.)
2. Users buy inside your app → Google collects the money.
3. Google pays your bank account monthly (Play Console → 'Payments profile'). Google keeps its standard service fee (15% for most developers). AppMint keeps nothing.

To add more products later: add the new ID in your page code, rebuild once, and create the ID in Play Console. Price changes never need a rebuild.

### 16. If something doesn't work

Your app tells you what went wrong instead of failing silently. Find the message you see:

'In-app purchases are not enabled in this app.'  
→ '💰 Sell In-App Products' was OFF in STEPPER STEP 3 when you built. Turn it on and build again.

'This item is not available on Google Play yet.'  
→ Google does not recognise that id. Check it letter by letter against Play Console, confirm the product is ACTIVE (for a subscription, the base plan AND the subscription must both be activated), and make sure you installed the app from the Play tester link.

'Google Play could not start the payment.'  
→ The app was not installed from the Play Store, or was signed with a different key than the one you uploaded.

'Payment pending - this unlocks automatically once Google confirms.'  
→ Nothing to do. Slow payment methods (cash vouchers, some UPI) take a few minutes; the unlock arrives by itself, even after restarting the app.

NO MESSAGE AT ALL, nothing happens on tap  
→ Almost always a typo in data-iap-buy, or the app is not installed from Play. Every other cause shows one of the messages above.

PAYMENT WORKED BUT THE ADS ARE STILL THERE  
→ That product id is not in STEPPER STEP 3 → 'Remove Ads (IAP)' → 'Play Store Product ID'. Add it (comma-separate several) and build again.

BUY BUTTON NEVER APPEARS IN THE APP  
→ '💰 Sell In-App Products' was off at build time. In a normal web browser the buttons are hidden ON PURPOSE - there is nothing to buy outside the app.

NOTHING HAPPENED AFTER I CLOSED GOOGLE'S PAYMENT SHEET  
→ That is a normal cancel. Tap again and complete the payment.

PRICE LOOKS OLD  
→ Play caches prices on a device for a few hours. A fresh install always shows the new price.

### 17. React, Next.js, or plain JavaScript

REACT AND NEXT.JS NEED NOTHING SPECIAL. The labels above are only markup, so the same one line works there too - no useState, no useEffect, no 'use client':

<button data-iap-buy="pro_unlock"

```
      data-iap-label="Unlock Pro — {price}">Unlock Pro</button>
```

Buttons React mounts later are found automatically, and remounting is safe. In Next.js, build as a static export (output: 'export').

Prefer code to labels? One line does the same job:

AppMintIAP.sell('pro_unlock', '#buy-btn');

Optional third argument: {label:'Unlock Pro - {price}', owned:'✓ Unlocked', show:'#thanks', hide:'.upsell'}. Call it once per product.

ONLY IF YOU WANT REACT TO DRAW THE PRICE ITSELF - otherwise skip this:

const [iap, setIap] = useState({ available: false, products: {} });

useEffect(() => {

```
if (typeof window === 'undefined' || !window.AppMintIAP) return;
window.AppMintIAP.start({ plans: [{ id: 'pro_unlock' }] });
return window.AppMintIAP.onChange(setIap);
```

}, []);

const pro = iap.products?.pro_unlock;   // always optional-chain

if (!iap.available) return null;        // nothing to buy outside the app  
if (pro?.owned) return <p>Thanks!</p>;  
return <button onClick={() => window.AppMintIAP.buy('pro_unlock')}>

```
       Unlock Pro {pro?.price}
     </button>;
```

TWO HABITS KEEP THIS FROM BREAKING:

1. Read ownership PER PRODUCT - iap.products?.<id>?.owned. The top-level iap.owned means 'anything is owned' and changes meaning the day you sell a second product.
2. Optional-chain the whole path, so a field you did not expect can never throw while React is rendering.

onChange hands you {available, adFree, owned, ownedIds, products} immediately and on every change, and returns an unsubscribe function - so a returning buyer is already unlocked on the first render. In Next.js add 'use client' as line 1 and build with output: 'export'.

Also: AppMintIAP.available, .isOwned(id), .owned(), .buy(id), .state(), .refresh(). data-iap-buy labels work in JSX too, and buttons React mounts later are picked up automatically.

Prefer to drive the raw bridge yourself? Everything above is built on these:

- iap.isOwned(id) - instant true/false, works offline
- iap.getOwnedProducts() - JSON array of all owned IDs
- iap.getProducts(reqId, idsJson) - live prices; result arrives as the 'appmint:products' event {requestId, products:[{productId, title, price, currency, type, owned}]}
- iap.purchase(id) - one-time products AND subscriptions (auto-detected)
- Events: 'appmint:purchase' {productId} (grant ONLY here - also fires on restore), 'appmint:purchase-failed' {reason: disabled | not_found | billing_error | pending}

Selling only a single 'remove ads' upgrade? Use the simpler built-in pair instead - enable 'Remove Ads (IAP)' in wizard Step 3:

```
var iap = window.WebToApk;

if (iap && !iap.isPremium()) {
  showRemoveAdsButton(function onTap() {
    iap.startRemoveAdsPurchase();
  });
}

window.addEventListener('appmint:premium', function (e) {
  if (e.detail.premium) hideRemoveAdsButton();
});
```

## Remove Ads (IAP)

Google Play Billing Setup

### 1. Create Managed Product

In your Google Play Console dashboard:

- Go to 'Monetization' > 'In-app products'
- Click 'Create product'
- Enter a Product ID (e.g., 'remove_ads_premium')
- Set a Name (e.g., 'Remove All Ads') and Description
- Set the Price and click 'Save'
- Click 'Activate' to make it available for testing

Selling ad removal as a SUBSCRIPTION instead? Create it under 'Monetization' > 'Subscriptions' with an auto-renewing base plan, and activate BOTH the base plan and the subscription. Ad-free then lasts as long as the subscription is active, and the ads come back automatically when it lapses.

[Open Play Console](https://play.google.com/console)

### 2. Get your License Key

Google Play requires an RSA public key to verify purchases securely.

In Play Console:

- Go to 'Monetization' > 'Monetization setup'
- Under 'Licensing', copy the 'Base64-encoded RSA public key'
- ⚠️ IMPORTANT: You will need to paste this into the Generator later.

```
Example Key Format:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
```

### 3. Setup in WebToApk Generator

In the generator app:

1. Enable 'Remove Ads (IAP)' toggle in Step 3
2. Enter the EXACT same 'Product ID' you created in Step 1
3. Paste your 'Base64 License Key' from Step 2
4. Generate your APK/AAB

Offering more than one ad-free plan (e.g. a monthly subscription AND a lifetime one-time unlock)? Put every Product ID in this one field, separated by commas - owning ANY of them removes the ads. The first ID listed is the one the built-in 'Remove Ads' menu item buys, so put your default plan first.

```
Product ID: remove_ads_premium

Two plans:
remove_ads_monthly,remove_ads_lifetime
```

### 4. Setup License Testers

To test purchases without spending real money:

- In Play Console, go to 'Setup' > 'License testing'
- Add your Gmail address to the 'License testers' list
- Ensure 'License response' is set to 'RESPOND_NORMALLY'

[Setup License Testers](https://play.google.com/console)

### 5. Test in Internal or Closed Track

In-App Purchases ONLY work when the app is installed via the Play Store (Testing tracks):

1. Upload your generated AAB to the 'Internal Testing' or 'Closed Testing' track
2. Share the tester join link with your test accounts
3. Download the app from the Play Store
4. Tap the 'Remove Ads' button in your app to test the flow!

```
Note: Purchases will show a 'Test instrument, always approves' message for license testers.
```

## Code recipes

The steps above cover the basics - the four labels, a full plain page, the React one-liner. These recipes cover what they do not: several plans that replace each other, subscriptions that lapse, framework hooks, the raw bridge in full, and the reference tables.

### The one rule

A purchase is granted **only** when Google confirms it. Not when the button is clicked, not when the sheet opens, not when the user comes back to your page. Everything below is a different way of expressing that one rule.

The runtime already enforces it: `AppMintIAP` re-reads ownership from the bridge on launch, on every purchase, on every refund and every time the app is reopened. Ownership survives reinstalls, a new phone and being offline, because it lives in the buyer's Google account, not in your page.

> **Careful.** Never unlock in the click handler, and never keep the entitlement only in `localStorage`. A cleared browser store must not cost a paying customer what they bought - and a copied `localStorage` value must not give it away for free.

### Recipe 1 - a pricing table with live prices

Three plans where buying any one of them replaces the others. `group` is what makes them alternatives: without it, they are unrelated products and buying the lifetime plan would leave the monthly button sitting there.

*Three alternatives, one group*

```html
<div class="plans" data-iap-container>
  <button data-iap-buy="pass_monthly" data-iap-group="pass"
          data-iap-label="Monthly — {price}" data-iap-owned="Active">Monthly</button>

  <button data-iap-buy="pass_yearly" data-iap-group="pass"
          data-iap-label="Yearly — {price}" data-iap-owned="Active">Yearly</button>

  <button data-iap-buy="pass_lifetime" data-iap-group="pass"
          data-iap-label="Lifetime — {price}" data-iap-owned="Owned">Lifetime</button>
</div>

<p data-iap-show="pass">You are a member. Thank you.</p>
<p data-iap-hide="pass">Members get every level and no ads.</p>
```

A product id that Google does not know about - not created yet, not activated, or the app was not installed from the Play Store - is simply left without a price. Its button stays tappable on purpose: tapping it then reports the real reason instead of doing nothing.

### Recipe 2 - React

`onChange` fires immediately with the current state and again on every change, and it returns its own unsubscribe function - so it is exactly the shape a `useEffect` wants.

*hooks/useIap.js*

```jsx
import { useEffect, useState } from 'react';

/** Purchase state for the whole app. Safe in a browser too: available is false there. */
export function useIap() {
  const [iap, setIap] = useState({ available: false, ownedIds: [], products: {}, adFree: false });

  useEffect(() => {
    if (!window.AppMintIAP) return;             // running in a browser, or IAP not enabled
    return window.AppMintIAP.onChange(setIap);  // returns the unsubscribe fn
  }, []);

  return {
    ...iap,
    owns: (id) => iap.ownedIds.includes(id),
    priceOf: (id) => iap.products[id]?.price ?? null,
    buy: (id) => window.AppMintIAP?.buy(id)
  };
}
```

*A gate around anything you sell*

```jsx
import { useIap } from './hooks/useIap';

export function ProGate({ children }) {
  const { available, owns, priceOf, buy } = useIap();

  if (owns('pro_unlock')) return children;

  return (
    <div className="upsell">
      <h2>Pro</h2>
      <p>Unlimited projects, no watermark.</p>
      <button onClick={() => buy('pro_unlock')} disabled={!available}>
        {available ? `Unlock Pro${priceOf('pro_unlock') ? ` — ${priceOf('pro_unlock')}` : ''}` : 'Not available here'}
      </button>
    </div>
  );
}
```

> **Note.** The button calls `buy()`; it does not unlock anything. The unlock happens because Google confirms, `onChange` fires, `owns('pro_unlock')` turns true and the component re-renders. That is the same rule, expressed in React.

### Recipe 3 - Vue

*The same gate in Vue 3*

```html
<script setup>
import { ref, onMounted, onUnmounted, computed } from 'vue';

const iap = ref({ available: false, ownedIds: [], products: {} });
let stop;

onMounted(() => { stop = window.AppMintIAP?.onChange(s => (iap.value = s)); });
onUnmounted(() => stop && stop());

const isPro = computed(() => iap.value.ownedIds.includes('pro_unlock'));
const price = computed(() => iap.value.products.pro_unlock?.price ?? '');
</script>

<template>
  <slot v-if="isPro" />
  <button v-else :disabled="!iap.available" @click="AppMintIAP.buy('pro_unlock')">
    Unlock Pro {{ price }}
  </button>
</template>
```

### Recipe 4 - subscriptions

A subscription is bought exactly like a one-time product; the difference is that it can go away. `type` tells you which kind a product is and `period` gives the billing interval as an ISO-8601 duration - `P1M` monthly, `P1Y` yearly, `P1W` weekly.

*A monthly pass that expires on its own*

```js
AppMintIAP.onChange(state => {
  const pass = state.products.season_pass;      // undefined until Google answers
  const active = state.ownedIds.includes('season_pass');

  document.body.classList.toggle('has-pass', active);

  if (pass && !active) {
    const every = { P1W: 'week', P1M: 'month', P1Y: 'year' }[pass.period] || 'period';
    label.textContent = `Season pass — ${pass.price} / ${every}`;
  }
});

// The pass lapsed (not renewed, or refunded): the same handler runs with it gone.
// Nothing to write — the class comes off and the paid content hides itself.
```

You do not poll and you do not need an expiry date. Play restores the owned set on every launch, so a lapsed subscription simply stops appearing in `ownedIds`.

> **Careful.** Activate **both** the subscription and its base plan in the Play Console. A subscription with an inactive base plan returns no details at all, and the button will report "not available on Google Play yet".

### Recipe 5 - the raw bridge, no helper

Everything above is built on six methods and five events. If you want to own the UI completely, use them directly.

*The whole surface, in one file*

```js
const bridge = window.WebToApk;
const enabled = !!(bridge && bridge.purchase);          // false in a browser

// --- what does Google charge for these, in this buyer's currency? ---
const reqId = 'prices-' + Date.now();
window.addEventListener('appmint:products', function onProducts(e) {
  if (e.detail.requestId !== reqId) return;             // not our answer
  window.removeEventListener('appmint:products', onProducts);
  for (const p of e.detail.products) {
    // {productId, type:'inapp'|'subs', title, description, price, currency, period?, owned}
    render(p);
  }
});
bridge.getProducts(reqId, JSON.stringify(['pro_unlock', 'season_pass']));

// --- what does this buyer already own? instant, and works offline ---
const owned = JSON.parse(bridge.getOwnedProducts() || '[]');
const isPro = bridge.isOwned('pro_unlock');

// --- buy ---
buyButton.onclick = () => bridge.purchase('pro_unlock');

// --- the ONLY place a purchase is ever granted ---
window.addEventListener('appmint:purchase', e => {
  if (e.detail.productId === 'pro_unlock' && e.detail.owned) unlockPro();
});

// --- and the only place failures show up ---
window.addEventListener('appmint:purchase-failed', e => {
  toast({
    not_found:     'This item is not available on Google Play yet.',
    billing_error: 'Google Play could not start the payment. Please try again.',
    pending:       'Payment pending — this unlocks automatically once Google confirms.',
    disabled:      'In-app purchases are not enabled in this app.'
  }[e.detail.reason] || 'Purchase could not be completed. Please try again.');
});

// --- the launch-time restore finished, or a refund took something away ---
window.addEventListener('appmint:owned-changed', () => refreshEverything());
```

> **Note.** `appmint:purchase` fires again for something already owned, on purpose. Write `unlockPro()` so that running it twice is harmless and you never have to track whether you have already run it.

### Recipe 6 - degrade honestly outside the app

The same page usually has to open in a normal browser as well - during development, or because you also publish it on the web. There, `window.WebToApk` does not exist and no purchase can happen. Say so, rather than showing a button that does nothing.

*One check, at the top*

```js
const inApp = !!(window.AppMintIAP && window.AppMintIAP.available);

if (!inApp) {
  buyButton.disabled = true;
  buyButton.textContent = 'Available in the Android app';
  // and let people get it:
  storeLink.hidden = false;
}
```

### Reference

Everything the page can call, listen for, or mark up.

**window.AppMintIAP - the helper the runtime injects**

| Call | Does |
| --- | --- |
| `AppMintIAP.available` | False in a browser, or when in-app purchases were not switched on for this build. Check it before showing anything for sale. |
| `AppMintIAP.sell(id, button, opts)` | Wire one product to one button. `opts`: `label`, `owned`, `group`, `show`, `hide`, `labelEl`. Call it once per product. |
| `AppMintIAP.start(config)` | Wire several at once: `{plans, show, hide, container, toast, hideOtherPlans}`. Use it when you want your own toast function, or to keep the other plans of a group visible after one is bought (`hideOtherPlans: false`). |
| `AppMintIAP.onChange(fn)` | Fires immediately with the current state, then on every change. Returns an unsubscribe function. |
| `AppMintIAP.state()` | The same object, once: `{available, adFree, owned, ownedIds, products}`. |
| `AppMintIAP.isOwned(id)` | True/false, instantly, offline. |
| `AppMintIAP.owned()` | Array of every owned product id. |
| `AppMintIAP.buy(id)` | Opens Google's purchase sheet. Grants nothing by itself. |
| `AppMintIAP.refresh()` | Re-scan for `data-iap-buy` buttons added since the last pass. Rarely needed - the runtime watches the DOM. |

**window.WebToApk - the bridge underneath**

| Call | Returns |
| --- | --- |
| `purchase(productId)` | Nothing. Opens the sheet; the outcome arrives as an event. |
| `getProducts(requestId, idsJson)` | Nothing. The answer arrives as `appmint:products` carrying the same `requestId`. |
| `getOwnedProducts()` | JSON array of owned product ids, as a string. |
| `isOwned(productId)` | Boolean - a one-time product owned, or a subscription currently active. |
| `isPremium()` | Boolean - the "remove ads" entitlement specifically. |
| `startRemoveAdsPurchase()` | Nothing. Opens the sheet for the FIRST id in the wizard's "Remove Ads" field; owning any id listed there removes the ads. Outcome arrives as `appmint:premium`. |

**Events**

| Event | detail | When |
| --- | --- | --- |
| `appmint:purchase` | `{productId, owned}` | Google confirmed. The only place to unlock. Re-fires for something already owned. |
| `appmint:purchase-failed` | `{productId, reason}` | The sheet never opened, the flow errored, or the payment is pending. Never fired for a plain cancel. |
| `appmint:products` | `{requestId, products[]}` | Reply to a `getProducts()` call. Ids Play does not know are simply absent. |
| `appmint:premium` | `{premium}` | The ad-free entitlement changed - purchase, launch restore, refund or expiry. |
| `appmint:owned-changed` | `{products[]}` | The launch-time restore finished, or a refund took something away. Carries every owned id. |

**HTML attributes**

| Attribute | On | Does |
| --- | --- | --- |
| `data-iap-buy="id"` | button | Makes it buy that product. |
| `data-iap-label="… {price}"` | button | Label template. `{price}` becomes Google's live localised price. |
| `data-iap-owned="…"` | button | Label once the product is owned. |
| `data-iap-group="name"` | button | Marks plans as alternatives to each other. |
| `data-iap-show="id|group"` | anything | Shown only when that is owned. |
| `data-iap-hide="id|group"` | anything | Hidden once that is owned. |
| `data-iap-text` | inside a button | The element whose text gets the label, when the button has more inside it than text. |
| `data-iap-container` | wrapper | Shown only inside the app; hidden in a browser, where there is nothing to buy. Wrap the whole offer in it. |
| `data-iap-state="owned"` | set by the runtime | On an owned product's button, so you can style it. |

**Failure reasons on appmint:purchase-failed**

| reason | What actually happened |
| --- | --- |
| `not_found` | Google does not know this product id - not created, not activated, or the app was not installed from the Play Store. |
| `billing_error` | Play could not start the payment. Usually transient; the buyer should try again. |
| `pending` | A slow payment method (cash, bank transfer). It unlocks by itself when Google confirms - do not treat this as a failure. |
| `disabled` | In-app purchases were not switched on for this build. |
| `unknown` | Anything else. |

### Before you ship

1. Every product id in your code exists in the Play Console **and is activated** - for a subscription, the base plan too.
2. The build carries the same ids, and the Base64 RSA licence key from Monetization setup.
3. Your Gmail address is in **Setup → License testing**, with the response set to RESPOND_NORMALLY.
4. You uploaded the AAB to Internal or Closed testing and installed it **from the Play Store link** - a sideloaded APK can never purchase anything.
5. You bought each product as a licence tester and saw "Test instrument, always approves".
6. You uninstalled and reinstalled, and the purchase came back on its own.
7. You turned off the network and the paid content is still unlocked.
8. You refunded a test purchase in the Play Console and watched the app lock again.

### Mistakes that cost money

- **Unlocking in the click handler.** Anyone who opens the sheet and backs out gets the product free.
- **Storing the entitlement only in `localStorage`.** Clearing site data takes away something a customer paid for; copying a value gives it away.
- **Hard-coding the price in your HTML.** It will be wrong in every other country and out of date the day you change it. Use `{price}` or `products[id].price`.
- **Selling physical goods or a real-world service through Play billing.** Google requires the opposite: those must use a normal payment processor. That is what the [Stripe guide](/docs/stripe-payments) is for.
- **Testing on a sideloaded APK.** In-app purchases only work when the app was installed from the Play Store. Nothing you write can change that.
- **Treating `pending` as a failure.** The buyer paid by a slow method; it unlocks by itself when Google confirms.


---

# Connectors - Payments, WhatsApp, Maps & more

> Prebuilt wiring for payment gateways, WhatsApp, Maps and other third-party services.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/connectors

Ask the AI for a service - it wires the real integration

### 1. What connectors are

Ask the AI for Stripe payments, WhatsApp messages, Google Maps, email, calendars - and it wires the real integration: backend functions, typed contracts, and a working keys screen. 14 curated connectors are built in, and anything else (Juspay, MSG91, a niche CRM) gets wired the same way automatically when your app needs it.

### 2. Connect a service in ~2 minutes

After generation, Settings → Connectors shows a card for every service your app uses. Open the service's dashboard (the card links to it), paste your API keys, and tap Test.

### 3. The Test button is the truth

A connector only turns Connected after one real authenticated call to that service succeeds. Your keys are stored on your backend - never inside the APK - so they're safe to ship.

### 4. Reuse across apps

Once a service is connected, every future app that mentions it reuses the proven setup - you don't configure the same service twice.


---

# Supabase Backend (Connect It Once)

> Connect a Postgres database, auth and storage once, and let the AI write against it.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/supabase-backend

Connect your own free Supabase project - cloud database, user accounts and storage for AI-generated apps

### 1. What connecting Supabase gives you

By default an AI-generated app keeps its data on the one phone it is installed on - 'Offline' mode. Connect Supabase and the same app gets a real cloud database (Postgres), user accounts, and file storage, so data is shared across devices and users.

It is BRING-YOUR-OWN: the app talks to YOUR free Supabase project. AppMint hosts nothing for you and charges nothing extra for it.

You do not design tables or write SQL. AppMint works out the schema from your app description, applies it, and keeps it in sync on every build.

### 2. What you need first

A free Supabase account - that is all. You do NOT need to create a project first; AppMint can create one for you during sign-in.

Worth knowing about the free plan:

- 2 projects per organisation.
- Projects pause after a week of no traffic and wake on the next request.

If you already have a project you want to reuse, that works too - AppMint puts each app in its own schema inside it, so several apps can share one project.

### 3. Connect it (one tap, recommended)

In AI Studio, under 'WHERE YOUR APP'S DATA LIVES', tap the 'Supabase' card (it reads 'Tap to connect'). Choose 'Sign in with OAuth'.

Your browser opens Supabase, you sign in and approve AppMint, and you land back in the app automatically - there is no token to copy.

The same thing is available from the ⚙ Settings gear → 'BACKEND - SUPABASE' → '🔗 Connect Supabase (OAuth)'.

[Create a free Supabase account](https://supabase.com)

### 4. Pick or create the project

Straight after approving, AppMint shows 'Pick a Supabase project':

- Choose an existing project, or
- Tap '➕  Create new project…' → pick the organisation → name it (e.g. appmint-prod) → pick a region close to your users (this cannot be changed later) → 'Create'. Provisioning takes 1-2 minutes.

When AppMint creates the project it shows the database password ONCE, because Supabase only stores a hash of it. Copy it somewhere safe before closing that dialog - you do not need it for AppMint, but you will need it to connect any other tool.

Hit the free-tier limit ('Free tier allows 2 projects per organization')? Pick an existing project instead, or upgrade in the Supabase dashboard.

### 5. Or connect manually (self-hosted / no OAuth)

Settings → 'BACKEND - SUPABASE' → 'MANUAL / SELF-HOSTED':

1. Project URL - from your Supabase dashboard, Project Settings → API. It looks like https://YOUR-PROJECT-REF.supabase.co
2. anon key - the publishable key from the same page; it starts with 'eyJ'. This key is designed to be public: Row-Level Security is what protects your data, not hiding the key.
3. Turn on 'Enable Supabase backend for generated apps' and tap 'Save Supabase config'.

Tick 'Self-hosted instance' if you run Supabase yourself. Manual mode cannot auto-deploy the schema on Cloud - add a Personal Access Token (next step) if you want that.

```
Project URL   https://abcdefghijkl.supabase.co
anon key      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 6. What AppMint does on every build

Once connected, each generation does the backend work for you:

- Applies the schema the AI wrote (tables, indexes, Row-Level-Security policies).
- Runs the seed data, if the app needs any.
- Creates Storage buckets for uploads and images.
- Deploys edge functions (payments, email, webhooks) and skips ones that have not changed.
- Sets the auth providers and Site URL.
- Runs a security gate and a migration gate, then pulls TypeScript types back into the project.

Your app's tables live in their own schema named appmint_<your app>. User accounts are shared across every app in the project, so one sign-up works everywhere.

### 7. Check that it worked

Two quick checks:

- The 'Supabase' card in AI Studio now reads 'Connected', and Settings shows the project ref.
- Settings → 'DIAGNOSTICS' → '⚡  Test Supabase connection' - it reports success or the exact error.

After you generate an app, open your Supabase dashboard → Table Editor and switch the schema selector from 'public' to appmint_<your app> to see the tables AppMint created.

### 8. Which keys are safe where

- anon key - safe inside generated apps. Row-Level Security decides what each signed-in user may read or write.
- service_role key - NEVER goes into an app. AppMint stores it encrypted on this device only, and uses it for Storage buckets and self-hosted schema apply.
- Personal Access Token (sbp_…) - also device-only; it lets AppMint deploy schema and edge functions on Supabase Cloud automatically. Create one at supabase.com/dashboard/account/tokens with read + write project scope.

Both optional keys live in Settings → 'ADVANCED - DEPLOY CREDENTIALS'.

[Create a Personal Access Token](https://supabase.com/dashboard/account/tokens)

### 9. Unlocks: Google Sign-In, Stripe, Remote Update

Several features need Supabase connected first, and will send you here until it is:

- 'Continue with Google' in generated apps.
- Stripe payments (the checkout runs in an edge function in your project).
- Remote Update - the updates you push to installed apps are stored in your own Supabase project.

Connect once and all three become available; you do not repeat this per app.

### 10. Removing an app's backend

Settings → 'DANGER ZONE' (visible when connected):

- '📋  List & delete project tables' - browse every table AppMint created and delete the ones you no longer need.
- '🗑  Delete this whole app backend' - removes that app's schema, and optionally its Storage buckets and edge functions. You type DELETE to confirm.

Choose 'Data only' if you are unsure: buckets and edge functions are shared across the whole project, not per app. Your user accounts are never touched.

To disconnect entirely: Settings → 'ONE-TAP OAUTH' → '🔒  Disconnect Supabase OAuth'.

### 11. If something doesn't work

- 'Not connected' after signing in → the OAuth finished but no project is bound yet. Settings → 'Choose project'.
- A warning that the anon key was not fetched automatically → your Supabase OAuth approval is missing the Secrets:Read scope. Copy the anon key from Project Settings → API and paste it in Settings (step 5).
- 'Could not list your Supabase organizations' when creating a project → create the project in the Supabase dashboard instead, then come back and pick it.
- 'Connect Supabase first' in Remote Update or Stripe → this chapter, step 3.
- Data reads/writes fail in a generated app → run '⚡  Test Supabase connection' first; if that passes, ask the AI to fix the Row-Level-Security policy for the table it names.


---

# Firebase Backend (Database + Accounts)

> A hosted database and user accounts for an app with no server of its own.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/firebase-backend

Give AI-generated apps a cloud database and user login using your own free Firebase project

### 1. What this gives your app

Normally your generated app stores data only on the phone it's running on. Turning on Firebase gives the app a free cloud database, so the same data is visible from any device and (if you want) people can sign up with email + password.

It's BRING-YOUR-OWN - the app talks to YOUR free Firebase project. AppMint hosts nothing and charges you nothing extra. You paste one config once; the AI writes all the code.

You do NOT have to write or design anything - no tables, no schema, no SQL. Firebase + AppMint figure it out from your app description.

### 2. Create the Firebase project (5 min, free)

On a computer is easiest:

1. Open console.firebase.google.com and sign in with any Google account.
2. Tap 'Add project' → give it any name → keep clicking 'Continue' → skip Google Analytics → 'Create project'. Wait ~30 sec.
3. In the left menu: Databases & Storage → Firestore → 'Create database'.

- Pick a location near your users (you can't change this later).
- Choose 'Start in production mode' - NOT 'test mode'. Test mode auto-expires after 30 days and your app will silently stop working.

1. In the left menu: Security → Authentication → 'Get started' → tab 'Sign-in method':

- Enable 'Email/Password' (turn ON the first toggle, save).
- ALSO enable 'Anonymous' (scroll down, turn ON, save) - needed for guest/leaderboard apps.

That's it. There's no schema to design.

[Open Firebase Console](https://console.firebase.google.com)

### 3. Copy your web config

Still in Firebase Console:

1. Tap the ⚙️ gear (top left) → 'Project settings'.
2. Scroll to 'Your apps' → tap the </> (web) icon.
3. Give the app any nickname → tap 'Register app' (skip 'Firebase Hosting').
4. You'll see a code snippet. Copy ONLY the firebaseConfig object - everything from the opening { to the closing }.

The web API key is meant to be public - your data is protected by the security rules in step 6, not by hiding the key.

```
const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "my-app.firebaseapp.com",
  projectId: "my-app",
  storageBucket: "my-app.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123:web:abc"
};   ← copy the { ... } part
```

### 4. Paste it into AppMint (once)

Open AI Studio → Settings → scroll to 'BACKEND - FIREBASE (OPTIONAL)':

1. Paste the firebaseConfig you copied into the big text box.
2. Turn ON the 'Enable Firebase backend' switch.
3. Tap 'Save Firebase config'. You should see 'Saved Firebase project: <your-project-id>'.

It's stored encrypted on your device and reused for every app you generate - you only do this once.

### 5. Describe your app - the AI does the rest

Just say what you want, in plain English. The AI decides whether to add login screens or not, based on what you ask for:

- 'A notes app where each user saves their own notes' → AI builds signup/login + private notes.
- 'A global leaderboard for a tap game, no accounts' → AI uses silent guest sign-in, public scores, no login UI.
- 'A shared bulletin board everyone can post to' → AI uses guest sign-in, no login UI.

If the device is offline or the config is missing, the app automatically falls back to phone-only storage so it never crashes.

### 6. Apply the security rules (REQUIRED)

Without this step, the app will get 'permission denied' errors when it tries to read or write. The AI writes the rules FOR YOU; you just paste them in.

1. After generating your app, open the Code view (or unzip the downloaded project) and find the file named 'firestore.rules'. Tap it and copy ALL the text.
2. In Firebase Console: Databases & Storage → Firestore → 'Rules' tab → tap 'Edit rules' → delete what's there → paste the AI's rules → tap 'Publish'.

Do this once per app. The rules are tailored to your app - they let users write only their own data, while leaderboards stay publicly readable.

### 7. Verify it works

Quick sanity check after installing the APK:

1. Open the app on your phone and do one action that should save data (create a note, submit a score, etc.).
2. Back in Firebase Console: Databases & Storage → Firestore → 'Data' tab → you should see a new collection (e.g. 'notes' or 'scores') with the data you just entered.
3. Security → Authentication → 'Users' tab → if your app uses login, your account should appear here.

If nothing shows up: check the 3 most common causes in the next step.

### 8. If something doesn't work

The most common errors:

- 'permission-denied' or no data saving → you forgot step 6 (Publish the rules).
- 'auth/operation-not-allowed' on signup/login → you didn't enable Email/Password in step 2.
- 'auth/operation-not-allowed' for guest/leaderboard apps → you didn't enable Anonymous in step 2.
- 'auth/operation-not-allowed' for Google sign-in → you didn't enable Google AND paste your SHA-256 fingerprint (see step 'Add Google Sign-In' below).
- Pasted config rejected ('Couldn't find a { ... } config object') → paste the WHOLE { ... } block including the curly braces, not just the inside.

Supported sign-in methods in generated apps: Email/Password, Anonymous (guest), Google Sign-In (via native Credential Manager), and Phone/SMS (via reCAPTCHA). Facebook/Apple/Twitter sign-in is still NOT supported - they require OAuth popups that Google blocks inside Android WebView.

### 9. Add Google Sign-In (optional)

Generated apps can use Google Sign-In via Android's native Credential Manager - it works inside the WebView (unlike OAuth popups). One-time setup per app:

1. Firebase Console → Security → Authentication → 'Sign-in method' tab → enable 'Google'. Save.
2. Firebase Console → ⚙ Project settings → 'Your apps' → if you don't already have an Android app registered, tap 'Add app' → Android → enter your package name (the one you'll use in AppMint).
3. Build your APK once in AppMint. Open the downloaded '<appname>_signkey_info.txt' file - at the top you'll see SHA-1 and SHA-256 fingerprints.
4. Back in Firebase Console → ⚙ Project settings → Your apps → Android app → 'Add fingerprint' → paste the SHA-1, then 'Add fingerprint' again for the SHA-256. Tap 'Save'. Google Sign-In checks the SHA-1: with only the SHA-256 it fails with 'No credentials available'. (You only do this ONCE per app - the same signing key is used for every future build.)
5. Publishing on Google Play? Play re-signs your app with its own key, so an install from Play has a DIFFERENT fingerprint. Play Console → your app → Test and release → App integrity → copy the SHA-1 and SHA-256 under 'App signing key certificate' and add both to the same Firebase Android app. Skip this and sign-in works from the APK but fails for everyone who installs from Play.
6. Firebase Console → ⚙ Project settings → General → scroll to 'Your apps' → find the Web SDK section → copy the 'Web client ID' (ends in .apps.googleusercontent.com).
7. Open AppMint Settings → paste it into 'GOOGLE SIGN-IN - OAUTH WEB CLIENT ID'. Save.
8. Rebuild your app. Google Sign-In now works.

### 10. Add Phone / SMS Sign-In (optional)

Phone Auth uses Firebase Web SDK + reCAPTCHA (works inside WebView). The user types their phone number, taps an 'I'm not a robot' check, receives an SMS code, and enters it.

Setup:

1. Firebase Console → Security → Authentication → 'Sign-in method' tab → enable 'Phone'. Save.
2. No SHA needed (we use reCAPTCHA verification, not Play Integrity).
3. Just ask the AI for phone sign-in in your app description (e.g. 'Users sign in with their phone number').

⚠️ Billing: Sending real verification SMS now requires the Blaze (pay-as-you-go) plan - the free Spark plan no longer includes a free SMS quota. Upgrade in Firebase Console → ⚙ Project settings → Usage and billing. On Blaze, Firebase Authentication allows up to 3,000 verification SMS per day; SMS pricing varies by country.

💡 To test WITHOUT billing or real SMS: Authentication → Settings → 'Phone numbers for testing' lets you add a fixed test number + code (no SMS is sent).

[Firebase Auth quotas & pricing](https://firebase.google.com/docs/auth/limits)

### 11. Cost - what to expect

Firebase's free 'Spark' plan covers most hobby apps. Free per day:

- 50,000 document reads
- 20,000 writes
- 20,000 deletes
- 1 GiB total storage
- 10 GiB / month outbound network

For reference: a small notes app with 100 active users does ~5,000 reads/day. A viral game leaderboard could blow past 50k reads in an hour.

⚠️ Set a budget alert: Google Cloud Console → Billing → Budgets & alerts → set 'Alert me at $1'. You stay safe and Firebase will email you the moment usage costs money.

[Set a budget alert](https://console.cloud.google.com/billing/budgets)


---

# Google Sign-In (Continue with Google)

> A real "Continue with Google" button inside a generated app, and the SHA-1 that makes it work.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/google-sign-in

Add 'Continue with Google' to AI-generated apps using your own Google account - no shared login, no secret in the app

### 1. What this gives your app

Adds a 'Continue with Google' button to apps you generate in AI Studio, so your users sign in with their Google account instead of typing a new email + password.

It's BRING-YOUR-OWN: the button uses YOUR Google sign-in, on YOUR consent screen, for YOUR users. AppMint hosts no login and stores nothing - you paste your Google credentials once and every app you generate can reuse them.

You don't write any code. The AI adds the button and the sign-in logic when you ask for it; the secret never ships inside the app.

### 2. First connect Supabase (required)

Google sign-in for generated apps rides on Supabase Auth, so you must have Supabase connected and enabled first (Settings → BACKEND - SUPABASE). If Supabase isn't active, the Google button won't appear. The chapter '🗄️ Supabase Backend (Connect It Once)' at the top of this guide walks through connecting it.

Why: your users' accounts live in YOUR Supabase project. AppMint pushes your Google credentials into that project automatically on deploy - you never have to flip the Google switch inside the Supabase dashboard yourself.

### 3. Create a Google OAuth client (5 min, free)

On a computer, in the Google Auth Platform console (Google recently moved OAuth setup here from 'APIs & Services'):

1. Open console.cloud.google.com/auth and pick (or create) any project.
2. First time only - configure the consent screen: under 'Branding' add an app name + your support email, and under 'Audience' choose 'External' and either publish the app or add yourself as a test user.
3. Open 'Clients' → click 'Create client'.
4. Application type: choose 'Web application' (NOT Android - the sign-in happens through Supabase on the web).
5. Name it and click 'Create'. You'll get a Client ID (ends in .apps.googleusercontent.com) and a Client secret. Keep this tab open for the next step.

[Open Google Auth Platform → Clients](https://console.cloud.google.com/auth/clients)

### 4. Add your Supabase callback as a redirect URI

This is the step everyone forgets - without it Google shows a 'redirect_uri_mismatch' error.

1. Find your Supabase project ref: it's the '<ref>' part of your project URL https://<ref>.supabase.co (Supabase dashboard → Project Settings → API).
2. Back in the Google OAuth client you just created, under 'Authorized redirect URIs' click 'Add URI' and paste exactly:

```
 https://<ref>.supabase.co/auth/v1/callback
```

1. Replace <ref> with your real project ref and Save.

```
https://<ref>.supabase.co/auth/v1/callback
```

### 5. Paste your credentials into AppMint

In AI Studio, just describe an app that needs accounts and ask for Google sign-in - e.g. 'let users sign in with Google'. The first time, AppMint pops a 'Connect Google sign-in' dialog:

1. Paste your Google OAuth Client ID (…apps.googleusercontent.com).
2. Paste your Google OAuth Client Secret.
3. Tap 'Save & continue'.

They're stored encrypted on your device and reused for every future app - you only paste them once. (Tap 'Skip Google' if you change your mind; the app still builds, just without the button.)

### 6. How it works on a real phone

Google blocks its login screen inside an in-app WebView, so AppMint handles it the safe way automatically - nothing for you to configure:

- Tapping 'Continue with Google' opens the real browser for the consent screen.
- After the user approves, it returns to your app through a secure deep link and finishes the sign-in.

This works in BOTH the live Preview and the installed APK. Each generated app uses its own private return link, so multiple AppMint-made apps never collide.

### 7. Verify it works

1. Open your app (Preview or installed APK) and tap 'Continue with Google'.
2. The browser opens, you pick your Google account, and you're returned to the app, signed in.
3. In your Supabase dashboard → Authentication → Users, your Google account now appears.

If it works in Preview it will work in the built APK - the flow is identical.

### 8. If something doesn't work

- 'redirect_uri_mismatch' → the redirect URI in step 4 doesn't exactly match. It must be https://<ref>.supabase.co/auth/v1/callback with YOUR ref, no trailing slash, no typos.

- Button doesn't appear → Supabase isn't active (step 2), or you tapped 'Skip Google'. Re-open the app description with Google sign-in requested.

- 'Access blocked: app not verified' → your OAuth consent screen is still in Testing. Add your Google account as a test user, or publish the consent screen.

- Only Google is offered - Facebook / Apple / X (Twitter) sign-in is NOT supported. They need OAuth popups that Android WebView blocks. Email/password still works alongside Google.

- Offline (no-backend) apps get no social login at all - there's no Supabase to authenticate against.


---

# Tawk.to Live Chat

> Put a staffed live-chat widget in the app without touching your website.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/live-chat

In-App Live Chat Setup (Premium Feature)

### 1. Create Tawk.to Account

Sign up for a free Tawk.to account. Tawk.to provides live chat completely free with unlimited chats and agents.

[Go to Tawk.to](https://www.tawk.to)

### 2. Create a Property

After logging in:

- Click 'Add Property' (top-right or from dashboard)
- Enter your property/website name
- Enter your website URL
- Click 'Create Property'

A property represents your website or app.

### 3. Get the Widget Embed Code

In your Tawk.to dashboard:

- Go to Administration (⚙️ gear icon)
- Select your property
- Click on 'Chat Widget'
- Scroll down to 'Direct Chat Link' or 'Widget Code' section
- Click 'Get Widget Code'
- Copy the full JavaScript snippet shown

```
Example embed code format:
<script type="text/javascript">
var Tawk_API=Tawk_API||{};
(function(){
  var s1=document.createElement("script");
  s1.src='https://embed.tawk.to/PROPERTY_ID/WIDGET_ID';
  s1.charset='UTF-8';
  s1.setAttribute('crossorigin','*');
  document.head.appendChild(s1);
})();</script>
```

### 4. Setup in Web2APK Generator

In the generator app (requires Premium):

1. Enable 'Live Chat' toggle in Step 3
2. Paste the FULL JavaScript embed snippet into the 'Tawk Widget Code' field
3. The chat button will appear in your app's side menu
4. Users tap it to open a live chat dialog

⚠️ Note: Live Chat is a Premium feature. Free accounts cannot enable it.

### 5. Test Live Chat

After installing your generated app:

- Open the app and look for the chat icon in the side menu
- Tap it to open the chat dialog
- In Tawk.to dashboard, go to 'Conversations' to see incoming chats
- You can reply from the dashboard or the Tawk.to mobile agent app

💡 Pro Tip: Install the Tawk.to app on your phone to respond to customers on the go.

[Download Tawk.to Agent App](https://www.tawk.to/downloads/)

### 6. Customize the Widget

In Tawk.to Administration > Chat Widget:

- Change widget color to match your brand
- Set online/offline hours
- Add pre-chat form (collect name/email before chat)
- Set up automated greetings
- Configure canned responses for quick replies

✅ All free - no subscription needed for basic features


---

# Local Notifications & Reminders

> Schedule reminders on the device - no server, no internet, exact alarms included.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/local-notifications-and-reminders

Show instant notifications, or schedule reminders that fire even when the app is closed - on-device, no server

### 1. What this adds

Your app can show Android notifications from its own code - two levels:

- Instant (Tier 1): a notification that appears right now, while the app is open. Good for 'download complete', 'timer finished', etc.

- Scheduled reminders (Tier 2): a notification that fires at a future time even when the app is CLOSED, and survives a reboot. This is what reminder, habit, alarm and medication apps need.

These are 100% on-device and offline - no server, no OneSignal account. (OneSignal push is a separate feature for messages YOU send from a server.)

### 2. Turn it on in the build wizard

In Step 3 (Permissions), tick:

- 🔔 Notifications - lets the app post notifications (adds POST_NOTIFICATIONS).
- ⏰ Reminders - adds scheduled notifications that fire when the app is closed (adds the exact-alarm + reschedule-on-boot plumbing). Ticking Reminders auto-enables Notifications.

Leave both off for apps that don't need notifications - nothing extra is added to your APK.

### 3. Call the bridge from your web code

AppMint exposes a JavaScript bridge at window.WebToApk. Always feature-detect it first - it only exists inside the installed app, so your site still works in a browser.

```
const b = window.WebToApk || null;

// Ask once (Android 13+):
b?.requestNotificationPermission();

// Tier 1 — instant (app open):
b?.showNotification('Saved', 'Your note was saved', '', 'note');

// Tier 2 — scheduled reminder in 1 hour:
b?.scheduleNotification(
  'water-1',
  'Drink water',
  'Time for a glass of water',
  String(Date.now() + 60*60*1000),
  'daily'   // none | minutely | hourly | daily | weekly
);

b?.cancelNotification('water-1');
b?.cancelAllNotifications();
const pending = JSON.parse(b?.getScheduledNotifications() || '[]');
```

### 4. Let the AI wire it for you

In AI App Studio, just describe what you want - e.g. 'a water reminder that pings me every 2 hours' or 'a medication tracker that reminds me at 8am daily'. When your request mentions reminders/alarms/notifications, AppMint automatically teaches the AI about this bridge so the generated app uses it correctly (with a graceful fallback when it isn't available).

### 5. Your own sound instead of the Android default

Put an audio file in your web bundle (mp3, wav, ogg, m4a, flac or opus) and name its path as the sound. It works the same on an instant notification and on a reminder that fires days later with the app closed.

The file is copied into place when you schedule, so a wrong file name comes back as false straight away instead of turning into the default sound at 7am.

One Android rule worth knowing: a notification channel's sound is fixed when the channel is created, so AppMint makes a separate channel per sound. Changing a sound therefore resets that channel's own settings in Android's notification screen - unavoidable, and the honest behaviour.

```
const b = window.WebToApk || null;

// Instant, with your sound:
b?.notify(JSON.stringify({
  title: 'Order confirmed',
  body:  'Arriving Tuesday',
  sound: '/audio/chime.mp3'   // a file in YOUR bundle
}));

// Check a sound before you save it in a settings screen:
const ok = b?.prepareNotificationSound('/audio/chime.mp3');

// 'silent' for no sound at all; leave it out for the Android default.
```

### 6. Reminders with sound, pictures and buttons

scheduleNotificationEx() takes everything notify() takes, plus when to fire it. Use it instead of the older five-argument scheduleNotification() when you want anything more than a title and a body.

```
const b = window.WebToApk || null;

b?.scheduleNotificationEx('dose-1', JSON.stringify({
  at: Date.now() + 60*60*1000,  // epoch millis
  repeat: 'daily',              // none|minutely|hourly|daily|weekly
  title: 'Time for your dose',
  body: 'Vitamin D — 1 tablet',
  sound: '/audio/chime.mp3',
  actions: [{ id: 'taken', label: 'Taken' }]
}));

// Returns false if the sound file does not exist — check it.
```

### 7. Opening the app itself at a set time

Add openApp: true and the reminder becomes a full-screen alert: on a locked phone the app opens over the lock screen, on an unlocked one it appears as a heads-up banner.

This is the whole of what Android allows. An app cannot silently launch itself in the background - that has been blocked since Android 10 - so any page that promises 'the app just opens at 7am' has to go through this. On Android 14+ the user grants the alert per app; check canOpenAppAtTime() and send them to the settings screen if it says denied.

When the app opens this way your page gets an appmint:reminder event, so it can run the work it could not do while closed.

```
const b = window.WebToApk || null;

if (b?.canOpenAppAtTime() === 'denied') b?.requestOpenAppPermission();

b?.scheduleNotificationEx('standup', JSON.stringify({
  at: tomorrowAt9am, repeat: 'daily',
  title: 'Stand-up', body: 'Daily sync starts now',
  sound: '/audio/alarm.mp3',
  openApp: true
}));

window.addEventListener('appmint:reminder', e => {
  // e.detail = { id: 'standup', overLockScreen: true }
  showReminderScreen(e.detail.id);
});
```

### 8. Reliability on real devices

Scheduled reminders are as reliable as Android allows:

- On Android 12+, exact timing needs SCHEDULE_EXACT_ALARM. If it is off for your app, the reminder is still armed but Doze may batch it by minutes. Ask getAlarmPrecision() - it answers 'exact' or 'inexact' - and call requestExactAlarms() to send the user to the setting rather than letting them think your app is late.
- Some aggressive phones (Xiaomi, Samsung, Oppo, etc.) kill background alarms to save battery. For critical reminders, ask users to disable battery optimization for your app.
- Reminders are re-armed automatically after a reboot or an app update.


---

# AppMint Push - Notify Your Users

> Send a notification to every installed copy of your AppMint app from a web dashboard.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/appmint-push

Send notifications to everyone who installed your app, straight from AppMint on your own Firebase project - schedule, edit after sending, cancel, deep links

### 1. How It Works

AppMint Push sends notifications to everyone who installed your app, from inside AppMint - send now, schedule, edit after sending, cancel, deep links.

It runs on YOUR OWN Firebase project: your users, your project, no shared limits, and nothing of yours hosted by AppMint. Firebase Cloud Messaging is free with no message limit.

You need two files from that project - google-services.json (for the build) and a service-account key (for sending). The next steps get both. Works with every build mode: website, ZIP, HTML and AI.

AppMint Push and OneSignal are alternatives: turning one on turns the other off.

### 2. Create a Firebase Project

Go to Firebase Console and click 'Add project' (or open a project you already have). A free Firebase project is enough - no billing needed for notifications.

One project can hold several of your apps.

[Open Firebase Console](https://console.firebase.google.com)

### 3. Add Your App and Download google-services.json

In your Firebase project:

- Click 'Add app' and choose Android
- Enter the package name EXACTLY as set in the AppMint wizard (e.g. com.yourname.yourapp) - a mismatch means notifications never arrive, and AppMint refuses the build for it
- Click 'Register app' and download google-services.json
- You can skip the remaining SDK steps - AppMint handles them

### 4. Turn It On and Upload the File

In the build wizard's Push Notifications card:

- Enable 'AppMint Push'
- Tap 'Upload google-services.json' and pick the file from the previous step

The wizard checks the file contains your package name. Then build your APK as normal - during the build your app is registered for push against your project.

Users just install the app and open it once. On Android 13+ they are asked to allow notifications after the first screen loads.

### 5. Upload Your Service-Account Key (Once)

AppMint sends through your project, so it needs a key from it - the same file OneSignal asks for.

In Firebase Console:

- ⚙ Project settings → 'Service accounts' tab
- Click 'Generate new private key' and confirm - a JSON file downloads

In AppMint: Home > Notifications → pick your app → 'Upload key' → choose that JSON.

AppMint verifies the key with a test send to your project before storing it (encrypted), so a green tick means the next send will really go out. One upload per app; rebuilding the app does not need it again unless you switch Firebase projects.

⚠️ Upload the SERVICE-ACCOUNT key here, not google-services.json - the screen tells you if you mix them up. To revoke access later, delete the key in Firebase Console.

### 6. Send Your First Notification

In Home > Notifications:

- Pick your app
- Write a title (message, image and link are optional)
- Tap 'Send Notification'

Every phone with your app installed receives it. Use 'Preview' first to see it exactly as users will - including a real notification on your own phone.

### 7. Schedule for Later

In the compose form, tap the Delivery row and choose 'Schedule for later...', then pick a date and time. The notification goes out automatically at that moment.

Until it fires, you can edit or cancel it from the History list below.

### 8. Fix a Mistake After Sending

Tap any notification in History:

- 'Edit & resend' - replaces it IN PLACE on every device with the corrected version
- 'Cancel' - removes it from every phone where it has not been opened yet
- 'Delete' - same as cancel, and clears it from your history

⚠️ A notification the user already opened or dismissed cannot be taken back.

### 9. Open a Specific Page

The optional Link field controls what a tap opens:

- A full https:// address (great for website apps)
- An in-app route like #/offers

Your app's code can also read it any time:

```
const link = window.WebToApk?.getLaunchUrl?.();
window.addEventListener('appmint:deep-link',
  e => goTo(e.detail.url));
```

### 10. In-App Inbox (Optional)

Every push is also stored inside the installed app (last 50), so your app can show its own notifications screen with unread badges. This works in EVERY build mode - including website (URL) apps, where you just add these few lines to your own site.

Dismiss is a SWIPE, not a tiny ✕, and it is reversible - pair it with a brief Undo:

```
const B = window.WebToApk;
const inbox = JSON.parse(B?.getPushInbox?.() ?? "[]");
// [{id,title,body,imageUrl,link,receivedAt,read}]
const unread = inbox.filter(m => !m.read).length;

// live arrival while the app is open
window.addEventListener('appmint:push', e => {
  if (e.detail.type === 'received') showBanner(e.detail.message);
  refreshInbox();   // fires for 'revoked' too
});

B?.markPushRead?.(id);        // "" = mark all read
B?.dismissPushMessage?.(id);  // swipe away
B?.restorePushMessage?.(id);  // ...Undo
```

### 11. If Nothing Arrives on Your Test Phone

Almost always a limit on the TEST PHONE, not your app or your users.

Android allows roughly 100 push registrations per phone. Every FRESH install of an app that uses notifications takes one - so installing build after build while testing can use them all up, and that phone then stops receiving for newly installed apps.

Free up slots (this is what actually works):

- Uninstall test apps you no longer need - Android releases the slot each one was holding
- Or clear a test app's data: Settings > Apps > [that app] > Storage > Clear data - that releases its slot without uninstalling
- On an emulator, wiping it resets every slot at once

Restarting the phone does NOT help: these registrations are stored permanently, which is why they survive a reboot. Clearing Google Play Services' cache does not free them either.

Avoid it while testing:

- Keep ONE package name while you iterate - every different package name takes its own slot
- Install the new APK OVER the old one instead of uninstalling first - an update keeps the existing registration, a reinstall spends a new one
- Test on a spare phone or an emulator; wiping an emulator resets its slots instantly
- Delete test apps you have finished with

Also check the basics: the app was opened at least once after installing, and notifications are allowed for it in Android settings. The app re-subscribes on every launch, so it recovers by itself once slots free up - no rebuild needed.

### 12. Limits and Good Practice

- No limit on how many notifications you send - Firebase Cloud Messaging is free
- Title up to 120 characters; image links must be https://
- On the free plan a short ad plays before each send
- Test apps: remove them with the trash icon next to the app selector - this deletes the history and stored key in AppMint only; your Firebase project is untouched, and a rebuild adds the app back
- Rebuilding with a NEW google-services.json from the SAME project changes nothing: your key stays, existing installs keep receiving
- ⚠️ Moving the app to a DIFFERENT Firebase project is a clean break. Rebuild with the new google-services.json, upload the new project's key (AppMint drops the old one, since it could never send for the new project) - and know that phones still running the OLD version stop receiving until their users update. Notifications reach a project, and those installs are still listening to the old one
- Send sparingly: users uninstall apps that spam them


---

# OneSignal Integration

> Use OneSignal instead, for segments, scheduling and delivery reporting.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/onesignal-push

Push Notifications Setup

### 1. Create OneSignal Account

Sign up for a free OneSignal account to get started with push notifications. OneSignal provides unlimited push notifications for free.

[Go to OneSignal.com](https://onesignal.com)

### 2. Create New App

In OneSignal dashboard:

- Click 'New App/Website'
- Enter your app name
- Select 'Google Android (FCM)' as platform
- Click 'Next'

### 3. Create Firebase Project

You need a Firebase project for OneSignal to work. Go to Firebase Console and create a new project or use an existing one.

[Open Firebase Console](https://console.firebase.google.com)

### 4. Add Android App to Firebase

In your Firebase project:

- Click 'Add App' and select Android
- Enter your app's package name (MUST match the package name you set in the generator)
- Download 'google-services.json' file
- ⚠️ IMPORTANT: This is the file you will upload to the Web2APK Generator later.
- Click 'Continue' and finish setup

### 5. Create Firebase Service Account Key

OneSignal requires a Firebase Service Account JSON to send notifications from their server.

In Firebase Console:

- Go to Project Settings > Service accounts tab
- Click 'Generate new private key'
- Confirm and download the JSON file

⚠️ WARNING: This file is ONLY for the OneSignal Dashboard. Do NOT upload this file to the Web2APK generator.

[Open Firebase Console](https://console.firebase.google.com)

### 6. Configure OneSignal with Service Account

Back in OneSignal dashboard setup:

- When asked for Firebase credentials, choose 'Upload Service Account File'
- Upload the Service Account JSON you downloaded from Firebase
- Click 'Save & Continue'
- Copy your OneSignal App ID (you'll need this in the generator)

### 7. Setup in Web2APK Generator

In the generator app:

1. Enable 'OneSignal' toggle in Step 3
2. Click 'Upload google-services.json' button
3. Select the 'google-services.json' file (the one from Step 4)

⚠️ DO NOT upload the Service Account key from Step 5 here!

1. Paste your OneSignal App ID
2. Generate your APK

```
OneSignal App ID format:
12345678-1234-1234-1234-123456789012
```

### 8. Test Push Notifications

After installing your generated APK:

- Open the app on your device
- Go to OneSignal dashboard
- Navigate to 'Messages' > 'New Push'
- Compose and send a test notification
- You should receive it on your device within seconds

### 9. Important Notes

⚠️ Package Name: The package name in Firebase MUST exactly match your app's package name

⚠️ File Upload: Always upload google-services.json when using OneSignal, otherwise notifications won't work

⚠️ First Launch: Users must open the app at least once to receive notifications

✅ Free Forever: OneSignal is 100% free with unlimited notifications


---

# Immersive Kiosk Mode

> Lock the app to one screen for a shop counter, a museum or a demo unit.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/kiosk-mode

True Fullscreen Without Nav Bars

### 1. What is Immersive Kiosk Mode?

Immersive Kiosk Mode hides the Android navigation bar (back, home, recents) and the status bar permanently. The app takes over the entire screen.

Perfect for:

- Kiosk / POS terminals
- Gaming apps
- Digital signage displays
- Exhibition / demo tablets
- Restaurant ordering tablets

### 2. Enable in Generator

In Step 2 (Display Settings):

1. Scroll to 'Display Options'
2. Toggle ON 'Immersive Kiosk Mode'
3. Generate your APK

No code changes needed on your website - this is purely an Android-level feature.

### 3. How Users Exit

Users can still access navigation by swiping from the screen edge. The bars will appear briefly (translucent) and then auto-hide again.

⚠️ Important: If you combine this with 'Exit Confirmation', the user must swipe to reveal the back button. Consider your use case carefully.

💡 Tip: For true kiosk lockdown, also disable Pull-to-Refresh and set Link Mode to 'Internal'.

### 4. Best Practices

✅ Test thoroughly before deploying on kiosk devices

✅ Combine with Portrait or Landscape lock for single-orientation kiosks

✅ Disable Zoom for touch-screen kiosks

⚠️ Not recommended for general consumer apps - users may get confused

⚠️ Google Play policy: Kiosk apps should clearly state their purpose


---

# Picture-in-Picture (PiP)

> Float the video in a corner while the user does something else.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/picture-in-picture

Floating Video Window Support

### 1. What is Picture-in-Picture?

PiP allows your app to continue showing content in a small floating window when the user presses Home or switches apps.

Perfect for:

- Video streaming apps (YouTube-style)
- Live sports / event websites
- Video conferencing web apps
- Music visualizer websites
- Educational video platforms

### 2. Enable in Generator

In Step 2 (Display Settings):

1. Scroll to 'Display Options'
2. Toggle ON 'Picture-in-Picture (PiP)'
3. Generate your APK

Requires Android 8.0 (API 26) or higher. Older devices will ignore this setting gracefully.

### 3. How It Works

When PiP is enabled:

1. User is watching video / using your app
2. User presses Home button
3. App shrinks to a small floating window
4. User can interact with other apps while watching
5. Tapping the PiP window returns to full app

The PiP window shows whatever the WebView was displaying at the moment.

### 4. Website Optimization (Optional)

Your website can detect PiP mode and optimize the view. When the window shrinks, you may want to hide menus and show only the video.

```
// Detect PiP mode in your website JS:
document.addEventListener('resize', function() {
  if (window.innerWidth < 300) {
    // PiP mode - show only video
    document.querySelector('.navbar').style.display = 'none';
    document.querySelector('video').style.width = '100%';
  } else {
    // Full mode - restore UI
    document.querySelector('.navbar').style.display = 'block';
  }
});
```

### 5. Limitations

⚠️ Android 8.0+ only (API 26)

⚠️ Some devices may not support PiP (e.g., Android Go edition)

⚠️ PiP window size is controlled by Android, not your app

✅ Works with both video and non-video content

✅ No website changes required - works out of the box


---

# Background Audio Playback

> Keep playing when the user leaves the app or turns the screen off.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/background-audio

Keep Audio Playing When Minimized

### 1. What is Background Audio?

When enabled, audio/music playing in your WebView will continue playing even when the user switches to another app or turns off the screen.

Perfect for:

- Music streaming websites (SoundCloud, Bandcamp)
- Podcast platforms
- Radio stations
- Audio meditation / prayer apps
- YouTube music channels

### 2. Enable in Generator

In Step 2 (Display Settings):

1. Scroll to 'Display Options'
2. Toggle ON 'Background Audio Playback'
3. Generate your APK

No code changes needed on your website.

### 3. How It Works

Normally, when an Android app goes to the background, its WebView pauses all media playback. With Background Audio enabled:

- WebView is NOT paused when app goes to background
- Audio continues playing via the device speaker or headphones
- Video playback also continues (audio portion)

💡 Tip: Combine with PiP for video sites so users can watch in a floating window AND keep audio when the window is dismissed.

### 4. Battery Considerations

⚠️ Background audio keeps the WebView process alive, which uses more battery.

✅ Recommended: Only enable for apps that genuinely need background audio

✅ Users can still stop playback by pausing on your website or force-stopping the app

✅ Android's battery optimization may eventually pause background apps - this is normal system behavior.

### 5. Website Best Practices

For the best background audio experience, ensure your website:

✅ Uses the HTML5 <audio> or <video> elements  
✅ Has play/pause controls easily accessible  
✅ Handles the 'visibilitychange' event gracefully  
✅ Does not auto-pause media when the page loses focus

```
// Prevent auto-pause on visibility change:
document.addEventListener('visibilitychange', function() {
  // Don't pause audio when tab/app is hidden
  if (document.hidden) {
    // Keep playing - do nothing
  }
});
```


---

# Sensors, Files & Background Jobs

> Accelerometer, Bluetooth sensors, file access and work that keeps running when the app is closed.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/sensors-files-and-background-jobs

Pair BLE fitness sensors, receive FIT/GPX/TCX files, run jobs while closed

### 1. Receive files, photos, videos and links from other apps

Turn on 'Receive Shares From Other Apps' in the wizard and tick what your app accepts - text and links, data files (FIT, GPX, TCX, CSV, JSON, XML…), photos, videos, audio, documents. Your app appears in TWO places, for exactly those kinds:

1. Android's 'Open with' sheet when a user taps a file.
2. The SHARE / EXPORT sheet other apps show - including sport devices exporting workout files (.fit, .gpx, .tcx). Most fitness apps export via Share, which is why apps that only register 'Open with' never show up there.

Ask for the file with AppMint.getOpenedFile() - it waits for you, however late your page starts. f.kind is image, video, audio, document or data. Text formats (gpx, tcx, csv, json, xml…) arrive as a ready-to-use f.text; small binaries (.fit) as f.base64; every data file and document as a real File in f.file. Photos, videos and audio arrive as f.url, a streamable address for <video src> / <img src>, with f.getFile() when you need the bytes. There is no size limit. A shared link or caption is read with WebToApk.getSharedText().

```
// Ask on startup — the file waits, however late your page mounts
const f = await AppMint.getOpenedFile();   // null if opened normally
if (f) {
  if (f.name.endsWith('.gpx') || f.name.endsWith('.tcx')) {
    const xml = new DOMParser().parseFromString(f.text, 'text/xml');
    const points = xml.querySelectorAll('trkpt, Trackpoint');
    console.log('workout with ' + points.length + ' points');
  } else if (f.name.endsWith('.fit')) {
    // .fit is binary — a real File; parse its bytes
    parseFit(new Uint8Array(await f.file.arrayBuffer())); // e.g. fit-file-parser
  } else if (f.kind === 'video') {
    document.querySelector('video').src = f.url;   // streams from disk, seekable
  }
}

// A shared link or caption
const shared = JSON.parse(WebToApk.getSharedText() || 'null');
if (shared) console.log('shared:', shared.url || shared.text);
```

### 2. Pair Bluetooth fitness sensors (heart rate, speed, cadence…)

Turn on the Bluetooth permission in the wizard and your app can pair standard BLE sensors - every compliant chest strap and bike pod uses the same official Bluetooth profiles, so no per-brand code is needed:

- Heart rate straps → bpm
- Speed/cadence pods → km/h + pedal rpm
- Power meters → watts
- Running footpods → pace + steps/min
- Every sensor's battery level

Flow: scan (15s) → user picks a device → connect. Data then streams as events. Speed needs your wheel size; set it once (default 2096mm = 700x23c road wheel).

```
// 1. Scan — each found sensor fires a 'device' event:
window.addEventListener('appmint:ble', function (e) {
  const m = e.detail;
  if (m.kind === 'device') {
    // {address, name, sensors:['heart_rate','speed_cadence',...], rssi}
    addToPickerUI(m);
  }
  if (m.kind === 'data') {
    if (m.type === 'heart_rate')     showBpm(m.data.bpm);
    if (m.type === 'speed_cadence') {
      if (m.data.speedKmh)   showSpeed(m.data.speedKmh.toFixed(1));
      if (m.data.cadenceRpm) showCadence(Math.round(m.data.cadenceRpm));
    }
    if (m.type === 'power')   showWatts(m.data.watts);
    if (m.type === 'battery') showBattery(m.data.percent);
  }
  if (m.kind === 'error') console.warn('BLE:', m.error);
});

WebToApk.bleSetWheelCircumference(2105); // your wheel, in mm
WebToApk.bleStartScan();

// 2. When the user taps a device from your picker:
WebToApk.bleConnect(device.address);

// 3. Done training:
WebToApk.bleDisconnect();
```

### 3. Background jobs & durable auto-save (WorkManager)

JavaScript cannot run while your app is closed - that is Android, not AppMint. What CAN run is a native delivery job your page hands to the OS. Two tools:

1. workEnqueueOnline - durable one-shot delivery. Perfect auto-save: hand over the data and it POSTs to your server when there is network, retrying with backoff, surviving app kills and reboots. Re-using the same job id replaces the pending save with the newest state.

1. workSchedulePeriodic - a recurring native HTTP call (sync trigger, heartbeat). Android's minimum interval is 15 minutes; shorter values are clamped.

Both deliver YOUR payload to YOUR URL - the server side is a normal endpoint you already have (Supabase edge function, your API…).

```
// Durable auto-save: call this on every important change.
function autoSave(state) {
  WebToApk.workEnqueueOnline(
    'autosave',                          // same id → newest state wins
    'https://api.example.com/save',
    'POST',
    JSON.stringify({ 'Authorization': 'Bearer ' + token }),
    JSON.stringify(state)
  );
}

// Recurring sync every 30 minutes, even if the app is closed:
WebToApk.workSchedulePeriodic(
  'sync', 'https://api.example.com/sync', 'POST', '{}', '', 30
);

// Manage jobs:
WebToApk.workCancel('sync');
WebToApk.workList('req1');
window.addEventListener('appmint:work', function (e) {
  // {id, status:'enqueued'|'scheduled'|'cancelled'|'failed'}
  // or {requestId, jobs:[{id, state, attempts}]}
  console.log('work:', e.detail);
});
```

### 4. Checklist & common mistakes

- Files: the toggle must be ON at build time - it registers your app in Android's manifest, which cannot change after install. Rebuild after enabling.

- BLE: the Bluetooth permission toggle must be ON at build time. The FIRST scan asks the user for the runtime permission (Android 12+: 'Nearby devices'; older: Location - that is an Android rule for BLE scanning, your app does not read location).

- BLE: pair in YOUR app, not in Android's Bluetooth settings - BLE fitness sensors are not classic paired devices.

- Background jobs: don't schedule a periodic job to 'run my page code' - it delivers HTTP to your server. If you need on-device processing while closed, that is what the delivery endpoint is for.

- Auto-save: always the SAME job id. Different ids queue up multiple stale saves.


---

# Native Fullscreen Video

> Native fullscreen for HTML5 video, with the rotation and cutout handling Android expects.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/fullscreen-video

Auto-Rotate & Immersive Video Player

### 1. Built-in Fullscreen Video

Your generated app already supports native fullscreen video playback. When a user taps the fullscreen button on an HTML5 <video> element, the app:

- Enters true immersive fullscreen
- Auto-rotates to landscape automatically
- Hides all navigation bars
- Restores portrait orientation when the user exits fullscreen

No configuration needed - this works automatically! The orientation lock is managed by the app, so even apps configured to portrait-only will correctly go landscape during video playback.

### 2. Supported Video Sources

The following video types work with fullscreen:

✅ HTML5 <video> elements  
✅ YouTube embeds (iframe)  
✅ Vimeo embeds  
✅ Self-hosted MP4/WebM videos  
✅ HLS streams (.m3u8)

⚠️ Some DRM-protected content may not enter native fullscreen

### 3. Website Video Best Practices

For the best video experience in your generated app:

```
<!-- Good: Standard HTML5 video -->
<video controls playsinline>
  <source src="video.mp4" type="video/mp4">
</video>

<!-- Good: YouTube embed -->
<iframe
  src="https://youtube.com/embed/VIDEO_ID"
  allowfullscreen>
</iframe>

<!-- Tip: Add 'playsinline' attribute
     for inline playback on iOS too -->
```

### 4. Combine with PiP

For the ultimate video experience, enable both Fullscreen Video (built-in) and PiP mode:

1. User watches video inline
2. Taps fullscreen → enters immersive landscape
3. Taps back → returns to normal view
4. Presses home → enters PiP floating window

This gives your users a YouTube-like experience in your web app!


---

# Chromecast / Smart TV

> Cast video from the app to a TV.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/chromecast-and-smart-tv

Cast Web Content to TV via JS Bridge

### 1. What is Chromecast Support?

Chromecast support lets users cast video/audio from your app to a TV or smart display. The app provides a JavaScript bridge that your website can call to initiate casting.

Perfect for:

- Video streaming websites
- Music platforms
- Photo galleries
- Presentation tools
- Digital signage control apps

### 2. How It Works

The generated app injects a JavaScript bridge (window.WebToApk) into your WebView. Your website can call this bridge to trigger native Android casting.

Flow:

1. User taps a 'Cast' button on your website
2. Your JS calls window.WebToApk.castMedia(url)
3. Android opens the native media sharing/casting chooser
4. User selects their Chromecast device
5. Media plays on the TV

### 3. Add Cast Button to Your Website

Add a Cast button to your website that calls the JS bridge:

```
<!-- Add a Cast button -->
<button id="castBtn" onclick="castToTV()">
  📺 Cast to TV
</button>

<script>
function castToTV() {
  var videoUrl = document.querySelector('video')?.src
    || 'https://yoursite.com/video.mp4';
  
  if (window.WebToApk && window.WebToApk.castMedia) {
    window.WebToApk.castMedia(videoUrl);
  } else {
    alert('Casting is only available in the app');
  }
}
</script>
```

### 4. Supported Media Types

The cast bridge supports these media types:

✅ Direct video URLs (MP4, WebM)  
✅ Audio URLs (MP3, AAC, OGG)  
✅ HLS streams (.m3u8)  
✅ DASH streams (.mpd)

⚠️ DRM-protected content requires additional Chromecast receiver app setup

⚠️ Web pages (HTML) cannot be cast directly - only media URLs

### 5. Detect App Environment

Your website can detect whether it's running inside the generated app to show/hide the cast button:

```
// Check if running inside WebToApk app
if (window.WebToApk) {
  // Running in the app — show cast button
  document.getElementById('castBtn')
    .style.display = 'block';
} else {
  // Running in a browser — hide cast button
  document.getElementById('castBtn')
    .style.display = 'none';
}
```

### 6. Fallback for Browser

If your website is also accessed from a regular browser, the window.WebToApk object won't exist. Always check before calling:

✅ Use feature detection: if (window.WebToApk)  
✅ Provide a fallback message for browser users  
✅ Consider showing a 'Download our app for casting' banner


---

# Media Notification Bridge

> Lock-screen controls, artwork and the seek bar for audio your page is playing.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/media-notification-bridge

Lock-Screen Controls & Notification from Your Website JS

### 1. What Is the Media Notification Bridge?

When your website plays music or audio, Android doesn't know about it. There's no lock-screen player, no album art, no media buttons in the notification shade.

The Media Notification Bridge fixes this. Your JavaScript code tells Android:

- What song is playing (title, artist, cover art)
- Whether it's playing or paused

Android then shows a proper media notification with controls. When the user presses Play/Pause/Next/Prev on the notification or lock screen, Android calls back to your JavaScript so you can respond.

Think of it as a two-way bridge:  
Your Website JS  ⟷  Android Lock Screen / Notification

### 2. Enable in the Generator

In Step 4 of the generator:

1. Toggle ON '🎵 Media Notification'
2. Generate your APK

Now your website JS has access to window.WebToApk with media methods.

### 3. Step 1 - Tell Android What's Playing

Call this from your website JS whenever a new track starts. Android will update the notification and lock screen immediately.

```
// When a new song starts playing:
window.WebToApk.setMediaMetadata(
  'Bohemian Rhapsody',          // track title
  'Queen',                       // artist name
  'https://yoursite.com/art.jpg' // cover art URL (or '' to skip)
);
```

### 4. Step 2 - Update Play / Pause State

Call this whenever playback starts, pauses, or the position changes. Android uses this to show the right button (▶ or ⏸) and fill the seek bar.

```
// When playback starts:
window.WebToApk.setPlaybackState(
  true,   // isPlaying (true = playing, false = paused)
  30000,  // current position in milliseconds (30 seconds)
  240000  // total duration in milliseconds (4 minutes)
);

// When the user presses pause on your site:
window.WebToApk.setPlaybackState(false, 30000, 240000);
```

### 5. Step 3 - Listen for Button Presses

The user can press Play/Pause/Next/Prev on the notification or lock screen. Your website must define this callback function to receive those actions and respond to them.

```
// Define this ONCE, early in your page JS:
window.WebToApkOnMediaAction = function(action) {
  switch (action) {
    case 'play':
      myAudioPlayer.play();
      break;
    case 'pause':
      myAudioPlayer.pause();
      break;
    case 'next':
      playNextTrack();
      break;
    case 'prev':
      playPrevTrack();
      break;
    case 'stop':
      myAudioPlayer.pause();
      myAudioPlayer.currentTime = 0;
      break;
  }
};
```

### 6. Step 4 - Clear Notification When Stopped

When the user stops playback entirely (not just pauses), call this to revert the notification back to the basic 'Running in background' message and remove the media controls.

```
// When user stops / closes the player:
window.WebToApk.clearMediaNotification();
```

### 7. Why Play/Pause works automatically, but Next/Prev requires code

Our app includes an 'Automatic Media Tracker'. If you don't write any custom code, the app will automatically detect when standard <video> or <audio> tags are playing, and it will make the Play and Pause buttons work automatically as a fallback.

However, standard HTML5 media players do NOT have a universal 'Next' or 'Previous' command (since they don't inherently support playlists). To make Next/Prev work, your website MUST explicitly use the standard MediaSession API (navigator.mediaSession.setActionHandler) or define the window.WebToApkOnMediaAction callback to tell the app exactly what to do when those buttons are pressed.

### 8. Full Working Example

Complete example - paste this into your website to wire up an HTML5 audio element to the Android media notification:

```
var audio = document.getElementById('myAudio'); // your <audio> element

// — Send metadata when track loads —
audio.addEventListener('loadedmetadata', function() {
  window.WebToApk.setMediaMetadata(
    document.title,
    'My Radio Station',
    'https://yoursite.com/logo.png'
  );
});

// — Keep Android in sync with playback state —
audio.addEventListener('play', function() {
  window.WebToApk.setPlaybackState(
    true,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});
audio.addEventListener('pause', function() {
  window.WebToApk.setPlaybackState(
    false,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});

// — Receive lock-screen button presses —
window.WebToApkOnMediaAction = function(action) {
  if (action === 'play')  audio.play();
  if (action === 'pause') audio.pause();
  // next / prev: implement your playlist logic here
};
```

### 9. What the Notification Looks Like

The media notification shows in the pull-down shade and on the lock screen:

┌───────────────────────────────────────┐  
│  🎵  [Your App Name]                  │  
│  Bohemian Rhapsody                    │  
│  Queen                                │  
│  [album art]   ⏮  ⏸  ⏭              │  
└───────────────────────────────────────┘

- ⏮ Prev - calls your WebToApkOnMediaAction('prev')
- ⏸ / ▶ - calls 'pause' or 'play'
- ⏭ Next - calls 'next'

Bluetooth headset buttons and Android Auto also trigger the same callbacks automatically.

### 10. Requirements & Limits

✅ Requires 'Foreground Service' toggle to also be ON (media notification needs the service running)

✅ Cover art is fetched from the URL you provide - must be a publicly accessible image (HTTPS preferred)

✅ Works with any HTML5 audio or video element, or any JS music player library

⚠️ If you don't call setPlaybackState(), the buttons will appear but Android won't know the current state - always call it after play/pause

⚠️ window.WebToApk is only available inside the generated app. Always guard calls with:  
if (window.WebToApk) { ... }

### 11. Safe Guard for Browser Testing

Your website also opens in regular browsers where window.WebToApk doesn't exist. Use this wrapper so the code doesn't crash in Chrome/Safari:

```
// Safe wrapper — works in both app and browser:
function sendToAndroid(method, args) {
  if (window.WebToApk && typeof window.WebToApk[method] === 'function') {
    window.WebToApk[method].apply(window.WebToApk, args);
  }
}

// Usage:
sendToAndroid('setMediaMetadata', ['Song Title', 'Artist', 'https://art.jpg']);
sendToAndroid('setPlaybackState', [true, 0, 240000]);
```


---

# Native Folder Access

> Read and write a real folder on the phone, with permission that survives reboots.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/native-folder-access

Use SAF-backed local folders from WebView and offline HTML apps

### 1. What This Feature Does

This feature gives your web app controlled access to one user-picked Android folder using the Storage Access Framework (SAF). It works well for offline HTML apps, editors, backup/restore flows, and import/export tools.

It does NOT give unrestricted device storage access. The user explicitly chooses one folder, and your app can only work inside that granted tree.

### 2. Enable in the Generator

In Step 4 of the generator, turn ON 'Native Folder Access (SAF)'. Then generate the app.

When enabled, your website gets a high-level helper at window.WebToApkFS in addition to the raw window.WebToApk bridge.

⚠️ Android 11+ Storage Note: On Android 11 and above, reading the shared storage requires the special 'All Files Access' permission. When your generated app launches for the first time and the storage permission is enabled, it automatically opens the Android Settings screen to let the user grant this permission. The user just taps the toggle in Settings and returns to the app - no manual navigation required.

### 3. Browser-Safe Capability Check

Always guard your code so it still runs in Chrome/Safari where the Android bridge does not exist:

```
function canUseNativeFiles() {
  return !!(window.WebToApkFS && window.WebToApkFS.isAvailable());
}

if (canUseNativeFiles()) {
  console.log('Android native folder access available');
}
```

### 4. Ask User to Pick a Folder

Call requestAccess() from a button click or other clear user action. It opens Android's folder picker and returns the chosen folder URI.

```
async function connectFolder() {
  const result = await window.WebToApkFS.requestAccess();
  if (!result.success) {
    alert('Folder access was not granted');
    return false;
  }
  console.log('Granted folder:', result.folderUri);
  return true;
}
```

### 5. Basic File Operations

Once access is granted, you can list folders, create directories, read text files, write text files, rename entries, and delete entries.

```
// Create folders
window.WebToApkFS.mkdir('notes');
window.WebToApkFS.mkdir('notes/2026');

// Write a file
window.WebToApkFS.writeText('notes/2026/today.txt', 'Hello from offline app');

// Read it back
const text = window.WebToApkFS.readText('notes/2026/today.txt');
console.log(text);

// List folder contents
const entries = window.WebToApkFS.list('notes/2026');
console.log(entries);
```

### 6. Rename and Delete

Rename changes only the final entry name. Delete supports both non-recursive and recursive directory deletion.

```
// Rename file or folder
window.WebToApkFS.rename('notes/2026/today.txt', 'journal.txt');

// Delete a single file
window.WebToApkFS.delete('notes/2026/journal.txt');

// Delete a folder tree
window.WebToApkFS.delete('notes/2026', { recursive: true });
```

### 7. Good Use Cases

✅ Offline note or journal apps  
✅ CSV / JSON import-export tools  
✅ Simple local backup and restore  
✅ Static HTML editors that save user content  
✅ Dashboard apps that export reports as text or CSV

### 8. Limitations

⚠️ This is Android-only. It will not exist in normal desktop/mobile browsers.

⚠️ Current helper is designed around folder listing and text files. Binary workflows need additional APIs.

⚠️ Access is scoped to the one folder the user granted.

⚠️ Call these APIs after the page is loaded so the helper has been injected.

### 9. Full Working Example

This example connects a folder, creates a workspace directory, writes a JSON file, and renders the folder listing:

```
async function setupWorkspace() {
  if (!window.WebToApkFS || !window.WebToApkFS.isAvailable()) {
    console.log('Native folder access not available in this browser');
    return;
  }

  if (!window.WebToApkFS.hasAccess()) {
    const granted = await window.WebToApkFS.requestAccess();
    if (!granted.success) return;
  }

  window.WebToApkFS.mkdir('workspace');
  window.WebToApkFS.writeText(
    'workspace/config.json',
    JSON.stringify({ updatedAt: new Date().toISOString(), mode: 'offline' }, null, 2)
  );

  const files = window.WebToApkFS.list('workspace');
  document.getElementById('output').textContent = JSON.stringify(files, null, 2);
}
```


---

# Web APIs Bridge

> Which standard browser APIs work inside the app, and which need the native bridge instead.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/web-apis-bridge

Native Polyfills for Notifications, Share, Clipboard & More

### 1. What are Web API Bridges?

Android WebView doesn't support several modern Web APIs that Chrome does. Your generated app automatically polyfills these APIs so websites work just like they do in Chrome:

✅ Web Notifications (Notification API)  
✅ Web Share (navigator.share)  
✅ Clipboard (navigator.clipboard)  
✅ window.close()  
✅ target="_blank" links & window.open()

No setup needed - these work automatically in every generated app.

### 2. Web Notifications

Websites that use Notification.requestPermission() and new Notification() will show real Android notifications.

- On Android 13+, the user gets a system permission dialog
- On Android 12 and below, notifications are allowed by default
- Tapping a notification opens the app
- The 'tag' option replaces previous notifications (matches Web spec)

```
// Your website JS — works the same as in Chrome:
Notification.requestPermission().then(function(result) {
  if (result === 'granted') {
    new Notification('Hello!', {
      body: 'This is a native Android notification',
      tag: 'my-notif'
    });
  }
});
```

### 3. Web Share API

navigator.share() opens the Android native share sheet, letting users share content to WhatsApp, Telegram, email, etc.

- Supports title, text, and url
- navigator.canShare() returns true
- Works exactly like Chrome's share dialog

```
// Share content from your website:
navigator.share({
  title: 'Check this out',
  text: 'Amazing content!',
  url: 'https://example.com/page'
});
```

### 4. Clipboard API

navigator.clipboard.writeText() and readText() are bridged to Android's native clipboard.

- writeText() copies text to system clipboard
- readText() reads from system clipboard
- Both return Promises (matching the Web spec)

```
// Copy to clipboard:
await navigator.clipboard.writeText('Hello World');

// Read from clipboard:
const text = await navigator.clipboard.readText();
```

### 5. window.close() & target="_blank"

Two common WebView gaps are also fixed:

- window.close() - closes/finishes the app activity (useful for payment/auth callback pages)
- target="_blank" links - load inside the WebView instead of being silently dropped
- window.open() calls - handled the same way

No website changes needed - these just work.

### 6. Domain Matching for External Links

When 'External Links → Open in Browser' is set, the app intelligently matches domains:

- google.com and www.google.com are treated as the same domain
- Only truly different domains open in Chrome
- Redirects within the same site stay in the WebView

This prevents the issue where a site like google.com redirects to www.google.com and accidentally opens in Chrome.

### 7. UPI & Payment App Links (Razorpay, GPay, PhonePe, Paytm)

Any link whose scheme isn't a web page automatically opens the Android app that owns it - no setup, no scheme list to configure:

- upi://pay - generic UPI intent (the user picks their UPI app)
- paytmmp:// (Paytm), phonepe://, tez:// (Google Pay), gpay://
- tel:, mailto:, sms:, whatsapp://, tg://, intent://

This works everywhere a page can navigate:  
✅ A tapped <a href="upi://pay?..."> link  
✅ A JS redirect (window.location.href = 'upi://...')  
✅ A popup - window.open('paytmmp://...') - which is how Razorpay Checkout hands off to UPI apps

So Razorpay / Cashfree / PhonePe checkout pages work as-is: the customer taps a UPI option, the payment app opens, they approve, and your page's success handler fires when they return. If no app on the phone can handle the scheme, the user sees a clear toast instead of a blank error page.

⚠️ Selling DIGITAL goods in a Play Store app? Google requires Play Billing for those - use the IAP guide instead. UPI/card checkout is for physical goods, services, and apps distributed outside Play.

```
<!-- Simplest form — a plain UPI intent link. The user's phone
     shows every installed UPI app (GPay/PhonePe/Paytm/BHIM): -->
<a href="upi://pay?pa=merchant@bank&pn=MyStore&am=99.00&cu=INR&tn=Order%20123">
  Pay ₹99 via UPI
</a>
```

### 8. Complete Example - Razorpay Checkout with UPI, End to End

A full, copy-pasteable flow using Razorpay Checkout. What happens on the phone:

1. Customer taps 'Pay ₹499' → Razorpay Checkout opens in the page
2. Customer picks UPI → their UPI app opens automatically (this is the paytmmp:// / phonepe:// hand-off the app handles for you)
3. Customer approves in the UPI app and returns - Android brings your app back on its own
4. The handler function fires with a payment ID → show your success screen
5. dismiss fires if they cancel → let them retry

Replace rzp_test_XXXXXXXX with your key from dashboard.razorpay.com. Test with a key_test key first - Razorpay's test mode simulates UPI approval.

⚠️ For a real store, confirm the payment server-side (Razorpay webhook or Orders API + signature check) before shipping goods - the browser-side handler alone can be faked.

```
<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>

<h2>Premium Plan — ₹499</h2>
<button id="payBtn">Pay ₹499</button>
<p id="result"></p>

<script>
document.getElementById('payBtn').onclick = function () {
  var rzp = new Razorpay({
    key: 'rzp_test_XXXXXXXX',      // your Razorpay Key ID
    amount: 49900,                  // paise — ₹499.00
    currency: 'INR',
    name: 'My Store',
    description: 'Premium Plan',
    prefill: { contact: '', email: '' },
    theme: { color: '#2563eb' },

    // Fires after the customer returns from their UPI app
    handler: function (response) {
      document.getElementById('result').textContent =
        '✅ Paid! Payment ID: ' + response.razorpay_payment_id;
      // Real store: send response.razorpay_payment_id to your
      // server / webhook flow and verify before unlocking anything.
    },

    modal: {
      ondismiss: function () {
        document.getElementById('result').textContent =
          'Payment cancelled — tap Pay to try again.';
      }
    }
  });
  rzp.open();
};
</script>
```


---

# Block Screenshots on a Page

> Turn off screenshots and screen recording for pages that show something private.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/block-screenshots

Let one page in your app turn off screenshots, screen recording and the recents preview - and give it back when the user leaves

### 1. What this does

One line from your page turns on Android's screen-capture block for the screen the user is looking at:

- screenshots fail (the user gets Android's "can't take screenshot" message)
- screen recording and casting show a black frame
- the app's preview in the recents screen is hidden

What it cannot do - and nothing on Android can - is stop someone photographing the screen with another phone. If you need that, you need a watermark, not a flag.

```
const b = window.WebToApk || null;

// On the sensitive screen:
b?.setSecureScreen(true);

// Leaving it early (a modal closing, a tab switch inside one page):
b?.setSecureScreen(false);

// Current state:
const locked = b?.isSecureScreen();
```

### 2. Protect one page, not the whole app

Protection belongs to the page that asked for it. AppMint releases it the moment the app navigates anywhere else - a new page, a pushState route, a #hash route - so your statement screen can be protected while the rest of the app takes screenshots normally.

That also means a page has to ask again after a reload: a fresh document has not asked for anything yet, and inheriting the last one's answer is how apps end up locked down on screens nobody meant to protect.

### 3. In a single-page app

Route changes inside one page release protection automatically, so the usual pattern is to assert it when the protected view mounts and let navigation do the rest.

```
function showStatement() {
  render(statementView);
  window.WebToApk?.setSecureScreen(true);
}

// Nothing to undo on the way out — moving to another route
// releases it. Call setSecureScreen(false) yourself only when
// you hide the sensitive content WITHOUT navigating.
```

### 4. Do not use a timer for this

A common idea is to re-assert protection on an interval, say every second, and let it lapse when the page stops asking. It does not work, and it is worth knowing why: Android does not consult your app when the user presses the screenshot buttons. The flag has to already be on the window. Any second where your page is busy, throttled in the background, or between timer ticks is a second in which the screenshot succeeds.

Ask once when the sensitive content appears. AppMint takes protection away when the user leaves.


---

# Deep Linking

> Open a specific page in the app from a link, a QR code or a notification.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/deep-linking

Open Specific Pages from URLs & Notifications

### 1. What is Deep Linking?

Deep Linking allows external sources (browsers, SMS, emails, social media, push notifications, QR codes) to open your app directly to a specific page instead of the homepage.

Your app supports two kinds, and they are NOT equally easy:

1. ⚡ Custom Scheme (myapp://path) - works immediately, nothing to set up. Best for push notifications and QR codes.

1. 🌐 https:// links (https://mysite.com/page) - needs ONE file uploaded to your website. Without it Android keeps the link in the browser and your app never opens. This is the single most common reason deep links 'do not work'.

Both are covered below. If you only need something working today, use the custom scheme.

### 2. How Custom Scheme URLs Work

When a custom scheme link is tapped (e.g., myapp://products/shoes), the app:

1. Receives the custom scheme URL
2. Automatically maps it to your website URL
3. Opens the WebView to the correct page

✅ The scheme is derived from your App Name (lowercase, letters only).

✅ Example mapping:  
myapp://products/shoes  
→ https://mysite.com/products/shoes

The path segments after the scheme are preserved and appended to your website domain.

```
Custom scheme format:
  <appname>://<path>

Examples:
  myshop://cart
  → https://myshop.com/cart

  puma://in/en/help
  → https://in.puma.com/in/en/help
```

### 3. https:// links - one file must go on your website

This is the part people miss, so read it before testing.

AppMint puts your domain in the app automatically. But Android will NOT open your app from an https:// link until your WEBSITE proves the app belongs to you. On Android 12 and newer, an unproven link just opens the browser - no dialog, no choice. That is why a link can look like it 'does nothing'.

The proof is one small file. AppMint already made it for you: after you build, look in Downloads for assetlinks.json. It contains your package name and your app's signing fingerprint.

Upload it to your website at EXACTLY this address (the folder name starts with a dot):

```
https://yoursite.com/.well-known/assetlinks.json

Rules — all four must be true:
  1. Served over https (not http)
  2. Content-Type: application/json
  3. NO redirect (a redirect to www breaks it)
  4. Reachable publicly — no login, no Cloudflare challenge

Check it from any computer:
  curl -i https://yoursite.com/.well-known/assetlinks.json
```

### 4. Publishing on Google Play? Use Play's fingerprint

Google Play re-signs your app with ITS own key. So the fingerprint inside the assetlinks.json AppMint generated - which is your local key - will not match what users actually install from Play.

If you publish on Play, replace the fingerprint:

1. Play Console → your app → Test and release → Setup → App integrity
2. Copy the SHA-256 from 'App signing key certificate'
3. Put that value in assetlinks.json and re-upload it

You can list BOTH fingerprints in the same file - the local one for APKs you share directly, and Play's for Play installs. That way both work.

```
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.name",
    "sha256_cert_fingerprints": [
      "AA:BB:...",   // your local key (direct APK)
      "11:22:..."    // Play App Signing key
    ]
  }
}]
```

### 5. Check whether Android accepted it

After uploading the file, REINSTALL the app (Android only checks at install time, and it can take a minute).

The command below tells you the truth. Look for your domain with 'verified'. If it says 'legacy_failure' or the domain is missing, the file is not being read correctly - go back and check the four rules.

```
# Does Android consider your domain verified?
adb shell pm get-app-links com.yourapp.name

# Force a re-check without reinstalling (Android 12+):
adb shell pm verify-app-links --re-verify com.yourapp.name

# Google's own checker (open in a browser):
https://digitalassetlinks.googleapis.com/v1/statements:list?
  source.web.site=https://yoursite.com&
  relation=delegate_permission/common.handle_all_urls
```

### 6. Why it usually fails

In order of how often each one is the cause:

1. The file is not uploaded, or is at the wrong path. It must be /.well-known/assetlinks.json - with the dot.

1. www vs no-www. Android treats https://example.com and https://www.example.com as DIFFERENT domains. AppMint registers the exact host from your Website URL. If you use both, put the file on both, and tell us which host you entered.

1. A redirect. Many hosts redirect the apex domain to www. That breaks verification even though the file loads in a browser.

1. Published on Play but using the local fingerprint - see the previous step.

1. Not reinstalled after uploading. Android checks at install time.

Custom scheme links (myapp://...) need NONE of this and always work - use them for push notifications and QR codes if you want something working today.

### 7. Testing Deep Links via ADB

Test your deep links from a PC connected via USB debugging:

1. Enable USB Debugging on your phone
2. Connect via USB
3. Run the commands below.

⚠️ Important: 'am start' with an https link can open your app even when verification has FAILED, because you are handing the link straight to Android. It does not prove a real tap in Gmail or Chrome will work. Only 'pm get-app-links' (previous step) tells you that. Use am start to check your PAGE routing, not your domain setup.

```
# Test custom scheme:
adb shell am start -a android.intent.action.VIEW \
  -d "myapp://some/page"

# Test website URL:
adb shell am start -a android.intent.action.VIEW \
  -d "https://mysite.com/some/page"

# Verify which app handles it:
adb shell cmd package resolve-activity --brief \
  -a android.intent.action.VIEW \
  -d "myapp://some/page"
```

### 8. Deep Links in Push Notifications

When sending a push notification via OneSignal, paste any deep link URL into the 'Launch URL' field. The app will open and navigate directly to that page.

Both URL types work:  
✅ https://mysite.com/flash-sale  
✅ myapp://flash-sale

```
OneSignal Dashboard → New Push:

Launch URL: https://mysite.com/flash-sale
  OR
Launch URL: myapp://flash-sale

Both will open the app on the sale page.
```

### 9. Important: Warm Launch Behaviour

If your app is already running in the background when a deep link is triggered, Android delivers the link directly without restarting the app - this is called a 'warm launch'.

✅ Your app handles this automatically. The WebView will navigate to the new page even when the app is already open.

⚠️ If deep links only open the homepage, check that:

- Your Website URL in config matches the domain in the deep link
- The path in the custom scheme URL is correct

⚠️ If https:// links do not open the app AT ALL, this is not a warm-launch problem - it is the assetlinks.json step above. Custom scheme links working while https links do nothing is the classic sign.

```
Warm launch works automatically.
No extra setup needed.
```


---

# Offline Website Pro

> Ship the site inside the APK so it opens with no connection at all.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/offline-website

Convert ZIP to High-Performance Offline App

### 1. Prepare Your Website Files

Collect all your HTML, CSS, JS, and image files into a single folder. Ensure your main entry file is named 'index.html'.

Tips:

- Use relative paths for all assets (e.g., <img src="images/logo.png">)
- Avoid absolute paths (e.g., /C:/Users/...)
- Keep filenames and folder names case-sensitive (Android is Linux-based)

### 2. Create a ZIP Archive

Compress your website files into a standard .zip archive.

Recommended structure:

- index.html
- style.css (optional)
- script.js (optional)
- images/... (optional)

✅ The generator accepts both:

1. ZIP with files directly at root
2. ZIP containing one parent folder (auto-detected)

⚠️ Avoid deep nesting like project/build/site/index.html unless that is your intended web root.

### 3. Quick Minimal Test (Exact)

Use this exact test to verify your setup:

1. Create a folder named test_site
2. Add one file named index.html
3. Paste your sample HTML into index.html
4. Zip it as test_site.zip
5. In Step 1, choose Offline ZIP and select test_site.zip
6. Generate APK and install

If this opens correctly, your pipeline is fine and larger-project blank screens are usually path or asset issues.

```
test_site.zip
└── index.html
```

### 4. Select Offline Mode

In the Web2APK Generator (Step 1):

1. Select the 'Offline ZIP' radio button
2. Click the 'Choose Website ZIP' button
3. Select your prepared .zip file from your device storage

### 5. Generate Your APK

Complete the rest of the steps (App Name, Icon, Splash, etc.) and click 'Generate APK'. Your website will now run entirely offline without needing an internet connection!

### 6. Troubleshooting

❌ Blank screen? Open index.html in a browser first and check for JS errors.  
❌ Blank screen with simple ZIP? Rebuild with latest generator version (offline extraction fix included).  
❌ Broken images/CSS/JS? Verify paths are relative (./assets/logo.png), not absolute (/assets/logo.png or C:\...).  
❌ CSS not loading? Check exact filename case (style.css vs Style.css).  
❌ JS modules failing? Ensure module file paths exist in the ZIP.


---

# CSS / JS Quick Injection

> Restyle or patch a website you are wrapping without editing the website.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/css-and-js-injection

Global Tweaks - Same CSS & JS on Every Page

### 1. What Is CSS/JS Quick Injection?

Quick Injection adds the SAME CSS and JavaScript to EVERY page your app loads - no conditions, no per-site rules.

Think of it as a global style sheet and a global startup script that always runs, no matter which page the user is on.

✅ Perfect for:

- Branding tweaks (colors, fonts, logo)
- Hiding global elements (header, footer, cookie banner)
- Small layout or font-size fixes for all pages
- Adding a global floating button (WhatsApp, chat, back-to-top)

❌ NOT designed for:

- Running code only on specific URLs → use Smart User Scripts instead
- Complex automations with timing → use Smart User Scripts

### 2. Where to Find It in the Generator

Step 4 (Permissions) → scroll down → 🎨 CSS / JS Quick Injection card.

Two text boxes:

- 🎨 Custom CSS  - paste raw CSS rules
- ⚡ Custom JavaScript  - paste raw JS (no wrapping needed)

Both are optional. Leave empty to skip.

### 3. Example 1: Hide Cookie Banner & Header

Globally remove a sticky header and cookie consent popup on every page:

```
/* ── Hide header & nav ── */
header, nav, .navbar, #top-bar, .site-header {
  display: none !important;
}

/* ── Remove cookie/GDPR banners ── */
.cookie-banner, #cookie-notice, .gdpr-popup,
[id*="cookie"], [class*="cookie"] {
  display: none !important;
}
```

### 4. Example 2: Full Dark Mode (CSS only)

Turn any website dark with a single CSS filter - images stay natural:

```
/* ── Dark Mode via CSS filter ── */
html {
  filter: invert(1) hue-rotate(180deg) !important;
}
/* Keep images & media in original colors */
img, video, canvas, svg, picture {
  filter: invert(1) hue-rotate(180deg) !important;
}
```

### 5. Example 3: Scale / Zoom Fix

Website looks tiny or too large on mobile? Fix the zoom level:

```
/* 85% scale — adjust to your needs */
body {
  zoom: 0.85;
}

/* Force readable font size */
body, p, li, td {
  font-size: 15px !important;
  line-height: 1.65 !important;
}
```

### 6. Example 4: Floating WhatsApp Button (JS)

Adds a floating WhatsApp contact button on every page (replace the phone number):

```
// Floating WhatsApp button
(function() {
  if (document.getElementById('__wa_fab__')) return;
  var btn = document.createElement('a');
  btn.id = '__wa_fab__';
  btn.href = 'https://wa.me/1234567890?text=Hello';
  btn.style.cssText = [
    'position:fixed','bottom:24px','right:20px',
    'width:56px','height:56px','border-radius:50%',
    'background:#25D366','color:#fff','font-size:26px',
    'display:flex','align-items:center','justify-content:center',
    'text-decoration:none','z-index:999999',
    'box-shadow:0 4px 12px rgba(0,0,0,.35)'
  ].join(';');
  btn.textContent = '💬';
  document.body.appendChild(btn);
})();
```

### 7. Example 5: Auto-Accept Cookies (JS)

Automatically click 'Accept' on cookie consent dialogs:

```
// Auto-accept cookie banners
(function() {
  var selectors = [
    '.accept-cookies','#accept-btn','#cookie-accept',
    'button[id*="accept"]','button[class*="accept"]',
    '[aria-label*="Accept"]'
  ];
  selectors.forEach(function(sel) {
    var el = document.querySelector(sel);
    if (el) el.click();
  });
})();
```

### 8. How It Works Internally

- CSS is inserted as a <style id=\'__userscript_css__\'> tag into the page <head> after load.
- JS is inserted as a <script id=\'__userscript_js__\'> tag after load.
- Both run on EVERY page after onPageFinished - including back-navigation.
- Double-injection is blocked by checking the element ID first.
- Works in offline ZIP apps too.

⚠️ Limitation: Runs AFTER page load. Early-executing scripts on the page may already have run. For before-load injection use Smart User Scripts (document-start).


---

# Smart User Scripts

> Run a script on matching pages only - the userscript model, inside your app.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/smart-user-scripts

Per-Site Scripts with URL Matching & Timing (like Greasemonkey)

### 1. What Are Smart User Scripts?

Smart User Scripts are individual named scripts - each with its own:  
🌐 URL match patterns  (which pages to run on)  
⏱ Run-at timing  (before, during or after load)  
✅ Enable/Disable toggle

They work like Greasemonkey or Tampermonkey in desktop browsers - but built right into your app.

✅ Perfect for:

- Auto-login ONLY on the /login page
- Hide ads ONLY on article pages (https://news.com/article/*)
- Watch DOM changes with MutationObserver
- Inject before page renders (document-start) to avoid flash

Key difference from Quick Injection:  
Quick Injection = same CSS/JS on ALL pages  
Smart User Scripts = per-script, per-URL, per-timing control

### 2. Where to Find It

Step 4 (Permissions) → scroll down → 🤖 Smart User Scripts card.

Tap '+ Add' to create a new script. Each script has:

- Name - shown in the manager list
- URL Match Patterns - one per line (supports * wildcard)
- Run At - document-end / document-start / document-idle
- Code - your JavaScript
- Enabled toggle

Tap any row to edit or delete a script.

### 3. URL Match Pattern Examples

Patterns control which pages the script runs on. Use * as a wildcard:

```
# Run on every page of every site
*://*/*

# Run only on example.com (any path)
https://example.com/*

# Run on ALL pages of ANY .com domain
https://*.com/*

# Run only on the /login path
https://example.com/login
https://example.com/login/*

# Run on news article pages
https://news.example.com/article/*
```

### 4. Run-At Timing Explained

- document-end (default)

Runs AFTER the page finishes loading. Safe, most compatible. Use for hiding elements, adding buttons, tracking.

- document-start ⚡ (advanced)

Runs BEFORE the page renders. Injects script into the raw HTML via shouldInterceptRequest. Removes CSP headers. Use for dark-mode CSS or forcing viewport before layout paint.

- document-idle ⏱

Runs 1.5 seconds after page load. Good for catching late-loading AJAX content or modals that appear after a delay.

### 5. Example 1: Auto-Login on /login Only

Match: https://myapp.com/login  
Run-at: document-end

```
// Auto-fill login form
(function() {
  var email = document.querySelector('input[type=email], input[name=email]');
  var pass  = document.querySelector('input[type=password]');
  if (email) email.value = 'user@example.com';
  if (pass)  pass.value  = 'mypassword';
  // Uncomment to auto-submit:
  // var form = document.querySelector('form');
  // if (form) form.submit();
})();
```

### 6. Example 2: Hide Paywalls on Article Pages

Match: https://news.site.com/article/*  
Run-at: document-end

```
// Hide paywall overlay and restore scroll
(function() {
  var overlay = document.querySelector('.paywall-overlay, .metered-content, #paywall');
  if (overlay) overlay.remove();
  document.body.style.overflow = 'auto';
  document.documentElement.style.overflow = 'auto';
})();
```

### 7. Example 3: Watch Dynamic Content (MutationObserver)

Match: *://*/*  
Run-at: document-end  
For elements that appear AFTER page load (lazy-loaded modals, ads):

```
// Remove any modal/popup that appears dynamically
(function() {
  var sel = '.modal, .popup, .overlay, [class*="modal"], [class*="popup"]';
  // Remove existing ones first
  document.querySelectorAll(sel).forEach(function(el) { el.remove(); });
  // Watch for new ones
  var obs = new MutationObserver(function() {
    document.querySelectorAll(sel).forEach(function(el) { el.remove(); });
  });
  obs.observe(document.body, { childList: true, subtree: true });
  // Stop watching after 30 s to save battery
  setTimeout(function() { obs.disconnect(); }, 30000);
})();
```

### 8. Example 4: Force Dark Mode Before Render (document-start)

Match: *://*/*  
Run-at: document-start  
Injects CSS before the page paints - no white flash:

```
// Inject dark theme before page renders
(function() {
  var s = document.createElement('style');
  s.id = '__force_dark__';
  s.textContent = [
    'html { filter: invert(1) hue-rotate(180deg) !important; }',
    'img,video,canvas,svg { filter: invert(1) hue-rotate(180deg) !important; }'
  ].join('\
');
  (document.head || document.documentElement).appendChild(s);
})();
```

### 9. Example 5: Custom Analytics / Event Tracking

Match: https://myshop.com/*  
Run-at: document-idle  
Send custom events after the page fully settles:

```
// Track page views + button clicks
(function() {
  // Page view
  console.log('[Analytics] Page: ' + location.href);

  // Track all CTA button clicks
  document.querySelectorAll('button, .btn, a[href]').forEach(function(el) {
    el.addEventListener('click', function() {
      console.log('[Analytics] Clicked: ' + (el.textContent || el.href));
      // Replace with your own tracker call, e.g. gtag('event', ...)
    });
  });
})();
```

### 10. Security & Limitations

⚡ document-start removes Content-Security-Policy headers for the matched page. Only use on sites you own or explicitly trust.

🔒 Same-Origin Policy: JS cannot access cross-origin iframes (PayPal, Stripe, Google login). This is enforced by the browser engine and cannot be bypassed.

📵 HTTPS Only: APIs like geolocation or camera in injected scripts require HTTPS.

✅ Guard against double-run: each script is guarded by a window flag so it runs only once per page.

✅ Works offline: Smart User Scripts also run in ZIP-bundled offline apps.


---

# Custom Side Menu Links

> Add your own items to the drawer, each opening inside the app.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/side-menu-links

Add Unlimited In-App Menu Items with Custom Names

### 1. What Are Custom Side Menu Links?

You can add unlimited links in Step 5 and define each menu name yourself. Every custom menu link opens inside the generated app (WebView), not the external browser.

### 2. How To Add Links In Generator

Go to Step 5 > Side Menu > Custom Menu Links (Unlimited).

Tap “+ Add Link”, then fill the row:

- Icon - tap the round bubble and pick an emoji
- Menu name - the label shown in the drawer, e.g. Store
- Link - /shop or https://example.com/deals

Leave the icon alone and the generator picks one from the name (Store → 🛒, Contact Us → ✉️). The bubble always shows the exact icon your app will render, so pick one yourself for names it cannot read - including names not written in English.

### 3. URL Mode Apps (Online Websites)

Use full links (https://...) or relative paths (/pricing, /contact).

All custom links are forced to open inside the app WebView.

### 4. Offline ZIP & Framework Apps

For offline/framework bundles (React/Vite/Next static export), use route-style paths like /dashboard or /#/profile.

The app auto-resolves these to the local WebViewAssetLoader origin:  
https://appassets.androidplatform.net/assets/www/...

### 5. Document Mode Apps

For document mode, custom paths are resolved to:  
https://appassets.androidplatform.net/assets/documents/...

This lets you add quick menu entries for bundled local files.

### 6. Best Practices

- Keep labels short (1-2 words)
- Use clear icons for faster navigation
- Prefer absolute https:// links for external pages
- For SPAs, use router paths that your app already supports


---

# Remote Update

> Push new app content to installed copies without a Play release.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/remote-update

Change your published apps without rebuilding

### 1. What it does

Change ads, links, menu text and announcements in apps people already installed - no rebuild, no new APK, no Play review. Users see the change the next time they open the app.

### 2. Connect Supabase once

Remote updates live in your own free Supabase project, so you stay in control of your data. Open the Remote Update screen (side menu) and tap Connect Supabase - one time, then every app you build can use it.

### 3. Edit → Publish → live on next open

Pick the app, edit what you want, tap Publish. That's the whole loop.

### 4. Who gets it

Remote Update publishing is included with every paid plan - Pro ($5/mo), Standard or Max - for unlimited apps. On Free you can explore the whole panel; publishing is the part that needs a plan.


---

# Publish to Web

> Put the same build online as a website, on a URL you can share.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/publish-to-web

Free subdomain instantly, custom domain when you're ready

### 1. One project - app AND website

Every app you build can also be published to the web. Same code, same design: you get an installable APK for the Play Store and a live URL to share.

### 2. Free subdomain, instantly

Publishing gives your app a free web address right away - nothing to configure, hosting included.

### 3. Custom domain

Want yourapp.com? Connect a domain you own from the publish screen - the guided flow shows the exact DNS record to add and detects your provider. Custom domains are paid with Mints, no separate purchase.


---

# Promotional Tools

> In-app banners, rating prompts and update nudges you control.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/promotional-tools

App Promo Maker, Mockups & Banners

### 1. App Promo Maker

Create stunning promotional videos for your app with phone mockups, text overlays, effects, and background music.

🎬 Features:

- 10 music styles (Upbeat, Chill, Corporate, Epic, etc.)
- 11 visual effects (Particles, Snow, Confetti, etc.)
- Phone frame customization
- Text overlays with animations
- Multiple aspect ratios (9:16, 1:1, 16:9)

```
📁 Save Location:
Movies/Web2APK Promo/

File format: MP4 video
Resolution: Up to 1080x1920
```

### 2. Phone Mockup Generator

Place your app screenshots inside realistic phone device frames. Perfect for Play Store listings and marketing materials.

📱 Features:

- Multiple phone frame styles
- Custom frame colors
- Background gradients
- Multiple device angles
- High resolution export

```
📁 Save Location:
Pictures/Web2APK Mockups/

File format: PNG image
Transparent background option available
```

### 3. Feature Banner Creator

Create Play Store feature graphics (1024×500) with your app icon, title, and custom background.

🖼️ Features:

- Play Store compliant size (1024×500)
- App icon integration
- Custom text and taglines
- Gradient backgrounds
- Export ready for Play Console

```
📁 Save Location:
Pictures/Web2APK Banners/

File format: PNG image
Size: 1024×500 pixels (Play Store requirement)
```

### 4. File Access & Sharing

All exported files are saved to your device's public folders and can be easily accessed:

📂 Using File Manager:

- Open your device's file manager
- Navigate to the respective folder
- Find files named with timestamp

📤 Sharing:

- Tap 'Share' on the file to send via email, social media, etc.
- Files can be directly uploaded to Play Console

```
Quick Access Paths:

📹 Videos: Movies/Web2APK Promo/
📱 Mockups: Pictures/Web2APK Mockups/
🖼️ Banners: Pictures/Web2APK Banners/
```

### 5. Tips for Best Results

✅ Screenshots: Use high-quality screenshots (at least 1080p)

✅ Video Length: Keep promo videos between 15-30 seconds

✅ Music: Choose music style that matches your app's theme

✅ Text: Keep text concise and readable

✅ Mockups: Use consistent style across all marketing materials

💡 Pro Tip: Create multiple variations and A/B test which performs better on Play Store


---

# Smart Abandoned Cart Links

> Bring a shopper back to the exact cart they left, from a notification.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/abandoned-cart-links

Re-Engage Users with Push → Deep Link

### 1. What are Abandoned Cart Deep Links?

When a user adds items to their cart but doesn't complete the purchase, you can send a push notification that takes them back to their exact cart page.

This is one of the most effective re-engagement strategies:

- 📈 Recover 10-30% of abandoned carts
- 💰 Direct revenue recovery
- 🎯 Highly targeted notifications
- ⏰ Time-sensitive urgency

### 2. Prerequisites

To use Smart Abandoned Cart Links, you need:

1. ✅ OneSignal integration enabled in your app
2. ✅ A website with unique cart URLs (e.g., yoursite.com/cart?id=abc123)
3. ✅ A way to track abandoned carts on your server

If your website uses Shopify, WooCommerce, or similar - they often have abandoned cart tracking built-in.

### 3. Method 1: Simple URL Push (No Code)

The easiest method - just send a push with the cart URL. No JSON or coding needed!

```
OneSignal Dashboard Steps:

1. Go to Messages → New Push
2. Title: "You left something in your cart! 🛒"
3. Message: "Complete your order - items are
   selling fast!"
4. Launch URL: https://yoursite.com/cart?id=abc123
5. Send to: Specific user (by OneSignal Player ID)
   or a segment

That's it! User taps → app opens → cart page loads
```

### 4. Method 2: JSON Payload Push (Advanced)

For more control, send a JSON data payload. Your website JavaScript can read this data and take custom actions:

```
OneSignal API Call:

POST https://onesignal.com/api/v1/notifications
{
  "app_id": "YOUR_ONESIGNAL_APP_ID",
  "include_player_ids": ["PLAYER_ID"],
  "headings": {"en": "Your cart misses you! 🛒"},
  "contents": {
    "en": "Complete checkout & get 10% off"
  },
  "url": "https://yoursite.com/cart",
  "data": {
    "type": "abandoned_cart",
    "cart_id": "cart_abc123",
    "discount_code": "COMEBACK10",
    "expires": "2025-12-31"
  }
}
```

### 5. Handle JSON Data on Website

When the app opens from a notification with JSON data, you can read the URL parameters on your website:

```
// On your cart/checkout page:
const params = new URLSearchParams(
  window.location.search
);

// Auto-apply discount if present
const discount = params.get('discount_code');
if (discount) {
  applyDiscountCode(discount);
  showBanner('Welcome back! ' + discount +
    ' discount applied 🎉');
}

// Or handle via OneSignal web SDK:
// OneSignal.on('notificationDisplay',
//   function(event) {
//     console.log(event.data);
//   });
```

### 6. Automation with Webhooks

For fully automated abandoned cart recovery:

1. User abandons cart on your website
2. Your server detects no purchase after 1 hour
3. Server calls OneSignal API to send push
4. User taps notification → returns to cart

Most e-commerce platforms (Shopify, WooCommerce, Magento) have plugins that automate this entire flow with OneSignal.

[OneSignal Abandoned Cart Docs](https://documentation.onesignal.com/docs/abandoned-cart)

### 7. Best Practices

✅ Timing: Send first reminder 1 hour after abandonment

✅ Second chance: Send another at 24 hours with a discount

✅ Urgency: Use phrases like 'Items selling fast' or 'Limited stock'

✅ Personalize: Include the product name if possible

✅ Discount: 5-15% off is usually enough to convert

⚠️ Don't spam: Max 2-3 reminders per abandoned cart

⚠️ Respect opt-outs: Honor notification preferences

### 8. Tracking Success

Monitor your abandoned cart recovery rate:

📊 In OneSignal Dashboard:

- Check notification CTR (Click-Through Rate)
- Track 'Confirmed Deliveries' vs 'Clicks'

📊 On your website:

- Track conversions from notification-originated visits
- Compare cart completion rates before/after

💡 Pro Tip: A/B test different notification messages and timing to optimize your recovery rate.


---

# Document & PDF to APK

> Turn a PDF or a set of documents into an app with a reader built in.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/document-and-pdf-apps

Bundle Multiple PDFs into a Reader App

### 1. Prepare Your Documents

Gather all the PDF files you want to include in your app. Professional naming helps since these titles will be displayed in your app's 'My Library' menu.

### 2. Select Document Mode

In the Web2APK Generator (Step 1):

1. Select the 'PDF Library' radio button
2. Click the 'Choose PDF Files' button
3. In the file picker, long-press to select MULTIPLE PDF files at once
4. Confirm your selection

### 3. Customize Your App

Set your app name, primary color, and icon. These will define the look of your digital library.

### 4. App Features

✅ Built-in Library: Browses all bundled documents automatically.  
✅ Searchable: Users can search for document titles.  
✅ Professional PDF Reader: High-quality rendering with zoom support.  
✅ Completely Offline: No internet required to view documents.

### 5. Best Practices

- Optimize PDF size for smaller APKs.
- Use clear, descriptive filenames for better library organization.
- Limit total size below 100MB for best performance.


---

# Photo Story to APK

> A gallery or slideshow app built from a folder of images.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/photo-story-apps

Create Swipeable Image Gallery Apps

### 1. Prepare Your Images

Gather the images (JPG, PNG) you want to include in your gallery app. Make sure they are high quality.

### 2. Select 'Photo Story/Gallery' Mode

On the main screen of the WebToApk generator, select the '🖼️ Photo Story to APK' creation mode from the options.

### 3. Choose Your Images

Click the button to pick files and select all the images you prepared. You can select multiple files at once.

### 4. Set Scroll Direction

Choose whether you want the gallery to scroll horizontally (like a traditional photo viewer) or vertically (like a social feed).

### 5. Generate APK/AAB

Complete the rest of the app details (name, icon, etc.) and generate your app. The images will be bundled directly into your app for offline viewing.


---

# Audio to APK

> An album, a podcast or a sound library as its own app.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/audio-apps

Bundle Audio Tracks into a Playlist App

### 1. Prepare Your Audio Files

Collect the audio files (MP3, WAV, M4A, etc.) you want to include in your playlist app.

### 2. Select 'Audio to APK' Mode

On the WebToApk generator's main screen, choose the '🎵 Audio to APK' conversion option.

### 3. Import Audio Tracks

Click the pick files button and navigate to select your audio files. Remember you can select multiple tracks to create a playlist.

### 4. Configure Playback Options

Enable 'AutoPlay' if you want music to start immediately when the app opens. Enable 'Resume Playback' to remember the last played track and position.

### 5. Build Your Music App

Configure your app's icon, theme colors, and name, then hit generate! Your new audio player app will bundle all selected tracks.


---

# Video to APK

> Ship video inside the APK, or stream it, with a real player.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/video-apps

Package Videos into a Swipeable Player App

### 1. Gather Your Videos

Prepare the video files (MP4, MKV, WebM) you want to showcase in your application.

### 2. Select 'Video to APK' Mode

On the main creation screen, select the '🎬 Video to APK' mode.

### 3. Add Video Clips

Use the file picker to select your video files. These videos will be integrated into the app for high-performance offline playback.

### 4. Configure Player Settings

Toggle options like AutoPlay (starts video immediately) and Resume Playback (remembers where the user left off in the video feed). Your videos will be presented in a sleek vertical-scrolling reel format.

### 5. Finalize and Generate

Fill in app details like the name and icon, then start the build process to package your videos into a standalone reel application.


---

# Multimedia Metadata (Audio/Video)

> Titles, artwork and track order for the media you bundled.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/audio-and-video-metadata

Organize Tracks & Clips with Titles & Categories

### 1. 🎬 Choose Audio or Video Mode

Select 'Audio Converter' or 'Video Converter' from the home screen to start building your media app.

### 2. 📂 Select Your Media Files

Click the selection button and pick all the audio tracks or video clips you want to include. You can select multiple files at once!

### 3. 🏷️ Open Metadata Editor

Once files are selected, a new button '🏷️ Edit Titles & Categories' will appear. Click it to customize your metadata.

### 4. ✍️ Add Titles & Group by Categories

Enter a professional 'Display Title' for each file. Use the 'Category' field to group related files (e.g., 'Rock', 'Yoga', 'Tutorials'). This will automatically create an organized playlist in your final app!

### 5. 📜 In-App Playlist navigation

In the generated app, users can tap the '📜 Playlist' (Audio) or '📁 Topics' (Video) icons to quickly jump between categories.


---

# Fix Play Store Upload Key Error

> What to do when Play rejects an upload because the signing key does not match.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/fix-play-upload-key-error

If Play Console says your AAB is signed with the wrong key - recover in 6 steps

### 1. What this fixes

If Play Console rejects your AAB with an error like "Your Android App Bundle is signed with the wrong key", you're hitting this. Older AppMint versions signed each build with a different random key. New AppMint builds use a stable per-package key - but Play Console still expects the old key it has on file. You need to RESET the upload key once. Your live users are NOT affected: Google's app signing key (the one on their devices) never changed. This only updates what Google accepts from you as the developer.

### 2. Rebuild with the latest AppMint

Build your app once with the current AppMint version. Along with the AAB, the build now produces three signing files in your Downloads folder:

- <appname>_signkey.p12         - the full signing key (KEEP PRIVATE)
- <appname>_upload_cert.pem    - the certificate only (this is what you upload to Google)
- <appname>_signkey_info.txt   - readme with credentials

You only need upload_cert.pem for the reset. Hold onto the .p12 - you'll need it for future updates.

### 3. Open Play Console → App integrity

On a computer:

1. Go to Play Console and open the affected app.
2. Left menu: Test and release → App integrity.
3. Open the App signing tab.
4. Scroll to Upload key certificate.
5. Click Request upload key reset.

[Open Play Console](https://play.google.com/console)

### 4. Fill in the reset form

On the reset form:

- Reason: choose "I have lost or compromised my existing upload key."
- Upload the upload_cert.pem file from your Downloads folder.
- Submit.

That's it on your side. Google reviews within 24-48 hours (often faster). You'll get an email when they approve.

### 5. Upload the new AAB after approval

Once Google approves, the new upload key is active. Upload the AAB you built in step 2 (or any newer AAB built with the same AppMint version). Future updates with the SAME package name will all match automatically - you'll never have to do this reset again.

### 6. What end-users see

Nothing. Their installed app is signed with Google's app signing key, which is unchanged. After the reset, your update installs over the existing app like any normal Play Store update - no reinstall, no data loss, no warning.

### 7. If something doesn't work

- "upload_cert.pem not found in Downloads" - make sure you built the app with the latest AppMint AFTER this guide was added. Older builds only produced .p12; you'd have to derive the .pem yourself.

- "Reset request denied" - Google denies a few. Common cause: a different cert was uploaded than the one matching your new builds. Rebuild and download a fresh upload_cert.pem before requesting again.

- "My app was published as an APK, not an AAB" - this guide doesn't apply: APK-only apps that opted OUT of Play App Signing can't recover. The only path is a new app under a new package name.

- Google Sign-In, Facebook Login, or Firebase Auth stops working after reset - those use the APP SIGNING certificate fingerprint (SHA-1/SHA-256), which is Google's and DID NOT CHANGE. If they broke, the problem is elsewhere - not the reset.


---

# Play Store App Ownership Verification

> Prove you own the website your app wraps, which Play now asks for.

- **Applies to:** AppMint
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/play-store-ownership-verification

Prove APK Ownership to Google Without a PC

### 1. What Is Play Store App Ownership Verification?

Google Play has a challenge-response system that lets you prove you are the legitimate owner of an APK without needing Android Studio or a PC.

When does this happen?

- A user or business partner asks you to prove the APK they have is yours
- Google Play or a distributor sends you a verification token
- You need to inject that token into the APK and re-sign it

The token is a small text file (adi-registration.properties) placed inside the APK's assets folder. Google then downloads and installs the APK to confirm the token matches their records.

### 2. Open the Play Store Verification Tool

The verification tool is built directly into the WebToApk Generator app:

1. Open the generator
2. Tap the ☰ menu (top-left)
3. Tap '🛡️ Play Store Verification'

No PC, Android Studio, or command-line tools needed.

### 3. Step 1 - Pick Your APK File

Tap 'Pick APK File' and select the generated APK you want to verify.

✅ This should be the same APK you submitted to (or generated for) Google Play.

⚠️ The APK must have been generated by this app so the signing key is available. APKs signed with external keys cannot be re-signed here.

```
APK file location after generation:
Downloads/WebToApk/<AppName>/

Example:
Downloads/WebToApk/MyShopApp/MyShopApp.apk
```

### 4. Step 2 - Paste Your Verification Token

Google (or whoever requested verification) will send you a token string. It typically looks like a random alphanumeric code.

Paste it into the 'Verification Token' field exactly as received - do not add spaces or line breaks.

```
Example token format:
adi-registration.properties content:

token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

(Paste ONLY the token value, not the key name)
```

### 5. Step 3 - Generate & Sign Verified APK

Tap 'Generate Verified APK'. The tool will:

1. Read your original APK
2. Remove any old META-INF verification files
3. Inject assets/adi-registration.properties with your token
4. Re-sign the APK with your app's original signing key
5. Save the verified APK to your Downloads folder

The entire process runs on-device in seconds.

```
Output file:
Downloads/WebToApk/Verified/<AppName>_verified.apk
```

### 6. Step 4 - Share the Verified APK

After generation, tap 'Share APK' to send it directly to:

- Email (attach to your reply to Google)
- Google Drive / OneDrive
- WhatsApp / Telegram
- Any other sharing method

Send the verified APK back to whoever requested the verification. Google's system will automatically download it, extract the token, and complete the ownership check.

### 7. What Gets Injected Into the APK?

The tool injects a single properties file at the path required by Google:

```
File path inside APK:
assets/adi-registration.properties

File content:
<your token exactly as provided>
```

### 8. Signing Key Details

The verified APK is re-signed using the same deterministic key that was used when the original APK was generated. The key is derived from your app's package name, so:

✅ The verified APK has the exact same signature as your submitted APK  
✅ Google can confirm the signer matches their records  
✅ No keystore file needed - the key is computed automatically

⚠️ Important: This only works for APKs generated by this app. It cannot re-sign APKs from other tools.

### 9. Frequently Asked Questions

Q: Will this break my app or change its behavior?  
A: No. The only change is the addition of the properties file in assets. All other functionality stays identical.

Q: Do I need to update my Play Store listing?  
A: No. The verified APK is used only for the ownership challenge, not submitted as a new release.

Q: Can I verify multiple APKs with different tokens?  
A: Yes - run the tool once per APK/token combination.

Q: My token expired. What do I do?  
A: Contact Google to request a new token, then repeat this process with the fresh token.


---

# JavaScript bridge API

> Every native method a page inside an app built with AppMint can call: 152 methods.

- **Applies to:** AppMint
- **Source:** extracted from the app runtime (`WebViewActivity.kt`); this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/api

The bridge exists only inside a generated app: in a browser `window.WebToApk` is undefined, so guard every call. Anything asynchronous answers with a DOM event (`appmint:*`) rather than a return value; each description names the event it fires.

## Purchases and entitlements

Selling from your own page, and asking what this buyer already owns. See the in-app purchases guide for the code around these.

### `isPremium`

```js
window.WebToApk.isPremium(): Boolean
```

True when the user owns "Remove Ads" (Play Billing entitlement, auto-restored on every launch). Matches the reason 'ad_free' in 'appmint:ad-unavailable'.

### `startRemoveAdsPurchase`

```js
window.WebToApk.startRemoveAdsPurchase()
```

Launch the Google Play "Remove Ads" purchase flow from the page (user-initiated, e.g. the app's own "Remove ads" button). Without this the ONLY entry point was the native side-menu item - unreachable in apps built without the side menu. Outcome reaches the page via 'appmint:premium' {premium:true}; already-owned re-notifies immediately; flow errors surface as a native toast.

### `isOwned`

```js
window.WebToApk.isOwned(productId: String): Boolean
```

Instant on-device ownership check (one-time product owned OR sub active).

### `getOwnedProducts`

```js
window.WebToApk.getOwnedProducts(): String
```

JSON array of every owned product ID - for gating whole screens at startup.

### `getProducts`

```js
window.WebToApk.getProducts(requestId: String, productIdsJson: String)
```

Asks Play for live details of the given product IDs (JSON array of strings). Result arrives as 'appmint:products' {requestId, products:[{productId, type, title, description, price, currency, period?, owned}]}. IDs Play doesn't know are absent from the result - the page hides those items.

### `purchase`

```js
window.WebToApk.purchase(productId: String)
```

Opens Google's purchase sheet for [productId] (one-time product or subscription - resolved automatically). Grant ONLY on 'appmint:purchase' {productId, owned:true}; failures fire 'appmint:purchase-failed' {reason}. Already-owned re-fires the purchase event so the page can idempotently unlock.

## Ads

Showing an interstitial or a rewarded ad on your own cue, and telling the shell when a navigation starts and settles so it does not interrupt one.

### `adsConfig`

```js
window.WebToApk.adsConfig(): String
```

`{control, formats:{banner, mrec, interstitial, rewarded, rewarded_interstitial, app_open}}` - the ad formats this build can serve.

### `adsIsReady`

```js
window.WebToApk.adsIsReady(type: String): Boolean
```

True when a full-screen [type] is loaded and can be shown right now.

### `adsLoad`

```js
window.WebToApk.adsLoad(type: String, callbackId: String)
```

Loads a full-screen [type]; the promise for [callbackId] resolves with the outcome.

### `adsShow`

```js
window.WebToApk.adsShow(type: String, callbackId: String, userGesture: Boolean)
```

Shows a loaded full-screen [type]; resolves when it closes, with earned/reward for rewarded formats. [userGesture] is the shim's `navigator.userActivation` reading - a rewarded format asked for without one gets AdMob's intro screen first (see DeveloperAds.offerRewarded).

### `adsSlotAttach`

```js
window.WebToApk.adsSlotAttach(slotId: String, type: String, widthCss: Int, callbackId: String)
```

Creates a banner/mrec overlay for the page's slot [slotId], sized to [widthCss]; resolves with the ad's size once loaded.

### `adsSlotRect`

```js
window.WebToApk.adsSlotRect(slotId: String, x: Float, y: Float, w: Float, h: Float, visible: Boolean)
```

Internal: the slot element's current viewport rectangle (CSS px) - moves the overlay.

### `adsSlotDetach`

```js
window.WebToApk.adsSlotDetach(slotId: String)
```

Removes a banner overlay.

### `adsAppOpenEnable`

```js
window.WebToApk.adsAppOpenEnable(enabled: Boolean)
```

Lets the page pause/resume the app-open ad on return from another app (on by default when a unit is set).

### `isRewardedAdReady`

```js
window.WebToApk.isRewardedAdReady(): Boolean
```

True when a rewarded ad is loaded and can be shown right now. Let the page enable/disable its "Watch ad" button off this (poll or call before showing).

### `isInterstitialAdReady`

```js
window.WebToApk.isInterstitialAdReady(): Boolean
```

True when an interstitial is loaded AND past its cooldown (matches exactly what showInterstitialAd() will accept - no "ready" that then refuses to show).

### `showRewardedAd`

```js
window.WebToApk.showRewardedAd()
```

Show a rewarded ad NOW (user-initiated - the only policy-compliant way to show rewarded). Pair it with trigger mode "On Demand" in the wizard to get rewarded ads with NO automatic app-open/navigation ads at all. The reward is delivered back to the page via deliverRewardToPage(): window.addEventListener('appmint:reward', e => { /* e.detail = {type,amount} */ }) When the ad closes, 'appmint:ad-closed' fires with {adType:'rewarded', earned} - earned is false if the user backed out early, so grant nothing in that case. Not showable right now → skipped + 'appmint:ad-unavailable' fired with the reason.

### `showInterstitialAd`

```js
window.WebToApk.showInterstitialAd()
```

Show an interstitial NOW (e.g. between levels / on a deliberate action). Not showable right now → skipped + 'appmint:ad-unavailable' with the reason.

### `notifyUserAction`

```js
window.WebToApk.notifyUserAction()
```

Internal (called by the injected tap counter, not creator code): one meaningful user interaction happened in the page. Counts toward the "interstitial every N actions" cadence ONLY while no URL-based navigation has ever been observed - single-HTML apps that switch screens via DOM show/hide never change the URL, so without this their navigation counter stayed at 0 forever and configured ads never showed (TicTrek complaint class, 2026-07-26). URL/SPA apps are unaffected: their first real navigation permanently switches counting back to URL signals.

### `navStarted`

```js
window.WebToApk.navStarted()
```

Internal (called by the injected navigation observer, not creator code): the page is changing view without changing its URL. This is the ONLY signal for it - a single-HTML app that swaps DOM nodes fires no onPageStarted, no onPageFinished, no doUpdateVisitedHistory, and leaves onProgressChanged pinned at 100, so from native the tap and the new screen are completely invisible. Ignored while a real document load is running: that load owns the bar, and its own callbacks decide when it ends.

### `navSettled`

```js
window.WebToApk.navSettled()
```

Companion to [navStarted]: the swapped-in view has painted.

## Notifications on the device

Posting and scheduling without a server, the POST_NOTIFICATIONS grant, exact alarms, and custom sounds.

### `showNotification`

```js
window.WebToApk.showNotification(title: String, body: String, icon: String, tag: String): Boolean
```

The ORIGINAL four-argument form, kept verbatim as an adapter so every app already in the wild and every guide snippet keeps working. It now forwards to the rich builder - which means the `icon` argument, silently discarded by the old implementation, finally does something.

### `notify`

```js
window.WebToApk.notify(optionsJson: String): Boolean
```

Rich notification. See NotificationBridge.show for the full option list: channel (urgent|default|quiet|ongoing), image, largeIcon, bigText, ongoing, actions, progress, sound, silent, group, color. Image fetching and decoding happen off the main thread, so a remote image can never block the page.

### `getNotificationPermission`

```js
window.WebToApk.getNotificationPermission(): String
```

The CURRENT notification permission, read live from the OS. The polyfill used to hardcode `Notification.permission = 'default'` on every page load, so the overwhelmingly common page pattern if (Notification.permission === 'granted') new Notification(...) never fired - not even for a user who had already granted it, and not on Android 12 and below where notifications need no runtime grant at all.

### `requestNotificationPermission`

```js
window.WebToApk.requestNotificationPermission(): String
```

Reading and requesting the POST_NOTIFICATIONS grant, and managing notifications the page already scheduled. Posting and scheduling are documented on their own methods.

_Described by its group, Notification permission, cancelling and listing, rather than on its own._

### `scheduleNotification`

```js
window.WebToApk.scheduleNotification(id: String, title: String, body: String, triggerAtMillis: String, repeat: String): Boolean
```

===== Tier-2: SCHEDULED local notifications (reminders) ===== Fire a notification at a future time even when the app is closed - backed by AlarmManager + persistence so it survives reboot. Dormant unless called. JS contract (all args strings; triggerAtMillis = epoch millis): window.WebToApk.scheduleNotification(id, title, body, triggerAtMillis, repeat) repeat ∈ "none" | "minutely" | "hourly" | "daily" | "weekly" window.WebToApk.cancelNotification(id) window.WebToApk.cancelAllNotifications() window.WebToApk.getScheduledNotifications()  -> JSON array string

### `cancelNotification`

```js
window.WebToApk.cancelNotification(id: String): Boolean
```

Reading and requesting the POST_NOTIFICATIONS grant, and managing notifications the page already scheduled. Posting and scheduling are documented on their own methods.

_Described by its group, Notification permission, cancelling and listing, rather than on its own._

### `cancelAllNotifications`

```js
window.WebToApk.cancelAllNotifications(): Boolean
```

Reading and requesting the POST_NOTIFICATIONS grant, and managing notifications the page already scheduled. Posting and scheduling are documented on their own methods.

_Described by its group, Notification permission, cancelling and listing, rather than on its own._

### `getScheduledNotifications`

```js
window.WebToApk.getScheduledNotifications(): String
```

Reading and requesting the POST_NOTIFICATIONS grant, and managing notifications the page already scheduled. Posting and scheduling are documented on their own methods.

_Described by its group, Notification permission, cancelling and listing, rather than on its own._

### `scheduleNotificationEx`

```js
window.WebToApk.scheduleNotificationEx(id: String, optionsJson: String): Boolean
```

The full form of [scheduleNotification]: everything `notify()` accepts, fired at a future time with the app closed. WebToApk.scheduleNotificationEx('dose-1', JSON.stringify({ at: Date.now() + 3600000,   // epoch millis (alias: triggerAt) repeat: 'daily',            // none|minutely|hourly|daily|weekly title: 'Time for your dose', body: 'Vitamin D - 1 tablet', sound: '/audio/chime.mp3',  // a file in YOUR bundle; 'silent' for none openApp: true               // open the app itself, over the lock screen })); A bundled sound is copied into place during this call, so a wrong file name is reported now (false) rather than turning into the default sound days later.

### `getAlarmPrecision`

```js
window.WebToApk.getAlarmPrecision(): String
```

"exact" - reminders fire on the minute. "inexact" - the user (or the OEM) turned exact alarms off for this app, so Doze may batch them by minutes. Ask [requestExactAlarms] to fix it. A page that must be on time should check this instead of assuming.

### `requestExactAlarms`

```js
window.WebToApk.requestExactAlarms(): Boolean
```

Opens the system screen where exact alarms are granted. Android 12+.

### `canOpenAppAtTime`

```js
window.WebToApk.canOpenAppAtTime(): String
```

Whether a scheduled notification may put the APP ITSELF on screen (`openApp`). "granted"  - a full-screen alert will show, over the lock screen. "denied"   - Android 14+ withheld it; call requestOpenAppPermission(). There is no third answer where the app silently launches itself in the background: Android has blocked background activity starts since Android 10, and a full-screen intent is the whole of what remains.

### `requestOpenAppPermission`

```js
window.WebToApk.requestOpenAppPermission(): Boolean
```

Opens the system screen where the full-screen alert is granted. Android 14+.

### `prepareNotificationSound`

```js
window.WebToApk.prepareNotificationSound(spec: String): Boolean
```

Copies a bundled audio file into place ahead of time and reports whether it is usable as a notification sound. Optional - `notify()` and `scheduleNotificationEx()` do it themselves - but it lets a settings screen verify a sound the moment the user picks it.

### `clearNotificationSounds`

```js
window.WebToApk.clearNotificationSounds(): Int
```

Drops the copied sound files. They are re-created on next use.

## The push inbox

Messages the creator sent from a dashboard, kept on the device so the page can show a history rather than only a tray pop-up.

### `getPushInbox`

```js
window.WebToApk.getPushInbox(): String
```

AppMint Push inbox (creator-sent messages, newest first, max 50): JSON array of {id, title, body, imageUrl, link, receivedAt, read}. Always the full current truth - an app that mounts late loses nothing by having missed the live `appmint:push` events.

### `markPushRead`

```js
window.WebToApk.markPushRead(id: String): Boolean
```

Marks one push message read; pass "" to mark every message read.

### `dismissPushMessage`

```js
window.WebToApk.dismissPushMessage(id: String): Boolean
```

Dismisses ONE message from the inbox - the per-row swipe-away an inbox screen needs (clearPushInbox is all-or-nothing). REVERSIBLE by design: the entry is hidden, not destroyed, so the UI can offer "Undo" for a few seconds after the swipe. Local only: the tray notification and the creator's history are untouched.

### `restorePushMessage`

```js
window.WebToApk.restorePushMessage(id: String): Boolean
```

Undo a dismiss: puts the message back in its place in the inbox.

### `clearPushInbox`

```js
window.WebToApk.clearPushInbox(): Boolean
```

Empties the push inbox (the tray and server history are untouched).

## Sign-in and passkeys

A real Google account chooser, native rather than a web redirect, and passkeys through Android’s Credential Manager - navigator.credentials works as in Chrome, or use AppMint.passkey with your server’s JSON options.

### `signInWithGoogle`

```js
window.WebToApk.signInWithGoogle(serverClientId: String, callbackId: String)
```

===== Native Google Sign-In via Credential Manager ===== Bypasses Google's Android WebView OAuth block (disallowed_useragent error) by running the sign-in flow in native Android and bridging just the resulting Google ID token back to JS, where the Firebase Web SDK consumes it via GoogleAuthProvider.credential(idToken) + signInWithCredential(...). JS contract: window.WebToApk.signInWithGoogle(serverClientId, callbackId) -> on completion, window.__webToApkAuth[callbackId](resultJsonString) is called resultJsonString = '{"ok":true,"idToken":"...","email":"...","displayName":"..."}' or '{"ok":false,"error":"<message>"}'

### `signOutGoogle`

```js
window.WebToApk.signOutGoogle(callbackId: String)
```

Clears the saved Credential Manager state so the next signInWithGoogle call shows the account picker again (rather than silently re-selecting the last account). Generated apps should call this on user-initiated sign-out, in addition to firebase.auth().signOut().

### `passkeyIsAvailable`

```js
window.WebToApk.passkeyIsAvailable(): Boolean
```

True on Android 9+ with Google Play services - the phones that can hold a passkey.

### `passkeyOrigin`

```js
window.WebToApk.passkeyOrigin(): String
```

The origin a passkey server sees from this app: `android:apk-key-hash:<base64url SHA-256>`.

### `passkeyAssetLinks`

```js
window.WebToApk.passkeyAssetLinks(): String
```

The assetlinks.json array (as text) that authorises this installed app for your domain.

## QR and barcode scanner

Google’s scanner screen from one promise, AppMint.scanCode() - no camera permission, and the parsed URL, Wi-Fi, phone or contact for common QR codes.

### `scanCode`

```js
window.WebToApk.scanCode(optionsJson: String, callbackId: String)
```

Opens Google's code scanner; [optionsJson] `{formats?, autoZoom?, manualInput?}`. Resolves the AppMint.scanCode promise [callbackId].

## Biometrics and the keystore

Fingerprint and face unlock, and hardware-backed keys the page can encrypt with but never read.

### `generateKey`

```js
window.WebToApk.generateKey(alias: String, optionsJson: String): String
```

Creates (or replaces) an AES-256-GCM key called [alias]. @param optionsJson `{"requireAuth":bool, "authValiditySeconds":int, "strongBox":bool}`. `requireAuth` binds the key to the device lock; `strongBox` fails outright on devices without a secure element rather than handing back a weaker key than was asked for. @return JSON `{ok, alias, hardwareBacked, error}`.

### `hasKey`

```js
window.WebToApk.hasKey(alias: String): String
```

True when a key called [alias] exists in this app's keystore.

### `listKeys`

```js
window.WebToApk.listKeys(): String
```

JSON array of every key alias this page has created.

### `encryptWithKey`

```js
window.WebToApk.encryptWithKey(alias: String, base64Plaintext: String): String
```

Encrypts base64 [base64Plaintext] with [alias]. Each call generates its own IV, so a large file is encrypted chunk by chunk - chunks are independent and may be decrypted in any order. @return JSON `{ok, base64, error}` where `base64` is `IV || ciphertext || tag`.

### `decryptWithKey`

```js
window.WebToApk.decryptWithKey(alias: String, base64Payload: String): String
```

Reverses [encryptWithKey]. Fails with `error:"no-such-key"` once the key has been deleted - the payload is then unrecoverable by design. @return JSON `{ok, base64, error}`.

### `deleteKey`

```js
window.WebToApk.deleteKey(alias: String): String
```

Destroys [alias] permanently. Everything encrypted with it becomes undecryptable - including by this app, and by anyone holding the device.

### `isKeyHardwareBacked`

```js
window.WebToApk.isKeyHardwareBacked(alias: String): String
```

True when [alias] lives in the TEE or a secure element rather than in software. Worth checking before promising a user that destroying a key is irreversible.

### `isKeystoreEnabled`

```js
window.WebToApk.isKeystoreEnabled(): String
```

Whether the creator enabled the keystore bridge for this app.

### `isBiometricAvailable`

```js
window.WebToApk.isBiometricAvailable(): String
```

WebToApk.isBiometricAvailable()            -> "available" | "no_hardware"                                                | "not_enrolled" | "unavailable"   WebToApk.authenticateBiometric(id, title, subtitle) Result is delivered to the same __webToApkAuth callback table the Google Sign-In bridge uses:   window.__webToApkAuth = window.__webToApkAuth || {};   window.__webToApkAuth['unlock'] = function (json) {       var r = JSON.parse(json);      // {ok:true} | {ok:false,error:"..."}       if (r.ok) showApp();   };   WebToApk.authenticateBiometric('unlock', 'Unlock', 'Use your fingerprint');

_Described by its group, Fingerprint / biometric bridge, rather than on its own._

### `authenticateBiometric`

```js
window.WebToApk.authenticateBiometric(callbackId: String, title: String, subtitle: String)
```

WebToApk.isBiometricAvailable()            -> "available" | "no_hardware"                                                | "not_enrolled" | "unavailable"   WebToApk.authenticateBiometric(id, title, subtitle) Result is delivered to the same __webToApkAuth callback table the Google Sign-In bridge uses:   window.__webToApkAuth = window.__webToApkAuth || {};   window.__webToApkAuth['unlock'] = function (json) {       var r = JSON.parse(json);      // {ok:true} | {ok:false,error:"..."}       if (r.ok) showApp();   };   WebToApk.authenticateBiometric('unlock', 'Unlock', 'Use your fingerprint');

_Described by its group, Fingerprint / biometric bridge, rather than on its own._

### `authenticateBiometricEx`

```js
window.WebToApk.authenticateBiometricEx(callbackId: String, optionsJson: String)
```

The full form. [optionsJson] accepts: title, subtitle, description, negativeButtonText, allowDeviceCredential (PIN/pattern/password fallback), strong (require BIOMETRIC_STRONG - use for anything payment-shaped). Errors are distinct codes, not one boolean: no_hardware | none_enrolled | hw_unavailable | lockout | lockout_permanent | user_cancel | permission_missing.

## Files: a folder the user granted

A directory chosen once, readable and writable afterwards, with permission that survives reboots.

### `requestFolderAccess`

```js
window.WebToApk.requestFolderAccess(requestId: String)
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `hasFolderAccess`

```js
window.WebToApk.hasFolderAccess(): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `isFolderAccessEnabled`

```js
window.WebToApk.isFolderAccessEnabled(): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `getFolderAccessUri`

```js
window.WebToApk.getFolderAccessUri(): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `clearFolderAccess`

```js
window.WebToApk.clearFolderAccess()
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `listFolderEntries`

```js
window.WebToApk.listFolderEntries(relativePath: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `readTextFile`

```js
window.WebToApk.readTextFile(relativePath: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `writeTextFile`

```js
window.WebToApk.writeTextFile(relativePath: String, content: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `mkdir`

```js
window.WebToApk.mkdir(relativePath: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `renameEntry`

```js
window.WebToApk.renameEntry(relativePath: String, newName: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

### `deleteEntry`

```js
window.WebToApk.deleteEntry(relativePath: String, recursive: String): String
```

Play-safe folder access using ACTION_OPEN_DOCUMENT_TREE with persistable URI permissions.  JavaScript usage:   window.WebToApk.requestFolderAccess('myRequestId')   window.WebToApk.hasFolderAccess()                // "true" / "false"   window.WebToApk.getFolderAccessUri()             // "content://..." or ""   window.WebToApk.clearFolderAccess()              // releases persisted access  Callback from Android → JS:   window.WebToApkOnFolderAccessResult(success, folderUri, requestId)

_Described by its group, Native Folder Access (SAF) Bridge, rather than on its own._

## Files: one file at a time

The system picker and chunked binary read/write, for files too large to hold in a string.

### `pickFile`

```js
window.WebToApk.pickFile(requestId: String, mimeFilter: String)
```

Opens the system single-file picker (ACTION_OPEN_DOCUMENT). Unlike [requestFolderAccess] this grants access to exactly one file, which is what an editor or a shredder should ask for; the read/write grant is persisted so the URI keeps working after the process is killed. @param mimeFilter e.g. "image/\*", "application/pdf", or "" for any file. (The star is backslash-escaped only because Kotlin block comments nest.)

### `readFileBase64`

```js
window.WebToApk.readFileBase64(pathOrUri: String, offset: Long, length: Long): String
```

Reads up to [length] raw bytes starting at [offset] and returns them base64. @param pathOrUri a `content://` URI from [pickFile], or a path relative to the folder granted by [requestFolderAccess]. @param length bytes to read; clamped to 4 MB per call. 0 or negative means "as much as one call allows". @return JSON `{ok, base64, bytesRead, offset, size, eof, error}`. `eof` tells a chunking loop when to stop without having to compare against `size` itself.

### `writeFileBase64`

```js
window.WebToApk.writeFileBase64(pathOrUri: String, base64: String, offset: Long, mode: String): String
```

Writes raw bytes and confirms how many landed. @param mode `"patch"` writes at [offset] leaving the rest of the file intact (what a multi-pass overwrite needs), `"truncate"` replaces the file, `"append"` ignores [offset] and writes at the end. @return JSON `{ok, bytesWritten, offset, size, error}` - `size` is re-read from the file after an fsync, so a caller can verify the write for real rather than trust a boolean.

### `statFile`

```js
window.WebToApk.statFile(pathOrUri: String): String
```

File metadata without reading any of it. @return JSON `{ok, name, size, mime, lastModified, uri, isDirectory, canWrite}`.

### `releaseFileAccess`

```js
window.WebToApk.releaseFileAccess(uriString: String): String
```

Releases a persisted single-file grant taken by [pickFile]. Android caps how many URI grants an app may persist, so an app that picks many files should release the ones it is done with.

### `getMaxIoChunkSize`

```js
window.WebToApk.getMaxIoChunkSize(): Long
```

The per-call byte cap for [readFileBase64] / [writeFileBase64], for chunk maths.

## Files: opened with this app

Collecting what another app handed over through "Open with", in chunks the page pulls.

### `openedFilesPending`

```js
window.WebToApk.openedFilesPending(): String
```

Internal to AppMint.getOpenedFile() / getOpenedFiles() / releaseOpenedFile(). The page pulls, rather than being pushed at: a file opened on cold start is parked until it is asked for, so an SPA that mounts late still gets it. Each file's metadata carries `kind` (image | video | audio | document | data) and `url` - https://appassets.androidplatform.net/appmint-shared/<token>/<name>, served from the cache copy with byte ranges, so a shared video streams into <video src> and seeks. Data files and documents are also pulled in MAX_IO_CHUNK slices into a File; media and anything over 64 MB stay url-only (getFile() fetches on demand), so a 300 MB clip never sits in a JS array.

_Described by its group, Files shared to, or opened with, the app, rather than on its own._

### `openedFileChunk`

```js
window.WebToApk.openedFileChunk(token: String, offset: String, len: Int): String
```

Internal to AppMint.getOpenedFile() / getOpenedFiles() / releaseOpenedFile(). The page pulls, rather than being pushed at: a file opened on cold start is parked until it is asked for, so an SPA that mounts late still gets it. Each file's metadata carries `kind` (image | video | audio | document | data) and `url` - https://appassets.androidplatform.net/appmint-shared/<token>/<name>, served from the cache copy with byte ranges, so a shared video streams into <video src> and seeks. Data files and documents are also pulled in MAX_IO_CHUNK slices into a File; media and anything over 64 MB stay url-only (getFile() fetches on demand), so a 300 MB clip never sits in a JS array.

_Described by its group, Files shared to, or opened with, the app, rather than on its own._

### `openedFileCollected`

```js
window.WebToApk.openedFileCollected(token: String)
```

Internal to AppMint.getOpenedFile() / getOpenedFiles() / releaseOpenedFile(). The page pulls, rather than being pushed at: a file opened on cold start is parked until it is asked for, so an SPA that mounts late still gets it. Each file's metadata carries `kind` (image | video | audio | document | data) and `url` - https://appassets.androidplatform.net/appmint-shared/<token>/<name>, served from the cache copy with byte ranges, so a shared video streams into <video src> and seeks. Data files and documents are also pulled in MAX_IO_CHUNK slices into a File; media and anything over 64 MB stay url-only (getFile() fetches on demand), so a 300 MB clip never sits in a JS array.

_Described by its group, Files shared to, or opened with, the app, rather than on its own._

### `openedFileRelease`

```js
window.WebToApk.openedFileRelease(token: String)
```

Internal to AppMint.getOpenedFile() / getOpenedFiles() / releaseOpenedFile(). The page pulls, rather than being pushed at: a file opened on cold start is parked until it is asked for, so an SPA that mounts late still gets it. Each file's metadata carries `kind` (image | video | audio | document | data) and `url` - https://appassets.androidplatform.net/appmint-shared/<token>/<name>, served from the cache copy with byte ranges, so a shared video streams into <video src> and seeks. Data files and documents are also pulled in MAX_IO_CHUNK slices into a File; media and anything over 64 MB stay url-only (getFile() fetches on demand), so a 300 MB clip never sits in a JS array.

_Described by its group, Files shared to, or opened with, the app, rather than on its own._

### `openedFileMaxChunk`

```js
window.WebToApk.openedFileMaxChunk(): Int
```

Internal to AppMint.getOpenedFile() / getOpenedFiles() / releaseOpenedFile(). The page pulls, rather than being pushed at: a file opened on cold start is parked until it is asked for, so an SPA that mounts late still gets it. Each file's metadata carries `kind` (image | video | audio | document | data) and `url` - https://appassets.androidplatform.net/appmint-shared/<token>/<name>, served from the cache copy with byte ranges, so a shared video streams into <video src> and seeks. Data files and documents are also pulled in MAX_IO_CHUNK slices into a File; media and anything over 64 MB stay url-only (getFile() fetches on demand), so a 300 MB clip never sits in a JS array.

_Described by its group, Files shared to, or opened with, the app, rather than on its own._

## Media and casting

The lock-screen media notification your page drives, and handing a video to a TV.

### `castMedia`

```js
window.WebToApk.castMedia(mediaUrl: String)
```

Offers [mediaUrl] to whatever on this phone can play it on another screen - Chromecast, a Smart TV app, a local player - through the system chooser. This is a hand-off, not a cast session: the app does not stay in control of playback, and there is no callback. A page that needs a real session should use the Cast SDK in JavaScript instead.

### `setMediaMetadata`

```js
window.WebToApk.setMediaMetadata(title: String, artist: String, artworkUrl: String)
```

Lets web content drive the Android media-style notification and receive transport control callbacks (play/pause/next/prev) from the lock screen and notification shade.  Usage from JavaScript:   window.WebToApk.setMediaMetadata('Song Title', 'Artist Name', 'https://…/art.jpg')   window.WebToApk.setPlaybackState(true, 30000, 240000)   // playing, pos ms, dur ms   window.WebToApk.clearMediaNotification()  Callback from Android → JS:   window.WebToApkOnMediaAction('play'|'pause'|'next'|'prev'|'stop')

_Described by its group, Media Notification Bridge, rather than on its own._

### `setPlaybackState`

```js
window.WebToApk.setPlaybackState(isPlaying: Boolean, positionMs: Long, durationMs: Long)
```

Lets web content drive the Android media-style notification and receive transport control callbacks (play/pause/next/prev) from the lock screen and notification shade.  Usage from JavaScript:   window.WebToApk.setMediaMetadata('Song Title', 'Artist Name', 'https://…/art.jpg')   window.WebToApk.setPlaybackState(true, 30000, 240000)   // playing, pos ms, dur ms   window.WebToApk.clearMediaNotification()  Callback from Android → JS:   window.WebToApkOnMediaAction('play'|'pause'|'next'|'prev'|'stop')

_Described by its group, Media Notification Bridge, rather than on its own._

### `clearMediaNotification`

```js
window.WebToApk.clearMediaNotification()
```

Lets web content drive the Android media-style notification and receive transport control callbacks (play/pause/next/prev) from the lock screen and notification shade.  Usage from JavaScript:   window.WebToApk.setMediaMetadata('Song Title', 'Artist Name', 'https://…/art.jpg')   window.WebToApk.setPlaybackState(true, 30000, 240000)   // playing, pos ms, dur ms   window.WebToApk.clearMediaNotification()  Callback from Android → JS:   window.WebToApkOnMediaAction('play'|'pause'|'next'|'prev'|'stop')

_Described by its group, Media Notification Bridge, rather than on its own._

## The window

Fullscreen, picture-in-picture, the system bar colours, screenshot blocking, the splash screen and closing a window.

### `splashHold`

```js
window.WebToApk.splashHold()
```

Keeps the branded launch splash up until [splashReady] is called. By default the splash hides as soon as the body has laid-out children, which for an app that paints a skeleton and then fetches its first screen means "splash, then a skeleton". An app that would rather reveal a finished first screen calls this at import and [splashReady] once that screen is on. Capped at the same 6s backstop as the paint poll, so a page that never reports ready still opens.

### `splashReady`

```js
window.WebToApk.splashReady()
```

The first screen is on - hide the launch splash now (subject to the creator's minimum splash duration). Idempotent; harmless when nothing was held.

### `enterPip`

```js
window.WebToApk.enterPip(): Boolean
```

Shrinks the whole app into a floating picture-in-picture window right now - a video or a call the user wants to keep watching while they leave. Android 8+ and only when the build enabled PiP (the manifest flag it needs); returns whether the window opened. Leaving the app with PiP enabled does this by itself; this is the explicit "minimise" button.

### `closeWindow`

```js
window.WebToApk.closeWindow()
```

The Android share sheet, the system clipboard, and closing a window the page opened. These are the plain-web equivalents (navigator.share, navigator.clipboard, window.close) answered natively so they behave the same inside the app.

_Described by its group, Share, clipboard and window, rather than on its own._

### `setFullscreen`

```js
window.WebToApk.setFullscreen(enabled: Boolean)
```

Lets the page hide the status bar (clock/battery) and navigation bar itself - e.g. a game entering its play screen:     WebToApk.setFullscreen(true)   // hide the system bars     WebToApk.setFullscreen(false)  // bring them back     WebToApk.toggleFullscreen()     WebToApk.isFullscreen() The choice is remembered across launches. It is a no-op in apps the creator already locked to fullscreen/kiosk - there is nothing to restore to there. The side-menu "Fullscreen" item is the equivalent for end users and is gated by the creator's enableFullscreenToggle option; this bridge is always available to the app's own page.

_Described by its group, Fullscreen bridge, rather than on its own._

### `toggleFullscreen`

```js
window.WebToApk.toggleFullscreen()
```

Lets the page hide the status bar (clock/battery) and navigation bar itself - e.g. a game entering its play screen:     WebToApk.setFullscreen(true)   // hide the system bars     WebToApk.setFullscreen(false)  // bring them back     WebToApk.toggleFullscreen()     WebToApk.isFullscreen() The choice is remembered across launches. It is a no-op in apps the creator already locked to fullscreen/kiosk - there is nothing to restore to there. The side-menu "Fullscreen" item is the equivalent for end users and is gated by the creator's enableFullscreenToggle option; this bridge is always available to the app's own page.

_Described by its group, Fullscreen bridge, rather than on its own._

### `isFullscreen`

```js
window.WebToApk.isFullscreen(): Boolean
```

Lets the page hide the status bar (clock/battery) and navigation bar itself - e.g. a game entering its play screen:     WebToApk.setFullscreen(true)   // hide the system bars     WebToApk.setFullscreen(false)  // bring them back     WebToApk.toggleFullscreen()     WebToApk.isFullscreen() The choice is remembered across launches. It is a no-op in apps the creator already locked to fullscreen/kiosk - there is nothing to restore to there. The side-menu "Fullscreen" item is the equivalent for end users and is gated by the creator's enableFullscreenToggle option; this bridge is always available to the app's own page.

_Described by its group, Fullscreen bridge, rather than on its own._

### `setStatusBarColor`

```js
window.WebToApk.setStatusBarColor(color: String, style: String): Boolean
```

Paints the status and navigation bars [color] (any CSS hex) and picks the icon tint: [style] 'light' means light icons on a dark bar, 'dark' the reverse, '' lets the luminance decide. Returns false when the colour does not parse.

### `setSecureScreen`

```js
window.WebToApk.setSecureScreen(enabled: Boolean): Boolean
```

Sets protection for the CURRENT page and returns the state now in force. The window flag itself is applied on the UI thread, but the state this returns is already committed, so a page can call this and immediately reveal its sensitive content without waiting for a callback.

### `isSecureScreen`

```js
window.WebToApk.isSecureScreen(): Boolean
```

WebToApk.setSecureScreen(true)   // block screenshots on THIS page   WebToApk.setSecureScreen(false)  // release it early   WebToApk.isSecureScreen()        // -> boolean  Protection belongs to the page that asked for it. It is released the moment the app navigates anywhere else - a new document, a pushState route, a #hash route - so a protected screen cannot leave the rest of the app locked down, and a page that wants protection back after a reload simply asks again.  What it does: screenshots, screen recording, casting and the recents-screen thumbnail all stop while it is on. What it cannot do: stop a camera pointed at the screen. Nothing on Android can, and no bridge here will pretend otherwise.

_Described by its group, Screen-capture protection, rather than on its own._

## Share, clipboard and print

The Android share sheet, the system clipboard, text another app shared into yours, and the print dialogue.

### `print`

```js
window.WebToApk.print()
```

Hands the page as it currently stands to Android's print dialogue, which can print on paper or save a PDF. Nothing to configure - the WebView renders the document.

_Described by its group, Printing, rather than on its own._

### `shareNative`

```js
window.WebToApk.shareNative(title: String, text: String, url: String)
```

The Android share sheet, the system clipboard, and closing a window the page opened. These are the plain-web equivalents (navigator.share, navigator.clipboard, window.close) answered natively so they behave the same inside the app.

_Described by its group, Share, clipboard and window, rather than on its own._

### `getSharedText`

```js
window.WebToApk.getSharedText(): String
```

Text or a link another app shared INTO this one ("Share to <app>" - a YouTube video shared from the YouTube app arrives as its link), as JSON `{text, subject, url, receivedAt}` or "" when nothing was shared. Kept until read, so an app that mounts after the share still sees it; a share arriving while the app runs also fires `appmint:shared`. A photo or video shared with a caption delivers the file through AppMint.getOpenedFile() and the caption here. Requires the build's "Receive shares from other apps" option with "Text and links" ticked, which registers the share-sheet entry.

### `clearSharedText`

```js
window.WebToApk.clearSharedText()
```

Clears the kept share once the page has consumed it.

### `copyToClipboard`

```js
window.WebToApk.copyToClipboard(text: String): Boolean
```

The Android share sheet, the system clipboard, and closing a window the page opened. These are the plain-web equivalents (navigator.share, navigator.clipboard, window.close) answered natively so they behave the same inside the app.

_Described by its group, Share, clipboard and window, rather than on its own._

### `shareFiles`

```js
window.WebToApk.shareFiles(filesJson: String, title: String, text: String): Boolean
```

TRUE native file share for navigator.share({files:[...]}). Android WebView has no Web Share API, and text/plain ACTION_SEND can't carry a file - so before this a shared image was merely SAVED, not shared. filesJson is [{name, mimeType, base64}, ...]; we write each to cache, expose it via the app's FileProvider, and fire ACTION_SEND / ACTION_SEND_MULTIPLE so the real Android share sheet (WhatsApp, Gmail, …) opens. Returns true if the sheet opened.

### `readClipboard`

```js
window.WebToApk.readClipboard(): String
```

The Android share sheet, the system clipboard, and closing a window the page opened. These are the plain-web equivalents (navigator.share, navigator.clipboard, window.close) answered natively so they behave the same inside the app.

_Described by its group, Share, clipboard and window, rather than on its own._

## Launch, shortcuts and the back button

How the app was opened, long-press shortcuts on the icon, the in-app review prompt, and telling the shell the page wants the back press.

### `getLaunchUrl`

```js
window.WebToApk.getLaunchUrl(): String
```

The deep link that launched or resumed this app, or "" if it was opened normally. Read it whenever your app mounts and route on it yourself: const u = window.WebToApk?.getLaunchUrl?.(); if (u) router.navigate(new URL(u).pathname); The value is KEPT, not consumed, so a late-mounting app still sees it; a later link arriving while the app runs replaces it and also fires 'appmint:deep-link'.

### `setAppShortcuts`

```js
window.WebToApk.setAppShortcuts(itemsJson: String)
```

Launcher shortcuts (long-press the app icon). Up to four entries: `[{id, title, route}]`, where `route` is a path in the app ('/new-note'). A tap opens the app with that route as its launch deep link (`appmint-shortcut://<package><route>`), which the page reads through `getLaunchUrl()` and routes on exactly like any other deep link. Pass `[]` to remove them. Android 7.1+; a no-op below that.

### `rateApp`

```js
window.WebToApk.rateApp()
```

Opens the Play listing's rating flow. `rateApp()` already existed but only the native drawer entry could reach it, so an app that draws its own UI - every AI build, where the drawer is off - had no way to ask for a rating. It is the one store action a page genuinely cannot perform for itself: `market://` is an intent, not a navigable URL. Gated on the creator's own "Rate App Button" switch, exactly like the drawer entry and the bottom-nav Share item: turning Rate off must mean no rating surface anywhere, or the toggle looks broken.

### `__setBackInterest`

```js
window.WebToApk.__setBackInterest(interested: Boolean)
```

*(Back button)* Internal for AppMint.setBackHandler - tells the shell whether the page registered a back handler. When true, a hardware/gesture back is first offered to the page (cancelable `appmint:back` event + the registered handler); only an unconsumed press falls through to history-back / exit.

## Contacts

Reading, searching, picking and writing - the picker needs no permission at all.

### `listContacts`

```js
window.WebToApk.listContacts(requestId: String, limit: Int, offset: Int)
```

All async: cursor reads can be thousands of rows, and a blocking @JavascriptInterface return would run that on the JS thread - an ANR. Results arrive as `appmint:contacts` / window.onAppMintContacts({requestId,...}). requestId: pass a STRING ('pick-' + Date.now()). A raw NUMBER also works - the bridge coerces it through a double ("1.787491234567E12"), and every reply canonicalizes it back (BridgeRequestId), so `res.requestId === Date.now()` strict-compares true either way.    WebToApk.listContacts(id, limit, offset)   WebToApk.searchContacts(id, query, limit)   WebToApk.getContact(id, contactId)   WebToApk.pickContact(id)      <- NO permission needed (system picker)   WebToApk.addContact(id, json) <- needs the Contacts-write permission

_Described by its group, Contacts, rather than on its own._

### `searchContacts`

```js
window.WebToApk.searchContacts(requestId: String, query: String, limit: Int)
```

All async: cursor reads can be thousands of rows, and a blocking @JavascriptInterface return would run that on the JS thread - an ANR. Results arrive as `appmint:contacts` / window.onAppMintContacts({requestId,...}). requestId: pass a STRING ('pick-' + Date.now()). A raw NUMBER also works - the bridge coerces it through a double ("1.787491234567E12"), and every reply canonicalizes it back (BridgeRequestId), so `res.requestId === Date.now()` strict-compares true either way.    WebToApk.listContacts(id, limit, offset)   WebToApk.searchContacts(id, query, limit)   WebToApk.getContact(id, contactId)   WebToApk.pickContact(id)      <- NO permission needed (system picker)   WebToApk.addContact(id, json) <- needs the Contacts-write permission

_Described by its group, Contacts, rather than on its own._

### `getContact`

```js
window.WebToApk.getContact(requestId: String, contactId: String)
```

All async: cursor reads can be thousands of rows, and a blocking @JavascriptInterface return would run that on the JS thread - an ANR. Results arrive as `appmint:contacts` / window.onAppMintContacts({requestId,...}). requestId: pass a STRING ('pick-' + Date.now()). A raw NUMBER also works - the bridge coerces it through a double ("1.787491234567E12"), and every reply canonicalizes it back (BridgeRequestId), so `res.requestId === Date.now()` strict-compares true either way.    WebToApk.listContacts(id, limit, offset)   WebToApk.searchContacts(id, query, limit)   WebToApk.getContact(id, contactId)   WebToApk.pickContact(id)      <- NO permission needed (system picker)   WebToApk.addContact(id, json) <- needs the Contacts-write permission

_Described by its group, Contacts, rather than on its own._

### `pickContact`

```js
window.WebToApk.pickContact(requestId: String)
```

System contact picker - needs NO permission, and is the right choice whenever the page just wants the user to choose one person. Picks from the PHONE table, not the contact table: the picker grants read access only to the row it returns, so picking a phone row is what makes the number readable without READ_CONTACTS. Picking a bare contact would return a row with a name and no number, and reading the number from it would need the permission this method exists to avoid.

### `addContact`

```js
window.WebToApk.addContact(requestId: String, contactJson: String)
```

The system picker (no permission needed) and writing a new contact (WRITE_CONTACTS). The read side - listing and searching - is under the Contacts group above.

_Described by its group, Contacts: pick and add, rather than on its own._

## Phone, SMS and the call log

Placing a call, sending or drafting a message, and reading history. Every one of these is permission-gated and Play asks about them.

### `makePhoneCall`

```js
window.WebToApk.makePhoneCall(phoneNumber: String)
```

Places a call directly when the creator enabled the Phone permission, otherwise opens the dialer with the number prefilled (which needs no permission). A plain `tel:` link in your HTML also works and is often enough.

### `listCallLog`

```js
window.WebToApk.listCallLog(requestId: String, limit: Int, offset: Int, sinceMillis: String)
```

WebToApk.listCallLog(id, limit, offset, sinceMillis) Delivered as `appmint:calllog` / window.onAppMintCallLog.

_Described by its group, Call log, rather than on its own._

### `composeSms`

```js
window.WebToApk.composeSms(phoneNumber: String, message: String): Boolean
```

Opens the user's SMS app with the message prefilled. Needs no permission and cannot be rejected by Play - the right default for anything non-automated.

### `sendSms`

```js
window.WebToApk.sendSms(
```

WebToApk.composeSms(number, message)   <- NO permission, opens the SMS app   WebToApk.sendSms(id, number, message, wantDelivery)   WebToApk.listSms(id, "inbox"|"sent"|"draft", limit, offset) Send results: `appmint:sms` / window.onAppMintSms   {requestId, status:"sent"|"delivered"|"failed", ok, reason?} Inbound messages: `appmint:sms-received` / window.onAppMintSmsReceived.

_Described by its group, SMS, rather than on its own._

### `listSms`

```js
window.WebToApk.listSms(requestId: String, box: String, limit: Int, offset: Int)
```

WebToApk.composeSms(number, message)   <- NO permission, opens the SMS app   WebToApk.sendSms(id, number, message, wantDelivery)   WebToApk.listSms(id, "inbox"|"sent"|"draft", limit, offset) Send results: `appmint:sms` / window.onAppMintSms   {requestId, status:"sent"|"delivered"|"failed", ok, reason?} Inbound messages: `appmint:sms-received` / window.onAppMintSmsReceived.

_Described by its group, SMS, rather than on its own._

## Vibration and sound

Haptic feedback, the app's own click sound fired on your semantic events rather than every stray tap, and the background music track the creator chose at build time - getMusicVolume returns -1 when the app ships none, so a settings screen can hide the slider instead of showing a dead one.

### `vibrate`

```js
window.WebToApk.vibrate(durationMs: Long)
```

Simple haptics for the page (navigator.vibrate and a pattern form). Both are ignored unless the build enabled the Vibrate permission.

_Described by its group, Vibration, rather than on its own._

### `cancelVibrate`

```js
window.WebToApk.cancelVibrate()
```

Simple haptics for the page (navigator.vibrate and a pattern form). Both are ignored unless the build enabled the Vibrate permission.

_Described by its group, Vibration, rather than on its own._

### `vibratePattern`

```js
window.WebToApk.vibratePattern(patternJson: String)
```

Vibrates an on/off pattern, e.g. "[100,50,100]" = buzz 100ms, pause 50, buzz 100. Backs navigator.vibrate(array); prefer the standard API. No-op unless the creator enabled the Vibrate permission.

### `playClick`

```js
window.WebToApk.playClick()
```

Plays the app's tap sound on demand, so a page can fire it on its OWN semantic events (a button press) instead of on every stray tap - which is what a native app actually does, and the reason clickSoundMode can be "off" while this still works. Honours the creator's mode; no-op when tap sound is off.

### `setMusicVolume`

```js
window.WebToApk.setMusicVolume(percent: Int)
```

Set the background-music level from the page, 0..100. The wizard slider decides how the app STARTS; this is how an app gives its own users a music control, which any game with a settings screen is expected to have. Clamped in [BackgroundMusic.setVolume], so a page passing 500 or -1 cannot hand MediaPlayer a gain outside the range it accepts. A no-op when the app was built without a track - there is nothing to set, and the honest answer is [getMusicVolume] returning -1 so the page can hide its slider rather than show one that does nothing.

### `getMusicVolume`

```js
window.WebToApk.getMusicVolume(): Int
```

Current level 0..100, or -1 when this app ships no background music.

## Text to speech

The device voices, spoken from the page.

### `ttsSpeak`

```js
window.WebToApk.ttsSpeak(text: String, lang: String, rate: Double, pitch: Double, utteranceId: String)
```

Backs the window.speechSynthesis polyfill, which is installed at document start in every frame - pages should use the STANDARD speechSynthesis API and these will be called for them. Android WebView ships no working speechSynthesis of its own, which is why the reroute exists.

_Described by its group, Text-to-speech, rather than on its own._

### `ttsCancel`

```js
window.WebToApk.ttsCancel()
```

Backs the window.speechSynthesis polyfill, which is installed at document start in every frame - pages should use the STANDARD speechSynthesis API and these will be called for them. Android WebView ships no working speechSynthesis of its own, which is why the reroute exists.

_Described by its group, Text-to-speech, rather than on its own._

### `ttsIsSpeaking`

```js
window.WebToApk.ttsIsSpeaking(): Boolean
```

Backs the window.speechSynthesis polyfill, which is installed at document start in every frame - pages should use the STANDARD speechSynthesis API and these will be called for them. Android WebView ships no working speechSynthesis of its own, which is why the reroute exists.

_Described by its group, Text-to-speech, rather than on its own._

### `ttsWarmUp`

```js
window.WebToApk.ttsWarmUp()
```

Backs the window.speechSynthesis polyfill, which is installed at document start in every frame - pages should use the STANDARD speechSynthesis API and these will be called for them. Android WebView ships no working speechSynthesis of its own, which is why the reroute exists.

_Described by its group, Text-to-speech, rather than on its own._

### `ttsGetVoices`

```js
window.WebToApk.ttsGetVoices(): String
```

JSON array of installed voices: [{name, lang, default}]. Empty until the engine finishes init - the page gets 'voiceschanged' then and re-queries, exactly like Chrome's async getVoices() contract.

## BLE fitness sensors

Heart rate, speed, cadence, power and battery from standard Bluetooth Low Energy profiles.

### `bleStartScan`

```js
window.WebToApk.bleStartScan()
```

Runtime for the existing Bluetooth permission toggle (permBluetooth) - the permissions were declared while nothing in the runtime touched a sensor, the exact declared-but-dead pattern SmsBridge documents. Results stream as `appmint:ble` events / window.onAppMintBle({kind, ...}).

_Described by its group, BLE fitness sensors (heart rate / speed / cadence / power / battery), rather than on its own._

### `bleStopScan`

```js
window.WebToApk.bleStopScan()
```

Runtime for the existing Bluetooth permission toggle (permBluetooth) - the permissions were declared while nothing in the runtime touched a sensor, the exact declared-but-dead pattern SmsBridge documents. Results stream as `appmint:ble` events / window.onAppMintBle({kind, ...}).

_Described by its group, BLE fitness sensors (heart rate / speed / cadence / power / battery), rather than on its own._

### `bleConnect`

```js
window.WebToApk.bleConnect(address: String)
```

Runtime for the existing Bluetooth permission toggle (permBluetooth) - the permissions were declared while nothing in the runtime touched a sensor, the exact declared-but-dead pattern SmsBridge documents. Results stream as `appmint:ble` events / window.onAppMintBle({kind, ...}).

_Described by its group, BLE fitness sensors (heart rate / speed / cadence / power / battery), rather than on its own._

### `bleDisconnect`

```js
window.WebToApk.bleDisconnect()
```

Runtime for the existing Bluetooth permission toggle (permBluetooth) - the permissions were declared while nothing in the runtime touched a sensor, the exact declared-but-dead pattern SmsBridge documents. Results stream as `appmint:ble` events / window.onAppMintBle({kind, ...}).

_Described by its group, BLE fitness sensors (heart rate / speed / cadence / power / battery), rather than on its own._

### `bleSetWheelCircumference`

```js
window.WebToApk.bleSetWheelCircumference(mm: Int)
```

Runtime for the existing Bluetooth permission toggle (permBluetooth) - the permissions were declared while nothing in the runtime touched a sensor, the exact declared-but-dead pattern SmsBridge documents. Results stream as `appmint:ble` events / window.onAppMintBle({kind, ...}).

_Described by its group, BLE fitness sensors (heart rate / speed / cadence / power / battery), rather than on its own._

## Web Bluetooth

The navigator.bluetooth shape, answered natively so a page written for Chrome works unchanged.

### `wbIsAvailable`

```js
window.WebToApk.wbIsAvailable(): Boolean
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbRequestDevice`

```js
window.WebToApk.wbRequestDevice(requestId: String, optionsJson: String)
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbConnect`

```js
window.WebToApk.wbConnect(requestId: String, deviceId: String)
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbDisconnect`

```js
window.WebToApk.wbDisconnect(deviceId: String)
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbGetCharacteristics`

```js
window.WebToApk.wbGetCharacteristics(requestId: String, deviceId: String, service: String)
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbRead`

```js
window.WebToApk.wbRead(requestId: String, deviceId: String, service: String, characteristic: String)
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbWrite`

```js
window.WebToApk.wbWrite(
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

### `wbNotify`

```js
window.WebToApk.wbNotify(
```

Raw transport for WebBluetoothPolyfill. A page never calls these directly - it calls navigator.bluetooth, exactly as it would in a browser.

_Described by its group, Web Bluetooth (navigator.bluetooth), rather than on its own._

## NFC

Reading a tag through window.AndroidNFC, and the write side behind the NDEFReader polyfill.

### `__nfcWrite`

```js
window.WebToApk.__nfcWrite(messageJson: String)
```

Called from the JS NDEFReader.write() polyfill. Stores the message JSON and waits for the next NFC tag tap.

_Described by its group, NFC Write Bridge, rather than on its own._

### `__nfcMakeReadOnly`

```js
window.WebToApk.__nfcMakeReadOnly()
```

Called from the JS NDEFReader.makeReadOnly() polyfill.

### `__nfcCancelWrite`

```js
window.WebToApk.__nfcCancelWrite()
```

Cancel any pending NFC write/lock operation.

### `startScan`

```js
window.AndroidNFC.startScan(): Boolean
```

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.

_Described by its group, Web NFC, rather than on its own._

## Background jobs

Work that keeps going after the app is closed: a durable auto-save, a periodic sync.

### `workEnqueueOnline`

```js
window.WebToApk.workEnqueueOnline(id: String, url: String, method: String, headersJson: String, payload: String)
```

No permission needed; results echo as `appmint:work` / window.onAppMintWork.

_Described by its group, Background jobs (WorkManager): durable auto-save + periodic native sync, rather than on its own._

### `workSchedulePeriodic`

```js
window.WebToApk.workSchedulePeriodic(id: String, url: String, method: String, headersJson: String, payload: String, intervalMinutes: Int)
```

No permission needed; results echo as `appmint:work` / window.onAppMintWork.

_Described by its group, Background jobs (WorkManager): durable auto-save + periodic native sync, rather than on its own._

### `workCancel`

```js
window.WebToApk.workCancel(id: String)
```

No permission needed; results echo as `appmint:work` / window.onAppMintWork.

_Described by its group, Background jobs (WorkManager): durable auto-save + periodic native sync, rather than on its own._

### `workList`

```js
window.WebToApk.workList(requestId: String)
```

No permission needed; results echo as `appmint:work` / window.onAppMintWork.

_Described by its group, Background jobs (WorkManager): durable auto-save + periodic native sync, rather than on its own._

## Device and app information

What phone this is, which build, and a stable per-install identifier.

### `getAppName`

```js
window.WebToApk.getAppName(): String
```

The app name the creator chose in the wizard - what the launcher shows.

### `getAppVersion`

```js
window.WebToApk.getAppVersion(): String
```

The versionName from the installed package, e.g. "1.4.2" - the string a creator sets when building, not the versionCode. Falls back to "1.0" if the package cannot be read, so a page can print it without a null check.

### `getDeviceInfo`

```js
window.WebToApk.getDeviceInfo(): String
```

WebToApk.getDeviceInfo()    -> JSON string, NO permission required   WebToApk.getPhoneIdentity() -> carrier/SIM, needs the Phone permission   WebToApk.getInstallId()     -> stable per-install UUID

_Described by its group, Device / app information, rather than on its own._

### `getPhoneIdentity`

```js
window.WebToApk.getPhoneIdentity(): String
```

WebToApk.getDeviceInfo()    -> JSON string, NO permission required   WebToApk.getPhoneIdentity() -> carrier/SIM, needs the Phone permission   WebToApk.getInstallId()     -> stable per-install UUID

_Described by its group, Device / app information, rather than on its own._

### `getInstallId`

```js
window.WebToApk.getInstallId(): String
```

WebToApk.getDeviceInfo()    -> JSON string, NO permission required   WebToApk.getPhoneIdentity() -> carrier/SIM, needs the Phone permission   WebToApk.getInstallId()     -> stable per-install UUID

_Described by its group, Device / app information, rather than on its own._