Is Cefrium a fit for your app?
Cefrium ships a real Chromium engine, and a real engine brings real constraints. Three teams evaluated Cefrium and each one found the same five. This page states them first, so you can decide in ten minutes instead of finding them in a build error. Two of the five have a workaround. Three do not, and this page says so.
The five constraints
| Constraint | Value | Can it change? |
|---|---|---|
| Build toolchain | JDK 25, Gradle 9.7.1, AGP 9.4, compileSdk 37 | No. The floor comes from Chromium. |
| Android version | Android 10 or newer (minSdk 29) |
No. Fall back to the System WebView below 10. |
| CPU architecture | arm64-v8a, armeabi-v7a and x86_64 |
No 32-bit x86: use an x86_64 emulator image. |
| Download size | About 89 MB per architecture | Partly. Ship an App Bundle. |
| Public API | Can change until 1.0 | Yes. Version 1.0 freezes it. |
Keep the plugin at the SDK's version
The com.cefrium Gradle plugin and the SDK are two lines in
your build. Update them together. The plugin keeps the engine's assets
uncompressed in your APK, and their names changed in 0.18.0. With an older
plugin, Cefrium.initialize() throws an
IllegalStateException that names the SDK version to use.
Why the toolchain floor is JDK 25
Chromium 152 and newer compile their own Java code at --release 25,
because that code uses Java 22 syntax. The Cefrium AAR carries that compiled
Chromium code. We counted it in the published 0.21.0 artifact:
- 31,453 classes in total,
- 31,258 of them are class-file major 69, which means Java 25,
- 30,896 of those belong to Chromium itself, not to Cefrium.
Your build has to read those 31,258 classes. A JDK 21 toolchain cannot read
class-file 69, so it reports cannot access CefriumBrowser or
Unsupported class file major version 69. Cefrium owns only 223 of
those classes, counting inner classes. Lowering our own compiler target would not move the floor.
The Gradle plugin is not the blocker. Three evaluators
assumed the com.cefrium Gradle plugin forced JDK 25 on them. It
does not. We compile that plugin to Java 17 on purpose, so Gradle can apply it
on an older JDK. Check it yourself: CefriumPlugin.class inside the
published jar is class-file major 61.
An app that cannot move to AGP 9.4 yet. Gradle resolves one
AGP version per build, so a Cefrium module cannot sit in the same build as an
AGP 8 app. Give it its own Gradle build, with its own
settings.gradle.kts and wrapper, and build it from its own
directory. Source and assets can still be shared through source sets. An app
that already ships another engine (GeckoView, the System WebView) can add
Cefrium that way without touching its main build.
Android 9 and older: keep the System WebView
Chromium sets minSdk 29 for every target it builds. That is
Chromium's own default, not a choice Cefrium made, and we cannot lower it. If
you must support Android 7 to 9, pick the engine once at startup.
Put each engine behind one interface, and put each implementation in its own class. The class loader on an Android 9 device then never loads the Cefrium one.
interface WebEngine {
View view();
void loadUrl(String url);
}
static WebEngine create(Activity host) {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { // Android 10
return new CefriumEngine(host); // uses com.cefrium.CefriumBrowser
}
return new SystemWebViewEngine(host); // uses android.webkit.WebView
}
This pattern loads one engine per device.
WebView and Cefrium in one process
Since 0.18.0 both run in one process, in either order: WebView first, Cefrium first, or one screen of each. The webview-same-process sample runs each order.
Before 0.18.0, Cefrium first killed the app at the first
new WebView(), with
org.chromium.base.JniAndroid$UncaughtExceptionException from
WebViewChromiumFactoryProvider. On those versions, load WebView's
engine before any Cefrium call (WebSettings.getDefaultUserAgent(context)
in Application.onCreate()), or run the WebView screens in their
own process with android:process=":webview".
Be aware of what this pattern does not solve. Your Android 9 users still download the native library, because it sits in the same APK. The pattern buys you compatibility, not size. If size on old devices matters, publish a separate flavour without the Cefrium dependency.
What your users download
The native library is large. The figure that gets quoted is the uncompressed one, and it overstates what a user downloads. Here are both, measured on the published 0.21.0 artifact. Every figure here is decimal MB, the unit Google Play reports a download size in:
| arm64-v8a | x86_64 | armeabi-v7a | |
|---|---|---|---|
libcef.so, uncompressed | 212 MB | 239 MB | 109 MB |
| Compressed inside the AAR | 89 MB | 99 MB | 61 MB |
The published AAR holds all three architectures and measures 292 MB. Your users never download that. Google Play delivers one architecture per device from an App Bundle, so the real download is about 89 MB on a phone. Publish an App Bundle rather than a universal APK.
This is the cost of a complete browser engine. We do not claim it is small. See the benchmarks for memory and startup numbers next to the System WebView.
Deliver the engine on demand
When only some users open a browser screen, keep the engine out of the
install with Play Feature Delivery. Put com.cefrium:cefrium-sdk-core
(Java API, resources, assets) in the base module and the
com.cefrium:cefrium-native-codecs-<abi> modules (the
libcef.so) in an on-demand dynamic feature module. Google Play
then installs the engine as a split of your package the first time it is
requested, and the engine's renderers load it from there. Measured on a 64-bit
ARM phone (0.19.0):
| Download | |
|---|---|
| Install, without the engine | 36 MB |
| Engine, on demand | 89 MB |
| One app with the engine inside | 125 MB |
Give the base and the engine module the same abiFilters, apply
the com.cefrium plugin to the base, and check
SplitInstallManager.getInstalledModules() before opening a
browser screen. The
feature-delivery
sample does all of it and shows how to test the split on a device without
Play.
The permissions in your merged manifest
The SDK and its dependencies add eleven permissions to your app. Each row below says what needs it and what we saw on a device with it removed. The permissions sample runs each case, so you can check your own build.
| Permission | Added by | Used for | Without it |
|---|---|---|---|
INTERNET |
Cefrium, Firebase | Every request, loopback included | The engine starts and every request fails. |
ACCESS_NETWORK_STATE |
Cefrium, Cast | The engine's network stack, at start | The app is killed at start. |
FOREGROUND_SERVICE,
FOREGROUND_SERVICE_MEDIA_PLAYBACK |
Cefrium, Cast | Media controls, with setMediaSessionEnabled(true) |
Sound plays, with no lock-screen or shade controls. Before 0.18.0 the app was killed. |
POST_NOTIFICATIONS |
Cefrium, Firebase Messaging | Web notifications and the media controls (Android 13 and newer; the app also asks the user for it) | showNotification() resolves and nothing is shown. |
CREDENTIAL_MANAGER_SET_ORIGIN |
Cefrium | Passkeys (Android 14 and newer) | Passkey requests fail with NotAllowedError. |
CREDENTIAL_MANAGER_QUERY_CANDIDATE_CREDENTIALS |
Cefrium | Passkey suggestions in sign-in fields (Android 14 and newer) | The app is killed on the first page with a passkey field. |
com.google.android.c2dm.permission.RECEIVE,
WAKE_LOCK |
Firebase Messaging | Firebase Cloud Messaging | We saw no difference: Web Push subscribed and delivered, with the app open and closed (Android 10). |
<app id>.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION |
androidx.core | Receivers that Play services and ML Kit register on Android 12 and older | Not measured. Keep it. |
com.google.android.apps.aicore.service.BIND_SERVICE |
ML Kit GenAI | On-device AI through Google AICore | Not measured: it needs a device with AICore. |
To remove one, mark it in your own manifest:
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"
tools:node="remove" />
On Google Play, an app that targets Android 14 or newer and keeps
FOREGROUND_SERVICE_MEDIA_PLAYBACK must declare the foreground
service in Play Console (App content, Foreground service permissions). If you
do not call setMediaSessionEnabled(true), remove both foreground
service permissions instead.
What pre-1.0 means for you
Cefrium is below 1.0, and the public API can still change between releases. That is the honest state and it is the main reason teams wait. Version 1.0 is the first stability commitment, and these are its terms:
- a reviewed public API surface, frozen at 1.0,
- no breaking change in 1.x without a major version and a deprecation window,
- no Chromium internals (
org.chromium.*) in any public signature, - published reference documentation for every public symbol.
You do not have to wait for the version number to learn which names the freeze covers. The surface is already decided. It is the one the sample apps and both Cefrium browsers use, and the table below states it. If you build against the first three rows, you build against the surface that 1.0 freezes.
What the freeze covers
| Names | What they are | Commitment |
|---|---|---|
In com.cefrium: every type whose name starts with
Cefrium |
The Java SDK. Cefrium for process setup,
CefriumBrowser for the engine, CefriumSurfaceContainer
for the view, the Cefrium*Handler interfaces you implement, and
every listener and callback type nested inside them. |
Frozen at 1.0 |
com.cefrium.compose, the whole package |
The Compose API. CefriumView, CefriumWebView,
CefriumViewState, CefriumNavigator,
CefriumBrowserPool and their remember* functions. |
Frozen at 1.0 |
The Gradle plugin id com.cefrium |
Applying the plugin is the whole contract. The plugin takes no configuration block, so there is nothing else to hold stable. | Frozen at 1.0 |
CefriumBrowser.executeDevToolsMethod,
setDevToolsEventListener,
evaluateJavaScript with a callback,
Cefrium.setRemoteDebuggingEnabled,
Cefrium.setDrmPreprovisioningAtStartupEnabled |
Added in 0.18.0. Their javadoc says Experimental. | May change before 1.0; frozen at 1.0 unless removed. |
PopupHandler.onCreateWindow, onCloseWindow,
CefriumBrowser.setIdentityHandler,
CefriumIdentityHandler |
Added in 0.19.0. Their javadoc says Experimental. | May change before 1.0; frozen at 1.0 unless removed. |
In com.cefrium: types whose name starts with
Cef but not Cefrium, and
CefriumMediaSession |
Glue that the engine calls into, such as CefWindowAndroid
and CefModalDialogPresenter. These types are public because
Chromium instantiates them from another package. Their parameters are
Chromium types, and none of them has a public constructor you can use. |
Not API. Either name can change in any release. |
com.cefrium.payments,
com.cefrium.webauthn |
Registrars that the engine instantiates for Payment Request and WebAuthn. A page gets both features by loading, so an app never calls these. | Not API. Either package can change in any release. |
org.chromium.*, org.jni_zero.*,
gen.* |
Chromium's own Java classes. They ship inside the AAR because the engine needs them. Upstream renames and deletes them between branches. | Never API. Do not import them. |
The short rule: a type name that starts with Cefrium is API,
with the single exception of CefriumMediaSession. The
reference documentation lists every symbol.
No Chromium type reaches you today. Across the stable
surface, in both the Java SDK and the Compose API, no public method takes or
returns an org.chromium.* type. Your code compiles against
Android and Java types only. The freeze keeps it that way, which is what
protects you from an upstream rename.
We do not publish a date for 1.0. The gate is the list above plus reliability across real devices, and a date would be a guess.
From 1.0
- Major releases are the only ones that may remove or change frozen API, and only API whose deprecation period has passed.
- Minor releases add API, may deprecate API and may move to a new engine branch. They never remove frozen API or change what it does.
- Patch releases carry fixes, security fixes and engine updates within the same engine branch. No API change.
Deprecated API is marked @Deprecated, names its replacement,
keeps working for at least 12 months, and goes only in a major release. One
exception: when Chromium removes the capability underneath, as it did with Web
SQL, the API stops working with the engine release that removes it, and the
changelog says so as soon as we know. API whose javadoc says Experimental is
not covered.
Updates and security
Cefrium follows the Chromium engine. A security fix reaches you through an engine update in a new Cefrium release. Public releases do not backport fixes to older Cefrium versions; the Fleet plan has a long-term engine branch. Plan for the engine update, and read the policy page for the current cadence.
maven.cefrium.com keeps the last ten releases, so a pinned
version keeps resolving for a while; still, move to each new release, since
only the current one gets security fixes; the releases page says what
changed.
If a coding agent writes your integration
A coding agent reads the instruction file in your repository
(AGENTS.md, or CLAUDE.md for Claude Code), not
ours. Paste this into yours so it uses the public API and avoids the
integration mistakes we see most. The same block, as a file:
cefrium.com/agents.md. A summary of the docs for
tools is at cefrium.com/llms.txt.
## Cefrium (embedded Chromium, com.cefrium:*)
- Public API only: com.cefrium.* (reference: https://cefrium.com/docs/).
Never call org.chromium.*, org.jni_zero.* or GEN_JNI, and no reflection
on the engine: it breaks on every engine update. Internals -> public
calls: https://cefrium.com/guides/public-api/
- Toolchain: JDK 25, Gradle 9.7.1, AGP 9.4, compileSdk 37, minSdk 29.
ABIs arm64-v8a, armeabi-v7a, x86_64. Apply the com.cefrium Gradle
plugin; its version equals the SDK version.
- Repository: https://maven.cefrium.com with
content { includeGroup("com.cefrium") }. The -sources.jar there is the
source of truth for each version.
- Your Application class also runs in the engine's isolated child
processes (renderer, GPU, utility). They cannot open your files or
preferences, so main-process work there kills the engine and no page
renders, not even a local one. First line of Application.onCreate():
if (!getPackageName().equals(Application.getProcessName())) return;
Sample: https://codeberg.org/cefrium/cefrium-sample/src/branch/main/child-processes
- R8: the SDK ships its own keep rules. Do not add keeps for engine
classes. A crash only in the minified build is a bug to report.
- Page <-> app bridge: window.cefriumQuery reaches a QueryHandler, which
must answer synchronously from onQuery; one handler per browser. To
push events to the page, call evaluateJavaScript from the app instead
of polling from the page.
- evaluateJavaScript(script, ValueCallback<String>) returns the script's
value as JSON. DevTools protocol in process: executeDevToolsMethod.
- Off-screen browser: input via sendMouse*/sendKeyEvent/sendTouchEvent,
resize via setSize (do not recreate the browser).
- android.webkit.WebView and Cefrium share a process in either order
since 0.18.0.
- Test on a real device before release. An emulator without KVM, or CI
that only compiles, cannot show that pages render.
- Bugs: https://codeberg.org/cefrium/cef-android/issues
Still a fit?
If Android 10 and newer covers your users, and your build runs on JDK 25, then nothing above blocks you. Go to the quickstart. It takes one dependency line and one plugin line.
If one of the three permanent constraints rules you out, tell us which one at cefrium@proton.me. We would rather know that than guess.