Inject a script that you've written from a Safari App Extension into a webpage.
Framework
- Safari
Services
Overview
After you've written a script that can read and modify browser content, you need to add it to your Safari App Extension and apply it to webpages, where it can perform the defined actions and change the appearance and behavior of the webpages.
A script can apply to a single webpage, all webpages, or only some webpages—for example, webpages from certain domains. For your script to be injected, you must specify either Some or All website access for your app extension. For details, see Access and Permissions. For more about injected scripts, see About Injected Style Sheets and Scripts.
Add a Script
After specifying website access, add the script to your Safari App Extension.
Add the script files to your extension’s Xcode target.
Add an
SFSafari
key to theContent Script NSExtension
element in your extension’sInfo
file. The value for this key is an array of dictionaries..plist For each script file, add a dictionary to the array. Each dictionary must have a
Script
key whose value specifies the path (relative to the Resources directory of the bundle) to the script file to include.
Note
By default, a script file is always injected, provided that the extension has permission to access the webpage. However, you can specify additional dictionary keys to provide more fine-grained control over whether that script file is injected into the webpage. For more information, see Access and Permissions.
If your app extension specifies multiple scripts to be injected into the webpage, the scripts are executed in the order in which they appear in the Info
file.
Access Resources Within Your App Extension’s Bundle
Resources stored in your app extension’s bundle can be accessed from within your scripts. Create a URL at runtime that references the resource relative to the root of the app extension’s bundle. The safari
property specifies the location of the bundle’s resource directory.
The code snippet below demonstrates how to use this property. This code adds a new image element to the webpage. The image is stored inside the Resources folder and referenced at runtime.
var newElement = document.createElement("img");
newElement.src = safari.extension.baseURI + "myDog.jpeg";
Execute Your Code After the Webpage Loads
The injected scripts are executed before the webpage has been fully loaded, so you can take action as resources are added to the webpage. During that time, document
is null
. To take action after the document has been loaded, listen for the DOMContent
event. The code snippet below registers a document event handler to be called after the content is loaded.
document.addEventListener("DOMContentLoaded", function(event) {
safari.extension.dispatchMessage("Hello World!");
});
Add an Element to the Webpage
The example code snippet below injects a new element into the webpage after the webpage loads. This example uses a resource stored in the bundle and shows how to register the document event handler.
// Create an image and insert it at the top of the body. document.addEventListener("DOMContentLoaded", function(event) {
var newElement = document.createElement("img");
newElement.src = safari.extension.baseURI + "myCat.jpg";
document.body.insertBefore(newElement,
document.body.firstChild);
});