To set a custom user agent in an Android WebView, call webView.settings.userAgentString = "..." before loadUrl. Most apps should append a suffix to the default string rather than replace it, so websites still see a normal mobile browser. Passing null or an empty string resets the WebView to the system default.
How to set a custom user agent in an Android WebView
You set the user agent through the WebView’s settings object, and it applies to every request that WebView makes afterward. The WebSettings reference says setUserAgentString sets the WebView’s user-agent string, and a null or empty value falls back to the system default.
val webView = findViewById<WebView>(R.id.webview)
webView.settings.javaScriptEnabled = true
// Append an app token to the default string
val defaultUa = webView.settings.userAgentString
webView.settings.userAgentString = "$defaultUa MyShopApp/2.3"
webView.loadUrl("https://example.com/")
Set it before loadUrl. The same reference says that since Android KitKat, changing the user agent while a page is loading makes WebView start loading again. Change it mid-load and you get a double request and a visible flicker.
The setting is per instance. A second WebView for a popup or a sign-in screen needs the string set too.
Append or replace: which to use
Appending a suffix keeps everything sites already expect and adds one token you control. Replacing the whole string is only worth it when a site misbehaves with the default.
| Approach | Code | Keeps wv token |
Client Hints sent |
|---|---|---|---|
| Default | nothing | Yes | Yes |
| Append | getUserAgentString() + " MyApp/1.0" |
Yes | Not guaranteed |
| Replace | setUserAgentString("Mozilla/5.0 ...") |
Only if you copy it in | Not guaranteed |
Google’s post on WebView user-agent reduction says sites can keep detecting WebView by looking for the wv token, unless an app overrides the user agent. A full replacement copied from a phone’s Chrome drops it.
To read the default without a WebView instance, call WebSettings.getDefaultUserAgent(context). It returns the string a fresh WebView would use.
Detect your app from the website
An appended token is the cleanest way for your site to know it’s running inside your app. Say an online store appends MyShopApp/2.3, then hides its “Download our app” banner when that token is present.
if (navigator.userAgent.includes("MyShopApp/")) {
document.querySelector(".app-banner")?.remove();
}
Keep this to small tweaks like hiding a banner or a footer. The User-Agent reference warns that serving different content to different browsers by user agent is usually a bad idea. A version number in the token also lets your server spot users on an old build, which helps when you ship an update.
What Android 17 changes for WebView user agents
The default WebView user agent is getting less detailed, and that changes what an appended string contains. Chrome has sent a reduced string on desktop and Android since Chrome 107, and Google says the default WebView string will be reduced the same way beginning in Android 17.
The reduced default looks like this:
Mozilla/5.0 (Linux; Android 10; K; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/125.0.0.0 Mobile Safari/537.36
OS, CPU and build details become the static Linux; Android 10; K, and minor version numbers become 0.0.0. Two consequences for custom strings:
- If you append to
getUserAgentString(), the default part is reduced and your suffix stays as you wrote it. - If you set a fully custom string, it isn’t reduced. Your app then sends whatever you wrote, including any device details you hardcoded.
Server code that reads the Android version or phone model from the WebView user agent will break. Read the version from your own token instead.
Client Hints and the metadata API
Overriding the user agent can also change what the Client Hints headers report. Client Hints let a server ask for device details instead of parsing the user-agent string, as the Client Hints overview explains.
Per the same Android post, WebView has supported Client Hints since version 116, but only for apps that send the default user agent. The WebSettings reference adds that an override can change the Client Hints headers and navigator.userAgentData.
If your site depends on Client Hints, set them explicitly. WebSettingsCompat’s setUserAgentMetadata, added in androidx.webkit 1.9.0, sets the metadata WebView uses to generate them. Check WebViewFeature.isFeatureSupported(WebViewFeature.USER_AGENT_METADATA) first, because older WebView versions don’t have it.
Desktop mode and sign-in workarounds
Some apps swap in a desktop browser’s user agent to get a site’s desktop layout. You get the layout, but also a desktop UI on a phone screen, and you lose the wv token. A responsive site plus proper full-screen handling is usually the better fix.
Don’t use a fake user agent to get past Google’s block on sign-in inside WebViews. The disallowed_useragent guide explains why that block exists, and the Google sign-in guide covers the supported routes.
My take and one limitation
Append. Don’t replace. A short token like MyShopApp/2.3 gives your server everything it needs, keeps the wv marker, and survives the Android 17 reduction untouched.
The limitation: a custom user agent covers only requests the WebView itself makes. Links you open in Chrome or a Custom Tab use that browser’s own string. If you build with webtoapkfree.com, the builder doesn’t list a user-agent setting among its options, so this applies when you edit the WebView code yourself. Its apps load your live website in a WebView, and you can confirm what your pages see with Chrome DevTools by checking navigator.userAgent in the console.
FAQ
How do I reset a WebView to its default user agent?
Call setUserAgentString(null) or pass an empty string. Android’s reference says the system default value is then used.
Should I replace the user agent or append to it?
Append in most cases. Reading getUserAgentString() and adding a suffix keeps the browser details sites expect, while a full replacement removes the wv token unless you copy it in.
Does changing the user agent reload the page?
Yes, if a page is loading. Since Android KitKat, changing the user agent while a page loads makes WebView start loading again, so set it before loadUrl.
Will Android 17 change my WebView user agent?
Only the default part. From Android 17 the default WebView string is reduced to a static ‘Linux; Android 10; K’ form. A suffix you append stays unchanged, and a fully custom string isn’t reduced.
How does my website know it is running inside my app?
Append a token such as MyShopApp/2.3 to the user agent and look for it on the server or in navigator.userAgent. Sites can also look for the wv token if you keep the default string.