An object that controls and manages the behavior of interactive web content.
A ``WebPage`` is an ``Observable`` type, which you use to access various properties of web content
and track changes to them. Use ``WebPage`` to interact with web content, like evaluating JavaScript
or converting the page to PDF data. The following example shows you how you can combine these
capabilities to get specific metadata from an ephemeral page with a custom user agent:
```swift
func fetchMetadata(for url: URL) async throws -> (title: String, description: String) {
let botAgent = """
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/601.2.4 (KHTML, like Gecko) Version/9.0.1 Safari/601.2.4 facebookexternalhit/1.1 Facebot Twitterbot/1.0
"""
var configuration = WebPage.Configuration()
configuration.loadsSubresources = false
configuration.defaultNavigationPreferences.allowsContentJavaScript = false
configuration.websiteDataStore = .nonPersistent()
// Set up the configured page.
let page = WebPage(configuration: configuration)
page.customUserAgent = botAgent
// Load the request and wait for navigation to complete.
let request = URLRequest(url: url)
for try await event in page.load(request) {
// Optionally do something with `event`.
}
// At this point, the navigation is complete.
// Now, use JavaScript to query the appropriate properties of the page.
let fetchOpenGraphProperty = """
const propertyValues = document.querySelectorAll(`meta[property="${property}"]`);
return propertyValues[0];
"""
let javaScriptResult = try await page.callJavaScript(fetchOpenGraphProperty, arguments: arguments)
guard let description = javaScriptResult as? String else {
// Handle failure, like throwing an error.
}
guard let title = page.title else {
// Handle failure, like throwing an error.
}
return (title, description)
}
```
Use ``WebPage`` to programmatically navigate to various types of resources like URL requests,
HTML strings, and data. Optionally, you can observe these navigations through the async sequence
returned by their associated loading functions, and you can customize them by using a type that
conforms to the ``WebPage/NavigationDeciding`` protocol. You can also use the ``WebPage/backForwardList``
property to observe changes to people’s navigation history, and to programmatically navigate to a
specific back-forward list item.
``WebPage`` also conforms to the ``Transferable`` protocol. You can use this conformance to export the
page to various different types of content, like PDF, web archive data, and other types. For customization
of PDF or image export, use ``WebPage/exported(as:)``.
Members (37)
get · iOS 26.0+
navigations
TypeScript
get navigations(): Promise<SDKHandle>
Swift declaration
@MainActor final var navigations: some AsyncSequence<WebPage.NavigationEvent, any Error> { get }
A sequence of all the navigation events that occur throughout the webpage, including both user navigation
and programmatic navigation.
A specific navigation is comprised of a sequential set of ``NavigationEvent``s; a new navigation begins when an
event is ``NavigationEvent/startedProvisionalNavigation``.
This property produces a new sequence each time it is called, and starts tracking events as soon as it is created.
The sequence is indefinite, but may be terminated under several circumstances:
* The owning ``WebPage``'s lifetime ends.
* An error occurs during navigation, at which point the sequence will throw the error and terminate.
* The ``Task`` enclosing iteration of the sequence is cancelled.
To track a specific programmatic navigation, use the return value of one of the loading APIs.
get · iOS 26.0+
serverTrust
TypeScript
get serverTrust(): Promise<(_Security_SecTrust) | null>
Swift declaration
@MainActor final var serverTrust: SecTrust? { get }
The trust management object you use to evaluate trust for the current webpage.
Use the object in this property to validate the webpage’s certificate and associated credentials.
See <doc://com.apple.documentation/documentation/security/evaluating-a-trust-and-parsing-the-result>
for more details on how to use the trust.
Create a new WebPage.
- Parameter configuration: A ``WebPage/Configuration`` value to use when initializing the page.
get · iOS 26.0+
isInspectable
TypeScript
get isInspectable(): Promise<boolean>
Swift declaration
@MainActor final var isInspectable: Bool { get set }
Indicates whether you can inspect the page with Safari Web Inspector.
Set to `true` at any point in the page's lifetime to allow Safari Web Inspector access to inspect the view’s content.
Then, select your view in Safari’s Develop menu for either your computer or an attached device to inspect it.
If you set this value to false during inspection, the system immediately closes Safari Web Inspector and does not
provide any further information about the web content.
The default value of this property is `false`.
set · iOS 26.0+
isInspectable
TypeScript
setIsInspectable(value: boolean): Promise<void>
Swift declaration
@MainActor final var isInspectable: Bool { get set }
Indicates whether you can inspect the page with Safari Web Inspector.
Set to `true` at any point in the page's lifetime to allow Safari Web Inspector access to inspect the view’s content.
Then, select your view in Safari’s Develop menu for either your computer or an attached device to inspect it.
If you set this value to false during inspection, the system immediately closes Safari Web Inspector and does not
provide any further information about the web content.
The default value of this property is `false`.
Executes the specified string as an async JavaScript function.
Don’t format the string in the functionBody parameter as a function-like callable object, as you would in pure
JavaScript. Instead, put only the body of the function in the string. For example, the following string shows a valid function body that takes x, y, and z arguments and returns a result.
```javascript
return x ? y : z;
```
If your JavaScript code returns an object with a callable then property, WebKit calls that property on
the resulting object and waits for its resolution. If resolution succeeds, WebKit returns the resulting
object. If resolution fails, WebKit throws a `WKErrorJavaScriptAsyncFunctionResultRejected` error. If the
garbage collector reclaims the object before resolution finishes, WebKit throws a `WKErrorJavaScriptAsyncFunctionResultUnreachable` error.
Because this method calls your JavaScript code asynchronously, you can call `await` on objects with a
`then` property inside your function body. The following code example illustrates this technique.
```javascript
var p = new Promise(function (f) {
window.setTimeout("f(42)", 1000);
});
await p;
return p;
```
- Parameters:
- functionBody: The JavaScript string to use as the function body. This method treats the string as an anonymous
JavaScript function body and calls it with the named arguments in the `arguments` parameter.
- arguments: A dictionary of the arguments to pass to the function call. Each key in the dictionary corresponds
to the name of an argument in the `functionBody` string, and the value of that key is the value to use during
the evaluation of the code. Supported value types are `Numeric`, `String`, `Date`, and arrays, dictionaries,
and optional values of those types.
- frame: The frame in which to evaluate the JavaScript code. Specify `nil` to target the main frame. If this
frame is no longer valid when script evaluation begins, this function throws an error with the
`WKError.Code.javaScriptInvalidFrameTarget` code.
- contentWorld: The namespace in which to evaluate the JavaScript code. This parameter doesn't apply to changes
you make in the underlying web content, such as the document's DOM structure. Those changes remain visible to
all scripts, regardless of which content world you specify. For more information about content worlds, see `WKContentWorld`.
- Returns: The result of the script evaluation. If your function body doesn't return an explicit value, `nil` is returned. If your function body explicitly returns `null`, then `NSNull` is returned.
- Throws: An error if a problem occurred while evaluating the JavaScript.
get · iOS 26.0+
backForwardList
TypeScript
get backForwardList(): Promise<WebPage_BackForwardList>
Swift declaration
@MainActor final var backForwardList: WebPage.BackForwardList { get }
The webpage's back-forward list.
get · iOS 26.0+
customUserAgent
TypeScript
get customUserAgent(): Promise<(string) | null>
Swift declaration
@MainActor final var customUserAgent: String? { get set }
The custom user agent string.
Use this property to specify a custom user agent string for the webpage.
The default value of this property is `nil`.
@MainActor final var customUserAgent: String? { get set }
The custom user agent string.
Use this property to specify a custom user agent string for the webpage.
The default value of this property is `nil`.
get · iOS 26.0+
fullscreenState
TypeScript
get fullscreenState(): Promise<WebPage_FullscreenState>
Swift declaration
@MainActor final var fullscreenState: WebPage.FullscreenState { get }
The fullscreen state the page is currently in.
get · iOS 26.0+
estimatedProgress
TypeScript
get estimatedProgress(): Promise<number>
Swift declaration
@MainActor final var estimatedProgress: Double { get }
An estimate of completion percentage of the current navigation.
The value ranges from `0.0` to `1.0` based on the total number of bytes received, including the main
document and all of its potential subresources. After navigation loading completes, the `estimatedProgress`
value remains at `1.0` until a new navigation starts, at which point the `estimatedProgress` value resets
to `0.0`.
get · iOS 26.0+
cameraCaptureState
TypeScript
get cameraCaptureState(): Promise<WKMediaCaptureState>
Swift declaration
@MainActor final var cameraCaptureState: WKMediaCaptureState { get }
Indicates whether the webpage is using the camera to capture images or video.
@MainActor final func setAllMediaPlaybackSuspended(_ suspended: Bool) async
Changes whether the webpage is suspending playback of all media in the page.
- Parameter suspended: Indicates whether the webpage should suspend media playback.
get · iOS 26.0+
url
TypeScript
get url(): Promise<(string) | null>
Swift declaration
@MainActor final var url: URL? { get }
The URL for the current webpage.
This property contains the URL for the webpage currently being presented. Use this URL in places
where you reflect the webpage address in your app’s user interface. If the webpage has not loaded
any content yet, this value will be `nil`.
@discardableResult @MainActor final func load(simulatedRequest request: URLRequest, responseHTML htmlString: String) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the web content from the HTML you provide as if the HTML were the response to the request.
- Parameters:
- request: A URL request that specifies the base URL and other loading details the system uses to interpret the HTML you provide.
- htmlString: The HTML code you provide in a string to use as the contents of the webpage.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(simulatedRequest request: URLRequest, response: URLResponse, responseData: Data) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the web content from the data you provide as if the data were the response to the request.
- Parameters:
- request: A URL request that specifies the base URL and other loading details the system uses to interpret the data you provide.
- response: A response the system uses to interpret the data you provide.
- responseData: The data to use as the contents of the webpage.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(html: String, baseURL: URL = Foundation.URL(string: "about:blank")!) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the contents of the specified HTML string and navigates to it.
Use this method to navigate to a webpage that you loaded or created yourself. For example, you might use
this method to load HTML content that your app generates programmatically.
This method sets the source of this load request for app activity data to NSURLRequest.Attribution.developer.
- Parameters:
- html: The string to use as the contents of the webpage.
- baseURL: The base URL to use when the system resolves relative URLs within the HTML string. By default, this is `about:blank`.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(_ data: Data, mimeType: String, characterEncoding: String.Encoding, baseURL: URL) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the content of the specified data object and navigates to it.
Use this method to navigate to a webpage that you loaded yourself and saved in a data object. For example,
if you previously wrote HTML content to a data object, use this method to navigate to that content.
- Parameters:
- data: The data to use as the contents of the webpage.
- mimeType: The MIME type of the information in the data parameter. This parameter must not contain an empty string.
- characterEncoding: The data's character encoding.
- baseURL: A URL that you use to resolve relative URLs within the document.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(_ request: URLRequest) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the web content that the specified URL request object references and navigates to that content.
Use this method to load a page from a local or network-based URL. For example, you might use this method
to navigate to a network-based webpage.
Provide the source of this load request for app activity data by setting the attribution parameter on your request.
- Parameter request: A URL request that specifies the resource to display.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(_ url: URL?) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Loads the web content that the specified URL references and navigates to that content.
Use this method to load a page from a local or network-based URL. For example, you might use this method
to navigate to a network-based webpage.
- Parameter url: The URL to load. If this is `nil`, an error will be immediately thrown from the returned sequence.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
@discardableResult @MainActor final func load(_ item: WebPage.BackForwardList.Item) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Navigates to an item from the back-forward list and sets it as the current item.
- Parameter item: The item to navigate to. The item must be in the webpage's back-forward list.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
get · iOS 26.0+
title
TypeScript
get title(): Promise<string>
Swift declaration
@MainActor final var title: String { get }
The page title.
method · iOS 26.0+
reload
TypeScript
reload(fromOrigin?: boolean): Promise<SDKHandle>
Swift declaration
@discardableResult @MainActor final func reload(fromOrigin: Bool = false) -> some AsyncSequence<WebPage.NavigationEvent, any Error>
Reloads the current webpage.
- Parameter fromOrigin: If `true`, end-to-end revalidation of the content using cache-validating conditionals
is performed, if possible.
- Returns: An async sequence you use to track the loading progress of the navigation. If the `Task` enclosing the sequence is cancelled, the page will stop loading all resources.
nonisolated final func exported(as representation: WebPage.ExportedContentConfiguration) async throws -> Data
Using the type's `Transferable` conformance implementation, exports a value as binary data,
optionally with a specified configuration for that type of data.
For example, you can export a 100 pt by 100 pt region of a webpage as a PDF, and allow it to have a transparent background:
```swift
let page = WebPage()
// Load web content and wait for navigation to complete.
let square = CGRect(x: 0, y: 0, width: 100, height: 100)
let pdf = try await page.exported(as: .pdf(region: .rect(square), allowTransparentBackground: true))
```
If no configuration is needed, use the ``Transferable`` conformance of ``WebPage`` directly:
```swift
let page = WebPage()
// Load web content and wait for navigation to complete.
let pdf = try await page.exported(as: .pdf)
```
- Parameter representation: A configuration for a representation for a specific type of data with optional customizable properties.
- Returns: The data with the specified representation type.
- Throws: An error if the specified representation cannot be created from the page.
get · iOS 26.0+
isLoading
TypeScript
get isLoading(): Promise<boolean>
Swift declaration
@MainActor final var isLoading: Bool { get }
Indicates whether the webpage is currently loading content.
- Returns: `true` if the page is still loading content, otherwise, `false`.
get · iOS 26.0+
mediaType
TypeScript
get mediaType(): Promise<(WebPage_CSSMediaType) | null>
Swift declaration
@MainActor final var mediaType: WebPage.CSSMediaType? { get set }
The media type for the contents of the webpage.
When the value of this property is `nil`, the webpage derives the current media type from the CSS
media property of its content. If you assign a value other than `nil` to this property, the webpage
uses the value you provide instead.
For example, you can use this property to configure a page for viewing as a print preview by setting
it to ``WebPage/CSSMediaType/print``.
The default value of this property is `nil`.
@MainActor final var mediaType: WebPage.CSSMediaType? { get set }
The media type for the contents of the webpage.
When the value of this property is `nil`, the webpage derives the current media type from the CSS
media property of its content. If you assign a value other than `nil` to this property, the webpage
uses the value you provide instead.
For example, you can use this property to configure a page for viewing as a print preview by setting
it to ``WebPage/CSSMediaType/print``.
The default value of this property is `nil`.
Skipped declarations
4 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
WebPage.transferRepresentation
This protocol needs associated types that cannot yet cross the bridge.
