Injecting a Script into a Webpage

Inject a script that you've written from a Safari App Extension into a webpage.


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.

  1. Add the script files to your extension’s Xcode target.

  2. Add an SFSafariContentScript key to the NSExtension element in your extension’s Info.plist file. The value for this key is an array of dictionaries.

  3. 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.

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.plist 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.extension.baseURI 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.body is null. To take action after the document has been loaded, listen for the DOMContentLoaded 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";

See Also

Injecting Scripts and Style Sheets

About Injected Style Sheets and Scripts

Learn how you can affect the appearance or behavior of a webpage by using injected style sheets and scripts.

Injecting CSS Style Sheets into a Webpage

Add to or override styles by injecting CSS style sheets into webpages.

Passing Messages Between Safari App Extensions and Injected Scripts

Pass data back and forth between Safari App Extension and injected scripts.

class SFSafariExtensionHandler

A base class that you subclass to handle events in your Safari app extension.

class SFSafariExtensionManager

A class used by your app to find out the current state of a Safari app extension.

class SFSafariExtensionState

The state of a Safari app extension.

class SFSafariPageProperties

Information about a webpage.

protocol SFSafariExtensionHandling

A protocol used to implement event handling in a Safari app extension.