Skip to content

ANDROID_WEBVIEW.md

Latest commit

 

History

History
176 lines (123 loc) · 6.69 KB

ANDROID_WEBVIEW.md

File metadata and controls

176 lines (123 loc) · 6.69 KB

Android WebView Emulation

Emulate Android WebView, the embedded browser used inside Android apps, with consistent identity and fingerprint protection.

Prerequisites

  • BotBrowser binary installed. See INSTALLATION.md.
  • An Android profile file (.enc for production).
  • ENT Tier3 license for WebView brand support.
  • PRO license for --bot-custom-headers (if injecting app headers).

Overview

Android WebView is the embedded browser component that Android apps use to display web content. It differs from regular Chrome in several ways: the User-Agent string includes a wv token, Client Hints report different brand values, and certain JavaScript APIs expose app-specific objects like window.android. Each of these differences is a fingerprint surface that must remain internally consistent to prevent identity mismatches.

BotBrowser can emulate WebView identity using the --bot-config-browser-brand=webview flag. This changes the User-Agent, navigator.userAgentData.brands, Client Hints headers, and other surfaces to match a real WebView environment.

Quick Start

chromium-browser \
  --bot-profile="/path/to/android-profile.enc" \
  --bot-config-browser-brand=webview \
  --bot-config-platform=Android \
  --bot-config-platform-version=13 \
  --bot-config-model=SM-G991B \
  --bot-config-mobile=true \
  --user-agent="Mozilla/5.0 (Linux; Android {platform-version}; {model} Build/TP1A.220624.021; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/{ua-full-version} Mobile Safari/537.36"

How It Works

What Makes WebView Different

WebView differs from regular Chrome in several identity surfaces: the User-Agent string includes a wv token and a Version/4.0 prefix, the brand identity reports "Android WebView" instead of "Google Chrome", and apps may inject custom headers like X-Requested-With. BotBrowser configures all of these surfaces consistently when using the webview brand.

What BotBrowser Configures

When you set --bot-config-browser-brand=webview:

  1. Brand identity. navigator.userAgentData.brands includes "Android WebView" instead of "Google Chrome".
  2. Client Hints. All Client Hints headers reflect the WebView brand.
  3. User-Agent placeholder. The {ua-full-version} placeholder in --user-agent resolves to the Chromium version, which WebView shares with Chrome.

Android 16+ UA Reduction

Starting with Android 16, Google applies UA reduction to WebView. When the profile's platform-version is 16 or higher, BotBrowser automatically freezes the UA string placeholders to reduced values ({platform-version} becomes 10, {model} becomes K, {ua-full-version} becomes a frozen major version). Client Hints continue to report the real values. The same --user-agent template works for both old and new Android versions without modification.

Custom HTTP Headers for App Identity

Many Android apps inject an X-Requested-With header containing their package name. Use --bot-custom-headers to replicate this:

chromium-browser \
  --bot-profile="/path/to/android-profile.enc" \
  --bot-config-browser-brand=webview \
  --bot-custom-headers='{"X-Requested-With":"com.example.app"}'

Or via CDP:

const cdpSession = await browser.newBrowserCDPSession();
await cdpSession.send("BotBrowser.setCustomHeaders", {
  headers: { "X-Requested-With": "com.example.app" },
});

Common Scenarios

Full WebView identity with Playwright

import { chromium } from "playwright-core";

const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    "--bot-profile=/path/to/android-profile.enc",
    "--bot-config-browser-brand=webview",
    "--bot-config-platform=Android",
    "--bot-config-platform-version=13",
    "--bot-config-model=SM-G991B",
    "--bot-config-mobile=true",
    "--bot-config-architecture=arm",
    "--bot-config-bitness=64",
    '--user-agent=Mozilla/5.0 (Linux; Android {platform-version}; {model} Build/TP1A.220624.021; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/{ua-full-version} Mobile Safari/537.36',
    '--bot-custom-headers={"X-Requested-With":"com.example.app"}',
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
  ],
});

const page = await browser.newPage();
await page.addInitScript(() => {
  delete window.__playwright__binding__;
  delete window.__pwInitScripts;
});

await page.goto("https://example.com");

// Verify WebView identity
const brands = await page.evaluate(() =>
  navigator.userAgentData.brands.map((b) => b.brand)
);
console.log("Brands:", brands); // Includes "Android WebView"

await browser.close();

WebView with app header

const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    "--bot-profile=/path/to/android-profile.enc",
    "--bot-config-browser-brand=webview",
    "--bot-config-platform=Android",
    "--bot-config-mobile=true",
    '--bot-custom-headers={"X-Requested-With":"com.example.app"}',
  ],
});

Troubleshooting / FAQ

Problem Solution
Brands still show "Google Chrome" Ensure --bot-config-browser-brand=webview is in the args array. WebView brand requires ENT Tier3.
User-Agent missing wv token Set --user-agent with the WebView UA format. BotBrowser does not auto-modify the UA string for WebView.
Custom headers not sent Use --bot-custom-headers (CLI) or BotBrowser.setCustomHeaders (CDP on browser-level session).

Next Steps

Related documentation: CLI Flags Reference | Advanced Features | Profile Configuration

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.