Extend the browsing experience with injected scripts and style sheets for web content, custom buttons in the Safari toolbar, and contextual menu items.
Safari Desktop 9.0+
Legacy Safari Extensions provide a way for you to add features to the Safari browser and extend the browsing experience. These extensions can add custom buttons to the Safari toolbar, create additional bars, add contextual menu items, display content, and inject scripts and style sheets into webpages.
The SafariAppExtensionPage class represents a web content area; an instance of the class is accessible as safari.self. Your extension can listen for events, such as SafariExtensionMessageEvent, using safari.self.addEventListener. See “Registering Event Listeners” in SafariEventTarget.
Instances of the SafariBeforeNavigateEvent class are used to notify listeners when the user navigates to a new page, before the page is loaded. You can use the preventDefault method to prevent the new page from loading.
The SafariBeforeSearchEvent event fires before the Smart Search Field performs a search, allowing you to intercept the query and execute an alternate task. SafariBeforeSearchEvent can be used with SafariBeforeNavigateEvent to determine what the user intends to do in the Smart Search Field.
The SafariContentExtension class represents your extension to scripts running inside the web content; an instance of the class is accessible as safari.extension. Its counterpart class outside of the web content is SafariExtension.
A SafariExtension instance represents your extension outside of the web content; an instance of the class is accessible as safari.extension. The counterpart class to SafariExtension for scripts running within the web content is SafariContentExtension.
A SafariExtensionCompanion object is an app extension for your macOS app that receives and responds to secure messages from your Safari extension. Sending a message to a Safari extension companion is similar to sending a message to an injected script; simply call the dispatchMessage method on the extension companion object. See Communicating with your OS X App for more information on extension companions.
Safari extensions have a global page, represented by the SafariExtensionGlobalPage class. The global page is loaded once when the extension is loaded, but it is never displayed to the user. It can contain resources such as scripts, images, and HTML content.
Instances of the SafariExtensionMessageEvent encapsulate a message being passed. Message passing is the only way to communicate information from inside the web content area to scripts running outside of it, and vice versa.
The SafariExtensionPopover class represents popovers. You use popovers to present information temporarily. The popover content is layered on top of the existing web content in a special type of window.
The SafariExtensionSecureSettings class provides a place for your extension to securely store settings that should persist between sessions. You interact with it in exactly the same way as you interact with the SafariExtensionSettings class.
Instances of the SafariExtensionsSettingsChangeEvent class are used to provide a description of a change made to the extension’s settings. A settings change event is sent when your extension changes a setting as well as when a setting is changed outside your extension (for example, a setting changed in the Safari preferences).
Instances of the SafariExtensionToolbarItem represent items that your extension adds to the Safari toolbar. Users can select which toolbar items are shown by selecting Customize Toolbar in the same way that they can add and remove toolbar items provided by Safari.
The SafariPrivateBrowsing class allows you to determine whether Safari currently has Private Browsing enabled. Private Browsing mode disables the ability for Safari to store cookies, browsing history, search history, caches, and Autofill information. If Private Browsing is enabled, you should make efforts not to track the user’s browsing behavior and respect their decision to browse privately.
Reader is a Safari feature that allows users to read online articles in a continuous, clutter-free view, with no ads or visual distractions. Reader concatenates multipage articles into a single scrolling pane.
Instances of the SafariValidateEvent class encapsulate a validate event. User interface elements such as contextual menu items and toolbar buttons send a validate event when they are about to display. You can prevent the element from displaying by listening for validate events and marking the element as disabled.