Extend the browsing experience with injected scripts and style sheets for web content, custom buttons in the Safari toolbar, and contextual menu items.
SDK
Safari Desktop 9.0+
Overview
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.
Instances of the SafariContentBrowserTabProxy class serve as proxy objects, allowing scripts injected in the web content to communicate with SafariBrowserTab objects and the rest of the extension.
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.
The SafariEvent class is a base class used to encapsulate events. Developers who are familiar with DOM events will notice many similarities in design and behavior.
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.
Instances of the SafariExtensionBar class represent a bar that your extension provides. An extension can add any number of bars to Safari. Adding bars is optional.
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.
Instances of the SafariExtensionContextMenu class represent a contextual menu that is populated by the extension. Safari displays the contents of this menu as part of its contextual menu.
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.
Instances of the SafariWebPageProxy class serve as a proxy objects, allowing objects outside of the web content to communicate with the SafariContentWebPage object.