BrowserEngineKit
Framework for building web browsers with alternative (non-WebKit) rendering
engines on iOS and iPadOS. Provides process isolation, XPC communication,
capability management, and system integration for browser apps that implement
their own HTML/CSS/JavaScript engine. Examples target Swift 6.4 and current
Apple SDKs.
BrowserEngineKit is a specialized framework. Alternative browser engines are
available only through Apple-approved entitlement profiles and supported-region
device eligibility. EU support applies to eligible users on iOS 17.4+ and
iPadOS 18+; Japan support starts with iOS 26.2 and adds explicit PAC/MIE
security requirements for browser apps. Development and testing can occur
anywhere. The companion frameworks BrowserEngineCore (low-level primitives) and
BrowserKit (eligibility checks, data transfer) support the overall workflow.
Contents
Workflow
- Verify regional eligibility, default-browser requirements, device capability, and approved entitlements before implementation.
- Model the host plus web-content, networking, and rendering extensions and follow the required bootstrap order.
- Create, retain, invalidate, and reconnect extension processes/XPC channels as explicit lifecycle states.
- Request only the capabilities each extension needs and keep JIT, sandbox, media, layer, text, and download responsibilities separated.
- Verify eligible/ineligible devices, process crashes, relaunch, backgrounding, downloads, memory pressure, and security boundaries.
Route by Task
- Read core implementation details for eligibility, entitlements, architecture, process management, capabilities, sandboxing, JIT, and downloads.
- Read extended BrowserEngineKit patterns for text interaction, layer hosting, scroll coordination, bookmarks, content filtering, and XPC recipes.
Core Decisions
- Treat entitlement approval and runtime eligibility as separate gates.
- Launch extensions only from the host and discard process objects after invalidation.
- Apply JIT-related entitlements only to the intended content process.
- Never weaken sandbox boundaries to simplify cross-process communication.
Common Mistakes
DON'T: Skip the bootstrap sequence
// WRONG - content extension has no path to other extensions
let contentProcess = try await WebContentProcess(
bundleIdentifier: nil, onInterruption: {}
)
// Immediately start sending work without connecting to networking/rendering
// CORRECT - broker connections through the host app
let networkEndpoint = try await networkProxy.getEndpoint()
let renderEndpoint = try await renderProxy.getEndpoint()
try await contentProxy.bootstrap(
renderingExtension: renderEndpoint,
networkExtension: networkEndpoint
)
DON'T: Launch extensions from other extensions
// WRONG - extensions cannot launch other extensions
// (inside a WebContentExtension)
let network = try await NetworkingProcess(...)
// CORRECT - only the host app launches extensions
// Host app creates all processes, then brokers connections
DON'T: Use extension process objects after invalidation
// WRONG
contentProcess.invalidate()
let conn = try contentProcess.makeLibXPCConnection() // Error
// CORRECT - create a new process if needed
let newProcess = try await WebContentProcess(
bundleIdentifier: nil, onInterruption: {}
)
DON'T: Apply JIT entitlements to non-content extensions
JIT compilation entitlements (com.apple.security.cs.allow-jit) are valid
only on web content extensions. Adding them to the host app, rendering
extension, or networking extension causes App Store rejection.
DON'T: Hard-code region eligibility
// WRONG
if Locale.current.region?.identifier == "DE" {
useAlternativeEngine()
}
// CORRECT - use the system eligibility API
let eligible = try await BEAvailability.isEligible(for: .webBrowser)
if eligible {
useAlternativeEngine()
}
DON'T: Forget to set UIRequiredDeviceCapabilities
Without web-browser-engine in UIRequiredDeviceCapabilities, users on
unsupported devices can download the app and hit runtime failures.
Review Checklist
References
1---2name: browserenginekit3description: "Build alternative browser engines using BrowserEngineKit. Use when developing a non-WebKit browser engine for iOS/iPadOS in supported regions, managing web content/rendering/networking extension processes, configuring GPU and networking process capabilities, checking alternative-engine device eligibility, or reviewing BrowserEngineKit entitlements and Info.plist setup."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/browserenginekit6---78# BrowserEngineKit910Framework for building web browsers with alternative (non-WebKit) rendering11engines on iOS and iPadOS. Provides process isolation, XPC communication,12capability management, and system integration for browser apps that implement13their own HTML/CSS/JavaScript engine. Examples target Swift 6.4 and current14Apple SDKs.1516BrowserEngineKit is a specialized framework. Alternative browser engines are17available only through Apple-approved entitlement profiles and supported-region18device eligibility. EU support applies to eligible users on iOS 17.4+ and19iPadOS 18+; Japan support starts with iOS 26.2 and adds explicit PAC/MIE20security requirements for browser apps. Development and testing can occur21anywhere. The companion frameworks BrowserEngineCore (low-level primitives) and22BrowserKit (eligibility checks, data transfer) support the overall workflow.2324## Contents2526- [Workflow](#workflow)27- [Route by Task](#route-by-task)28- [Core Decisions](#core-decisions)29- [Common Mistakes](#common-mistakes)30- [Review Checklist](#review-checklist)31- [References](#references)3233## Workflow34351. Verify regional eligibility, default-browser requirements, device capability, and approved entitlements before implementation.362. Model the host plus web-content, networking, and rendering extensions and follow the required bootstrap order.373. Create, retain, invalidate, and reconnect extension processes/XPC channels as explicit lifecycle states.384. Request only the capabilities each extension needs and keep JIT, sandbox, media, layer, text, and download responsibilities separated.395. Verify eligible/ineligible devices, process crashes, relaunch, backgrounding, downloads, memory pressure, and security boundaries.4041## Route by Task4243- Read [core implementation details](references/core-implementation.md) for eligibility, entitlements, architecture, process management, capabilities, sandboxing, JIT, and downloads.44- Read [extended BrowserEngineKit patterns](references/browserenginekit-patterns.md) for text interaction, layer hosting, scroll coordination, bookmarks, content filtering, and XPC recipes.4546## Core Decisions4748- Treat entitlement approval and runtime eligibility as separate gates.49- Launch extensions only from the host and discard process objects after invalidation.50- Apply JIT-related entitlements only to the intended content process.51- Never weaken sandbox boundaries to simplify cross-process communication.5253## Common Mistakes5455### DON'T: Skip the bootstrap sequence5657```swift58// WRONG - content extension has no path to other extensions59let contentProcess = try await WebContentProcess(60 bundleIdentifier: nil, onInterruption: {}61)62// Immediately start sending work without connecting to networking/rendering6364// CORRECT - broker connections through the host app65let networkEndpoint = try await networkProxy.getEndpoint()66let renderEndpoint = try await renderProxy.getEndpoint()67try await contentProxy.bootstrap(68 renderingExtension: renderEndpoint,69 networkExtension: networkEndpoint70)71```7273### DON'T: Launch extensions from other extensions7475```swift76// WRONG - extensions cannot launch other extensions77// (inside a WebContentExtension)78let network = try await NetworkingProcess(...)7980// CORRECT - only the host app launches extensions81// Host app creates all processes, then brokers connections82```8384### DON'T: Use extension process objects after invalidation8586```swift87// WRONG88contentProcess.invalidate()89let conn = try contentProcess.makeLibXPCConnection() // Error9091// CORRECT - create a new process if needed92let newProcess = try await WebContentProcess(93 bundleIdentifier: nil, onInterruption: {}94)95```9697### DON'T: Apply JIT entitlements to non-content extensions9899JIT compilation entitlements (`com.apple.security.cs.allow-jit`) are valid100only on web content extensions. Adding them to the host app, rendering101extension, or networking extension causes App Store rejection.102103### DON'T: Hard-code region eligibility104105```swift106// WRONG107if Locale.current.region?.identifier == "DE" {108 useAlternativeEngine()109}110111// CORRECT - use the system eligibility API112let eligible = try await BEAvailability.isEligible(for: .webBrowser)113if eligible {114 useAlternativeEngine()115}116```117118### DON'T: Forget to set UIRequiredDeviceCapabilities119120Without `web-browser-engine` in `UIRequiredDeviceCapabilities`, users on121unsupported devices can download the app and hit runtime failures.122123## Review Checklist124125- [ ] `com.apple.developer.web-browser-engine.host` entitlement on host app126- [ ] Each extension has its type-specific entitlement127- [ ] `UIRequiredDeviceCapabilities` includes `web-browser-engine`128- [ ] `arm64e` instruction set configured for all iOS device targets129- [ ] `arm64e` is not set for Simulator targets130- [ ] Swift packages built with `iOSPackagesShouldBuildARM64e` workspace setting131- [ ] Extension point identifiers set correctly in each extension's Info.plist132- [ ] Interruption handlers implemented for all process types133- [ ] Bootstrap sequence connects content extension to networking and rendering134- [ ] Capabilities granted before work begins and invalidated when done135- [ ] Visibility propagation interaction added to browser content views136- [ ] Restricted sandbox applied to content extensions after initialization137- [ ] `BEAvailability` used for eligibility checks instead of manual region logic138- [ ] Memory attribution entitlements use the host app bundle ID as their value139- [ ] Download progress reported via `BEDownloadMonitor` for active downloads on iOS 18.2+140- [ ] Memory tagging enabled for Japan distribution on iOS 26.2+ (recommended for EU)141142## References143- Extended patterns (text interaction, layer hosting, scroll views, file bookmarks, XPC communication, content filtering): [references/browserenginekit-patterns.md](references/browserenginekit-patterns.md)144- [BrowserEngineKit framework](https://sosumi.ai/documentation/browserenginekit)145- [Designing your browser architecture](https://sosumi.ai/documentation/browserenginekit/designing-your-browser-architecture)146- [Creating browser extensions in Xcode](https://sosumi.ai/documentation/browserenginekit/creating-browser-extensions-in-xcode)147- [Managing the browser extension life cycle](https://sosumi.ai/documentation/browserenginekit/managing-the-browser-extension-lifecycle)148- [Using XPC to communicate with browser extensions](https://sosumi.ai/documentation/browserenginekit/using-xpc-to-communicate-with-browser-extensions)149- [Web Browser Engine Entitlement](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.web-browser-engine.host)150- [BrowserKit framework](https://sosumi.ai/documentation/browserkit)151- [BrowserEngineCore framework](https://sosumi.ai/documentation/browserenginecore)152- [Sample: Developing a browser app with an alternative engine](https://sosumi.ai/documentation/browserenginekit/developing-a-browser-app-that-uses-an-alternative-browser-engine)153- [Core implementation details](references/core-implementation.md) -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.