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

ConstraintValueCan 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:

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-v8ax86_64armeabi-v7a
libcef.so, uncompressed212 MB239 MB109 MB
Compressed inside the AAR89 MB99 MB61 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 engine36 MB
Engine, on demand89 MB
One app with the engine inside125 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.

PermissionAdded byUsed forWithout 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:

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

NamesWhat they areCommitment
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

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.