Quickstart
From an empty Android project to a CefriumBrowser
rendering a page, using the prebuilt artifacts. No Chromium build required.
1. Prerequisites
Android Studio with the Android SDK, JDK 25,
Gradle 9.7.1, AGP 9.4, and
compileSdk 37. JDK 25 is a hard floor: Chromium 152 and newer
compile their own Java at --release 25, and the AAR carries it.
The com.cefrium Gradle plugin is built for Java 17 and is not the
cause. Before you integrate, read
is Cefrium a fit for your app?.
The SDK targets minSdk 29 and ships native code for
arm64-v8a, armeabi-v7a (32-bit ARM phones) and
x86_64 - build for one of those ABIs (a physical ARM device or an
x86_64 emulator).
Emulator: use an x86_64 or
arm64-v8a system image. On a 32-bit image (x86, offered up to
API 30) Cefrium.initialize() throws an IllegalStateException
that names the ABI. To keep an app off ABIs without an engine, list the supported ones
in ndk { abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86_64' }.
These versions are a hard requirement from 0.8.0 on.
Chromium 152 and later compile their Java with --release 25, so the published
SDK, Compose wrapper, and Gradle plugin contain Java-25 (class-file 69)
bytecode. An older toolchain cannot read or dex them and the build fails with
Unsupported class file major version 69. On AGP 9 use the built-in
Kotlin support (drop org.jetbrains.kotlin.android) and legacy
jniLibs packaging. See the
0.8.0 changelog entry.
The engine's classes.jar is large (~50k classes), so dexing it
needs more than Gradle's default 512 MB heap. Set a 4 GB heap (and keep
AndroidX on, which Android Studio enables for new projects) in
gradle.properties:
# gradle.properties
org.gradle.jvmargs=-Xmx4g
android.useAndroidX=true
2. Add the repository
Cefrium is published on its own Maven repository,
https://maven.cefrium.com. Add it to both blocks below;
includeGroup keeps Gradle from asking it for any other library. New
Android Studio projects use the Kotlin DSL by default; the Groovy form follows.
Pinning a version? The repository keeps the last ten releases
(0.18.0 onwards today). The Codeberg
Maven registry (https://codeberg.org/api/packages/cefrium/maven)
mirrors the current release and the one before it. Older releases stay on the
release page as the
git tag and a signed SHA256SUMS.
Keeping a version longer? Versions up to 0.17.1 also resolve
from mavenCentral(). To keep any version beyond the window, proxy the
repository in your own repository manager (Nexus, Artifactory, Reposilite), as you
would for any third-party dependency.
Staying current? Renovate or Dependabot can open a pull request
when a release comes out. For Renovate, in renovate.json:
{
"packageRules": [
{ "matchPackageNames": ["com.cefrium:*"],
"registryUrls": ["https://maven.cefrium.com"] }
]
}
For Dependabot, in .github/dependabot.yml:
version: 2
registries:
cefrium:
type: maven-repository
url: https://maven.cefrium.com
updates:
- package-ecosystem: gradle
directory: "/"
registries: [cefrium]
schedule:
interval: weekly
Or follow the release feed: RSS / Atom.
Support. Issues are answered as time allows. Cefrium is funded by the people who use it: individuals through Liberapay, and teams through support plans with response times and integration help.
settings.gradle.kts (Kotlin DSL)
pluginManagement {
repositories {
maven("https://maven.cefrium.com") {
content { includeGroup("com.cefrium") }
}
google()
mavenCentral()
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven("https://maven.cefrium.com") {
content { includeGroup("com.cefrium") }
}
}
}
settings.gradle (Groovy)
pluginManagement {
repositories {
maven {
url 'https://maven.cefrium.com'
content { includeGroup 'com.cefrium' }
}
google()
mavenCentral()
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url 'https://maven.cefrium.com'
content { includeGroup 'com.cefrium' }
}
}
}
3. Apply the plugin and dependency
The com.cefrium Gradle plugin generates the R classes for
Chromium's many resource packages in your app, so the bundled engine resolves
its resources at runtime. Add it alongside the SDK dependency in your app module.
app/build.gradle.kts (Kotlin DSL)
plugins {
id("com.android.application")
id("com.cefrium") version "0.21.0"
}
dependencies {
implementation("com.cefrium:cefrium-sdk:0.21.0")
// Compose API (CefriumView + state). A new Empty Activity project already has
// Compose + Material3; omit this line if you only use the View-based CefriumBrowser.
implementation("com.cefrium:cefrium-compose:0.21.0")
// Runtime dependencies the engine expects.
implementation("androidx.appcompat:appcompat:1.7.0")
implementation("androidx.mediarouter:mediarouter:1.7.0")
implementation("androidx.core:core:1.16.0")
implementation("androidx.browser:browser:1.8.0")
}
app/build.gradle (Groovy)
plugins {
id 'com.android.application'
id 'com.cefrium' version '0.21.0'
}
dependencies {
implementation 'com.cefrium:cefrium-sdk:0.21.0'
// Compose API (CefriumView + state). A new Empty Activity project already has
// Compose + Material3; omit this line if you only use the View-based CefriumBrowser.
implementation 'com.cefrium:cefrium-compose:0.21.0'
// Runtime dependencies the engine expects.
implementation 'androidx.appcompat:appcompat:1.7.0'
implementation 'androidx.mediarouter:mediarouter:1.7.0'
implementation 'androidx.core:core:1.16.0'
implementation 'androidx.browser:browser:1.8.0'
}
cefrium-sdk is a single multi-ABI artifact
(arm64-v8a + x86_64); your APK or App Bundle ships only
the device's ABI - the engine's libcef.so is ~203 MB
(uncompressed) for arm64-v8a, so a single-ABI App Bundle download is
a fraction of the 238 MB two-ABI artifact. It includes the full codec set
(H.264, H.265, AAC, VP8, VP9, Opus); a royalty-free cefrium-sdk-libre
variant (VP8, VP9, Opus, Vorbis) is also published. The SDK's manifest contributes
the multi-process service declarations and required permissions through manifest
merging - you do not declare them.
The libraries Chromium uses that are published on Maven (Guava, Material,
Google Play services, Firebase and others) are ordinary dependencies of the SDK,
not copies inside it. If your app uses one of them too, Gradle keeps a single
copy. No exclusions are needed. If you upgrade from 0.11 or earlier, remove any
exclude group: 'com.google.guava' or 'com.squareup.okio'
you added for Cefrium: those libraries now reach the app this way.
4. Show a browser
No initialization code is required - no custom Application, no
Cefrium.initialize() call. The SDK auto-initializes the engine at app
launch (via a ContentProvider it contributes through manifest merging). Your
manifest only declares your own activity:
<!-- AndroidManifest.xml -->
<application ... >
<activity android:name=".MainActivity" android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
The whole app is one composable. rememberCefriumViewState ties the
engine to composition - it loads when shown and is released automatically when it
leaves the screen, so there is no onDestroy cleanup:
// MainActivity.kt
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.cefrium.compose.CefriumView
import com.cefrium.compose.rememberCefriumViewState
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
val state = rememberCefriumViewState("https://cefrium.com/modern-web/")
CefriumView(state, Modifier.fillMaxSize())
}
}
}
Prefer classic Views?
CefriumBrowser.createWithSurface(activity) returns a
surfaceContainer you add to any ViewGroup (call
close() in onDestroy) - see
java-sample
for the Java and Kotlin View variants. Advanced: call
Cefrium.initialize(context) yourself to control init timing - still no
custom Application required.
5. Your first real browser screen
The view's state is observable, so a toolbar with the page title, a loading bar,
and a working system Back button is just reading
state.* and calling the navigator - the screen most first apps start
from:
// BrowserScreen.kt
import androidx.activity.compose.BackHandler
import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.cefrium.compose.CefriumView
import com.cefrium.compose.rememberCefriumNavigator
import com.cefrium.compose.rememberCefriumViewState
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun BrowserScreen() {
val state = rememberCefriumViewState("https://cefrium.com/modern-web/")
val navigator = rememberCefriumNavigator()
// System Back walks the page history until there is nowhere left to go.
BackHandler(enabled = state.canGoBack) { navigator.navigateBack() }
Scaffold(
topBar = {
Column {
TopAppBar(
title = { Text(state.pageTitle ?: "Loading...", maxLines = 1) },
navigationIcon = {
IconButton(onClick = navigator::navigateBack,
enabled = state.canGoBack) {
Icon(Icons.AutoMirrored.Filled.ArrowBack, "Back")
}
},
)
if (state.isLoading) LinearProgressIndicator(Modifier.fillMaxWidth())
}
},
) { padding ->
CefriumView(state, Modifier.fillMaxSize().padding(padding), navigator)
}
}
Edge-to-edge (Android 15+): call
enableEdgeToEdge() in onCreate before
setContent; the Scaffold already insets its content, so
the page draws behind the system bars without overlapping your toolbar.
The same navigator drives the rest of the browser:
navigateForward(), reload(), loadUrl(),
evaluateJavaScript(), cookies, and the SSL / HTTP-auth handlers.
6. Run
Build and install on an arm64-v8a device or x86_64
emulator. The app loads cefrium.com/modern-web - your
first run is a live tour of which web-platform features the bundled engine
supports.
Going further
Common things first apps reach for next - all on the navigator (or
CefriumBrowser for the View path):
- App <-> page messaging -
navigator.evaluateJavaScript(...)and theonQuerybridge onCefriumView(window.cefriumQueryfrom page JS). - Cookies -
setCookie/getCookies/deleteCookies/flushCookies. - Request interception -
setRequestInterceptor(block, redirect, or inspect requests). Ad blocking with EasyList-format lists is separate:Cefrium.loadAdBlockList/downloadAndLoadEasyList. - SSL & HTTP auth -
setSslErrorHandler/setHttpAuthHandler(WebViewonReceivedSslError/onReceivedHttpAuthRequestparity). - Scripts before the page's own -
CefriumBrowser.addDocumentStartJavaScript(script, allowedOriginRules)runs a script in every matching frame before the page's scripts, as the WebView method of the same name (0.16.0). - Permissions, zoom, custom User-Agent, print-to-PDF --
setPermissionHandler,setZoomLevel,setUserAgentOverride,printToPdf.
Web notifications
A page's service worker posts notifications to the Android shade with
ServiceWorkerRegistration.showNotification() (the bare
new Notification() constructor is disabled on Android - use the
service worker). Grant the permission up front for an origin you own, no prompt:
import com.cefrium.CefriumBrowser
val navigator = rememberCefriumNavigator()
// once the page is loading, pre-grant notifications for your origin:
navigator.setContentSetting(
"https://your-app.example",
CefriumBrowser.PERMISSION_NOTIFICATIONS,
CefriumBrowser.SETTING_ALLOW,
)
Prefer to answer the request interactively? Use
setPermissionHandler. Web Push and production native FCM are covered
in the push & notifications guide.
Push & notifications
Web Notifications out of the box, Web Push, and native FCM -- what works and how to wire it.
Working examples
cefrium-browser: full browser in View + Compose APIs. cefrium-sample: kiosk demos, the JS bridge, OSR.
Headless rendering
For screenshots, PDFs, or server-side rendering with no window, construct a browser with a size and density and receive BGRA frames through a render handler:
val browser = CefriumBrowser(1080, 1920, resources.displayMetrics.density)
browser.setRenderHandler { width, height, pixels ->
// `pixels` is a direct ByteBuffer of width*height BGRA bytes.
}
browser.loadUrl("https://cefrium.com/")