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

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.

Compose API

Dokka for CefriumView, CefriumViewState and CefriumNavigator.

Compose reference ->

SDK API reference

Full Javadoc for CefriumBrowser and the handlers.

Browse the API ->

Push & notifications

Web Notifications out of the box, Web Push, and native FCM -- what works and how to wire it.

Push guide ->

Working examples

cefrium-browser: full browser in View + Compose APIs. cefrium-sample: kiosk demos, the JS bridge, OSR.

cefrium-browser -> · cefrium-sample ->

Release parity

How Cefrium versions track CEF and Chromium upstream.

Releases ->

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/")