# Justson/AgentWeb: an Android WebView wrapper with a middleware layer

> AgentWeb is an Apache-2.0 Java library that wraps Android WebView with lifecycle handling, progress, file chooser and middleware hooks. The README is explicit about what breaks if you replace its clients, and that is the part worth reading before you adopt it.

**Justson/AgentWeb** —  AgentWeb is a powerful library based on Android WebView.

- Repository: https://github.com/Justson/AgentWeb
- Website: https://www.jianshu.com/p/fc7909e24178
- Stars: 9,432 · Forks: 1,664
- Language: Java
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/justson-agentweb

## The problem AgentWeb solves for Android hybrid apps

A bare Android WebView gives you a rendering surface and almost nothing else. Progress indication, error pages, file picker wiring, cookie handling, lifecycle forwarding and JavaScript bridge plumbing are all left to the caller, and every team that ships a hybrid screen writes roughly the same code to get them. AgentWeb is that code, packaged. The README describes it as a library based on Android WebView that is "extremely easy to use" and provides a set of solutions to common WebView problems, while staying lightweight and flexible.

The target reader is an Android developer embedding web content inside a native app: a marketing page, a checkout flow, a help centre, an account page served from the web. The library is written in Java and published under Apache-2.0, so it fits Java and Kotlin codebases alike. It is not a cross-platform framework and it does not replace the system WebView; it sits on top of it. If you are building a browser app, this is not the layer you want. If you are building an app that happens to contain web pages, it removes a known pile of boilerplate.

The repository is split into agentweb-core and agentweb-filechooser modules, with a sample app at the top level. The core module is the required dependency; the file chooser is optional and only needed if your web content opens file inputs.

## How AgentWeb is structured: core, middleware and the clients you must not replace

The architectural decision that shapes everything else is that AgentWeb owns the WebViewClient and WebChromeClient instances. The README states this as a warning: do not call setWebViewClient() or setWebChromeClient() directly on the WebView. Doing so replaces AgentWeb's internal implementations wholesale, and the progress bar, error page and file chooser stop working as a result.

The supported path is to configure through AgentWeb.with(...) and its setWebViewClient() / setWebChromeClient() methods, or to stack behaviour using the MiddlewareWebClientBase and MiddlewareWebChromeBase middleware classes. The middleware model is the interesting part: instead of one client that does everything, you compose a chain, and each layer can intercept a URL or a callback before passing it along. That is a real design choice rather than a thin wrapper, and it is the main reason to choose this library over copying a WebViewClient from a blog post.

Two constraints follow from the same design. First, AgentWeb uses an AlertDialog internally, so the host app must depend on an AppCompat theme; a plain framework theme will not do. Second, setAgentWebParent does not support ConstraintLayout, which rules the library out for layouts built entirely on that container. Both are stated plainly in the README's notes section, and both are the kind of thing you discover at integration time rather than at design time.

Lifecycle handling is centralised too, and that has a sharp edge: calling mAgentWeb.getWebLifeCycle().onPause() pauses every WebView in the application, not just the one you called it on. If your app hosts several web surfaces that must pause independently, this API is the wrong tool.

## Installing AgentWeb from JitPack and opening a first page

AgentWeb is distributed through JitPack, so the repository has to be declared before the dependency will resolve. The README shows the classic allprojects block, and a separate variant for Gradle 7 and later where repositories are managed centrally in settings.gradle.

```groovy
allprojects {
  repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
  }
}
```

If your build uses settings.gradle for dependency resolution, the README places the same repository inside dependencyResolutionManagement instead. Either way, mavenCentral() stays alongside it. Then add the core artifact, plus the optional modules you actually need.

```groovy
implementation 'com.github.Justson.AgentWeb:agentweb-core:5.1.7-androidx' // (必选)
implementation 'com.github.Justson.AgentWeb:agentweb-filechooser:5.1.7-androidx' // (可选)
implementation 'com.github.Justson:Downloader:v5.0.6-androidx' // (可选)
```

The version string is where people lose an afternoon. The Git tag is v5.1.7-androidx, but JitPack strips the leading v when it generates coordinates, so the dependency is written 5.1.7-androidx. Note that the Downloader artifact does keep its v prefix, which makes the inconsistency easy to miss. The README does not give a full first-activity code sample; it points to the Sample module in the repository and to the Wiki, which it describes as incomplete, and recommends the sample.

Before you run anything, check your Gradle and AGP versions. From v5.1.2 the library moved to compileSdk and targetSdk 36 (Android 16) and Android Gradle Plugin 8.13.2, and the README tells integrators to upgrade their own Gradle and AGP to match. A project still on an older AGP will not build against this release.

## Scheme handling, the queryIntentActivities privacy flag and when to disable it

When a page navigates to a non-http, non-https scheme, AgentWeb calls queryIntentActivities to decide whether another app can handle it. That call is the mechanism behind external app launches, and it is also the reason the README raises a privacy concern: app store privacy scanners may classify it as reading the installed application list.

If your app never needs to hand a URL off to an external app, the README gives a direct fix. Setting setOpenOtherPageWays(DefaultWebClient.OpenOtherPageWays.DISALLOW) stops the call from happening at all. That is a one-line change with a measurable compliance consequence, and it is worth deciding deliberately rather than inheriting the default.

The related setOpenOtherPageWays(ASK) mode has a behaviour that reads like a bug and is not one. The prompt only appears when the target app is already installed. If nothing on the device can handle the scheme, no dialog is shown, because there is no component to hand the intent to. The README calls this expected behaviour, which is honest, but it means ASK gives you no feedback in the case where a user most likely needs it.

Payment is handled unevenly. Alipay requires the Alipay SDK to be added and depended on in the project; WeChat Pay, according to the README, requires no extra work. If your hybrid checkout uses Alipay, budget for that SDK integration before you plan the sprint.

## Where AgentWeb is the wrong choice

The ConstraintLayout restriction is the most concrete disqualifier. setAgentWebParent does not support it, so an app whose screens are built on ConstraintLayout has to introduce a different container for the AgentWeb view specifically, or pick another library. For a modern codebase this is not a small concession.

The global pause behaviour is the second. Because getWebLifeCycle().onPause() pauses all WebViews in the application, any app with two independent web surfaces, say a chat webview and an article webview, cannot pause one without pausing the other. The README states this without offering a per-instance alternative.

The third is the AppCompat theme dependency, which is a hard requirement rather than a preference: AgentWeb uses AlertDialog internally and the README ties that to needing an AppCompat theme. Apps on a non-AppCompat theme path would have to change their theme before this library will behave.

Finally, the documentation is thin in a specific way. The Wiki is described by the README itself as incomplete, and the recommended source of truth is the Sample module. That is workable if you are comfortable reading sample code to infer API contracts, and frustrating if you expect reference documentation for every builder method. There is also no rollback guidance in the README: nothing describes how to revert to a previous version if an upgrade breaks your integration, so plan your version pinning accordingly.

## AgentWeb compared with WebViewAssetLoader and a hand-written WebViewClient

The closest thing in the Android platform itself is WebViewAssetLoader, which serves local assets over an http(s) origin so that a page loaded from your APK behaves like a normal web origin. The difference in approach is fundamental. WebViewAssetLoader solves one problem, content origin, and leaves progress, error pages, file chooser, lifecycle and middleware to you. AgentWeb solves the surrounding set and does not address asset loading at all.

If your requirement is only that local files load under a proper origin, WebViewAssetLoader is the smaller dependency and it is part of AndroidX. If your requirement is the whole hybrid screen, AgentWeb gives you more, at the cost of taking ownership of your WebViewClient and WebChromeClient and constraining your parent layout and theme.

The second alternative is simply writing your own WebViewClient subclass, which many teams do. The gap is the middleware chain. MiddlewareWebClientBase and MiddlewareWebChromeBase let you compose interception layers, so a cookie handler, a URL interceptor and an error handler can each be a separate unit. A hand-written client tends to grow into one method with several unrelated branches. That composability, not the feature list, is the concrete argument for AgentWeb.

## Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-14, the same day as the v5.1.7-androidx release. The preceding release, v5.1.6-androidx, came on 2026-08-27. Before those two, the listed releases jump back to v5.1.1-androidx in December 2023, so the release cadence has been uneven rather than steady. Two releases in a month after a long gap is worth noting when you decide how much to depend on future fixes.

The upgrade cost is real and documented. Moving to v5.1.2 or later means compileSdk and targetSdk 36, Android Gradle Plugin 8.13.2, and matching Gradle in your own project. That is a coordinated change across your build files, not a version bump in one line. If your app is pinned to an older AGP for other reasons, you are effectively stuck on an earlier AgentWeb release until that is resolved.

One upgrade got cheaper. From v5.1.3 the library ships the keep rules for @JavascriptInterface inside the package, so integrators no longer need to declare them in their own proguard-rules.pro. If you have those rules in your project from an earlier integration, they are now redundant.

On licensing, AgentWeb is Apache-2.0, which permits commercial use and modification. The README quotes the standard Apache 2.0 text and points to the LICENSE file at the repository root. Apache-2.0 does not by itself resolve the Alipay SDK dependency the README mentions, which carries its own terms; that is a question for your own legal review, not something this article can settle.

## Conclusion

Adopt AgentWeb if you are embedding a hybrid web surface in an Android app and you want progress, error pages, file chooser and lifecycle handling without writing them yourself; the middleware classes are the reason to pick it over a hand-rolled WebViewClient. Do not adopt it if your root layout is a ConstraintLayout, if you need per-WebView pause control (getWebLifeCycle().onPause() pauses every WebView in the app), or if you cannot move to compileSdk 36 and Android Gradle Plugin 8.13.2, which v5.1.2 requires. Before writing any code, verify three things in your own project: that your app theme descends from AppCompat, that the JitPack coordinate is written without the leading v (5.1.7-androidx, while the tag is v5.1.7-androidx), and that your proguard-rules.pro no longer needs the @JavascriptInterface keep rules that v5.1.3 began shipping inside the library.

## FAQ

### What is AgentWeb and who is it for?

AgentWeb is a Java library built on Android WebView, published under Apache-2.0, that packages common hybrid-app concerns such as progress, error pages, file chooser, cookie handling and lifecycle forwarding. It is aimed at Android developers embedding web content inside a native app rather than at teams building a full browser.

### How do I add AgentWeb to an Android project?

Add the JitPack repository alongside mavenCentral(), then depend on com.github.Justson.AgentWeb:agentweb-core:5.1.7-androidx, with agentweb-filechooser optional if your pages use file inputs. The version in the dependency has no leading v, even though the Git tag is v5.1.7-androidx.

### Why does AgentWeb break when I call setWebViewClient directly?

The README warns that calling setWebViewClient() or setWebChromeClient() on the WebView replaces AgentWeb's internal implementations entirely, which disables the progress bar, error page and file chooser. Configure through AgentWeb.with(...) instead, or stack behaviour with MiddlewareWebClientBase and MiddlewareWebChromeBase.

### Does AgentWeb work with ConstraintLayout?

No. The README states that setAgentWebParent does not support ConstraintLayout, so a layout built on that container needs a different parent for the AgentWeb view or a different library.

### Which Android SDK and Gradle versions does AgentWeb require?

From v5.1.2 the README states compileSdk and targetSdk were raised to 36 (Android 16) and Android Gradle Plugin to 8.13.2, and it asks integrators to upgrade their project's Gradle and AGP to match. Earlier releases do not carry that requirement.

## Sources

- [Justson/AgentWeb on GitHub](https://github.com/Justson/AgentWeb)
- [License: Apache-2.0](https://github.com/Justson/AgentWeb/blob/androidx/LICENSE)
- [Project website](https://www.jianshu.com/p/fc7909e24178)
- [README](https://github.com/Justson/AgentWeb/blob/androidx/README.md)
- [Releases](https://github.com/Justson/AgentWeb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/justson-agentweb