Access and Permissions
Extensions can have two parts—an app part, consisting of any global page or extension bars, and a content part, consisting of any injected scripts or style sheets. The two parts have different access and permissions.
In addition, there are settings you can specify when building your extension that select the websites your extension can interact with.
The Global HTML Page, Popovers, and Extension Bars
The global HTML page, popovers, and extension bars have access to the
SafariExtension classes. They can work with windows and tabs, extension settings, and add or remove extension items. They can also respond to commands from the Safari toolbar or the contextual menu that appears over a webpage.
The global HTML page, popovers, and extension bars do not have access to the content of webpages, and they can communicate with injected scripts only by sending messages—they cannot access an injected script’s functions or variables directly.
window.open() method. They must use the Safari Extensions API. See The Windows and Tabs API.
Injected Scripts and Style Sheets
Injected scripts have access to the
Injected scripts cannot access the
SafariExtension classes. They cannot respond to command events generated by the Safari toolbar or contextual menus, nor can they access functions or variables defined in the global HTML page or extension bars. They can, however, send messages to the global HTML page and extension bars, and the message data can be an object (such as an array, for example) declared in the injected script.
Injected scripts and style sheets cannot access resources within the extension folder, such as images or other files, using relative URLs. Any relative URL in an injected script or style sheet is interpreted as relative to the webpage. To access resources within the extension folder from an injected script or style sheet, you must use an absolute URL. For details, see Accessing Resources Within Your Extension Folder.
Extension Website Access
You choose the webpages and domains your extension has access to in Extension Builder. Only the websites you choose have web content injected into them, and only those websites can be manipulated using the
tab object’s properties, such as
Use the Extension Website Access field in Extension Builder to restrict your extension’s access to external websites. Your choices are as follows:
None—Your extension cannot access webpages by injecting scripts or style sheets, and most tab properties are undefined.
Some—Your extension can access webpages from a list of domains.
You are prompted for a list of domain patterns. For example:
*character matches any string in the domain. For example:
developer.apple.com, or any host name in the
All—Your extension’s access is not limited by a primary list of domain patterns. Potentially, your extension has access to all domains. Website access can be limited by using a whitelist and blacklist, however. See Whitelists and Blacklists.
If you choose Some or All, you can further choose to allow your extension access to secure sites (HTTPS URLs) or not, as shown in Figure 17-1.
Whitelists and Blacklists
The whitelist and blacklist work in conjunction with the Extension Website Access field. First, access is limited by the Extension Website Access settings, then the whitelist and blacklist are applied.
If there is no whitelist or blacklist, no restrictions are added to your Extension Website Access.
If there is a whitelist, your scripts and styles are applied only to webpages whose URL match an entry on your whitelist.
If there is a blacklist, your scripts and styles are not applied to any webpages whose URL matches a blacklist entry.
Again, note that these restrictions are in addition to those set in the Extension Website Access field. If you specify Some access, for example, you have access only to the domains matching your provided domain patterns. Items in your whitelist and blacklist create additional restrictions within those domains. Be sure all the items in your whitelist are within a domain you have access to.
Add URLs to the whitelist or blacklist by clicking New URL Pattern, as illustrated in Figure 17-2.
A URL pattern takes the form Scheme://Domain/Path.
Scheme can be
Domain is the host domain, such as
Path is the directory or webpage, such as
A URL pattern can include the * character to match any string. This allows you to specify all pages in a particular domain, for example, without having to create an exhaustive list.
The * character can be used anywhere in the domain or path, but not the scheme. Here are some examples:
http://*/*—matches all http URLs.
http://*.apple.com/*—matches all webpages from apple.com.
http://developer.apple.com/*—matches all webpages from developer.apple.com.
https://secure.example.com/accounts/*—matches all webpages from the accounts directory of secure.example.com that are delivered over HTTPS.
http://www.example.com/thepath/thepage.html—matches one webpage