Creating browser extensions in Xcode

Configure your Xcode project to support your alternative browser engine.

Overview

Deliver your web browser as a browser app and a collection of extensions, described in Designing your browser architecture. Create a separate target in your Xcode project for each of the three kinds of extension: web content extension, rendering extension, and networking extension.

Create your Xcode project

Create a new Xcode project for your browser app and extensions:

In Xcode, choose File > New Project.
Select the iOS App template, and click Next.
Give your project a name, and click Next.
Choose a location to save your project, and click Create.

Create extension targets in Xcode

Open your Xcode project, and follow these steps for each of the three extension types:

Select your Xcode project in the Project Navigator.
Click the Add (+) button at the bottom of the targets list.
Select the iOS Generic Extension template, and click Next.
Give the extension a name, and ensure your browser app is chosen for the Embed in Application setting.
Click Finish, then cancel the request to activate the extension target’s scheme.
Select the new target in the Project Editor.
Switch to the Info tab.
Expand the disclosure triangle next to EXAppExtensionAttributes.
Edit the value for EXExtensionPointIdentifier, and enter the appropriate value from the list based on the extension type:

Rendering extension: com.apple.web-browser-engine.rendering
Networking extension: com.apple.web-browser-engine.networking
Content extension: com.apple.web-browser-engine.content

Build for pointer authentication

Browser apps that include alternative browser engines must use the arm64e instruction set for all executables, including the extensions, in order to use the system’s pointer-authentication protection on devices that support it. Build your browser app as a universal binary that also supports the arm64 instruction set to target iPad models that support alternative browser engines and don’t support arm64e instructions.

To configure your Xcode targets to use the arm64e instruction set:

Select the Xcode project in the Project Navigator.
Select your target.
Open the Build Settings Tab.
Click the disclosure button to the left of the Architectures build setting.
Click the Add (+) button that appears when you move the mouse pointer over the Debug build configuration.
Change the SDK in the new row from “Any SDK” to “iOS”.
Enter the value arm64e for the build setting for the iOS SDK.
Repeat steps 5-7 for the Release build configuration.
Repeat steps 2-8 for each target in your browser app project.

Alternatively, if you use Xcode configuration files to manage build settings for your targets, add this line to your configuration file:

ARCHS[sdk=iphoneos*]=arm64e

If your Xcode workspace includes Swift Packages as dependencies for your targets, use workspace settings to build the packages using the arm64e instruction set. In Terminal, run these commands:

% plutil -create xml1 MyWorkspace.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings
% plutil -insert iOSPackagesShouldBuildARM64e -bool YES MyWorkspace.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings

Adopt the correct entitlements

To act as a person’s web browser, your app requires the default-browser entitlement (see Preparing your app to be the default web browser), and the Web Browser Engine Entitlement that enables your app to separate core tasks of an alternative browser engine into dedicated extensions.

Each of your browser app’s extensions need to add the the following entitlements with a value of true:

Rendering extension: com.apple.developer.web-browser-engine.rendering
Network extension: com.apple.developer.web-browser-engine.networking
Content extension: com.apple.developer.web-browser-engine.webcontent

To use the extension entitlements, compile your host app and extensions with the arm64e instruction set.

In Japan, browser apps are required to enable hardware memory tagging (see com.apple.security.hardened-process.checked-allocations). To protect your users, Apple also strongly recommends that browser apps enable memory tagging in the European Union.

In addition, you can optionally add the following entitlements:

To allow JIT compilation of website scripts, your content extension uses the Allow execution of JIT-compiled code entitlement entitlement with a value of true, and Extended Virtual Addressing Entitlement with a value of true. For more information, see Protecting code compiled just in time. You can’t give this entitlement to your browser app, rendering extension, or networking extension.
To transfer memory attribution between extensions, your content extension uses the com.apple.developer.memory.transfer_accept entitlement, and your rendering extension uses the com.apple.developer.memory.transfer_send entitlement, both with the browser apps’ bundle identifier as the value. For more information, see Attributing memory to a content extension.
To restrict access to the system notification service in your web content extension, add the com.apple.developer.web-browser-engine.restrict.notifyd entitlement with the value true. For more information, see Limiting resource access in web content extensions.

For more information on adding entitlements to targets in Xcode, see Entitlements.

Target devices with required capabilities

Add the string web-browser-engine to the UIRequiredDeviceCapabilities array in your target’s properties, to ensure that people can only download your app on devices that support browser apps with alternative browser engines. If your browser app only supports the arm64e instruction set, also add arm64e to UIRequiredDeviceCapabilities.

For more information, see Required Device Capabilities.

Test your web browser

Development of a web browser that uses an alternative browser engine can occur anywhere in the world. Xcode allows running development or Ad-Hoc signed builds of the app on Simulator but device support varies by region:

European Union: Alternative browser engines support iPhone and iPad.
Japan: Alternative browser engines support iPhone.