Categories
content-script google-chrome google-chrome-extension javascript youtube-api

Use a content script to access the page context variables and functions

570

I’m learning how to create Chrome extensions. I just started developing one to catch YouTube events. I want to use it with YouTube flash player (later I will try to make it compatible with HTML5).

manifest.json:

{
    "name": "MyExtension",
    "version": "1.0",
    "description": "Gotta catch Youtube events!",
    "permissions": ["tabs", "http://*/*"],
    "content_scripts" : [{
        "matches" : [ "www.youtube.com/*"],
        "js" : ["myScript.js"]
    }]
}

myScript.js:

function state() { console.log("State Changed!"); }
var player = document.getElementById("movie_player");
player.addEventListener("onStateChange", "state");
console.log("Started!");

The problem is that the console gives me the “Started!”, but there is no “State Changed!” when I play/pause YouTube videos.

When this code is put in the console, it worked. What am I doing wrong?

3

1092

Underlying cause:
Content scripts are executed in an “isolated world” environment.

Solution:
Inject the code into the page using DOM – that code will be able to access functions/variables of the page context (“main world”) or expose functions/variables to the page context (in your case it’s the state() method).

  • Note in case communication with the page script is needed:
    Use DOM CustomEvent handler. Examples: one, two, and three.

  • Note in case chrome API is needed in the page script:
    Since chrome.* APIs can’t be used in the page script, you have to use them in the content script and send the results to the page script via DOM messaging (see the note above).

Safety warning:
A page may redefine or augment/hook a built-in prototype so your exposed code may fail if the page did it in an incompatible fashion. If you want to make sure your exposed code runs in a safe environment then you should either a) declare your content script with “run_at”: “document_start” and use Methods 2-3 not 1, or b) extract the original native built-ins via an empty iframe, example. Note that with document_start you may need to use DOMContentLoaded event inside the exposed code to wait for DOM.

Table of contents

  • Method 1: Inject another file – ManifestV3 compatible
  • Method 2: Inject embedded code – MV2
  • Method 2b: Using a function – MV2
  • Method 3: Using an inline event – ManifestV3 compatible
  • Method 4: Using executeScript’s world – ManifestV3 only
  • Dynamic values in the injected code

Method 1: Inject another file (ManifestV3/MV2)

Particularly good when you have lots of code. Put the code in a file within your extension, say script.js. Then load it in your content script like this:

var s = document.createElement('script');
s.src = chrome.runtime.getURL('script.js');
s.onload = function() {
    this.remove();
};
(document.head || document.documentElement).appendChild(s);

The js file must be exposed in web_accessible_resources:

  • manifest.json example for ManifestV2

    "web_accessible_resources": ["script.js"],
    
  • manifest.json example for ManifestV3

    "web_accessible_resources": [{
      "resources": ["script.js"],
      "matches": ["<all_urls>"]
    }]
    

If not, the following error will appear in the console:

Denying load of chrome-extension://[EXTENSIONID]/script.js. Resources must be listed in the web_accessible_resources manifest key in order to be loaded by pages outside the extension.

Method 2: Inject embedded code (MV2)

This method is useful when you want to quickly run a small piece of code. (See also: How to disable facebook hotkeys with Chrome extension?).

var actualCode = `// Code here.
// If you want to use a variable, use $ and curly braces.
// For example, to use a fixed random number:
var someFixedRandomValue = ${ Math.random() };
// NOTE: Do not insert unsafe variables in this way, see below
// at "Dynamic values in the injected code"
`;

var script = document.createElement('script');
script.textContent = actualCode;
(document.head||document.documentElement).appendChild(script);
script.remove();

Note: template literals are only supported in Chrome 41 and above. If you want the extension to work in Chrome 40-, use:

var actualCode = ['/* Code here. Example: */' + 'alert(0);',
                  '// Beware! This array have to be joined',
                  '// using a newline. Otherwise, missing semicolons',
                  '// or single-line comments (//) will mess up your',
                  '// code ----->'].join('\n');

Method 2b: Using a function (MV2)

For a big chunk of code, quoting the string is not feasible. Instead of using an array, a function can be used, and stringified:

var actualCode="(" + function() {
    // All code is executed in a local scope.
    // For example, the following does NOT overwrite the global `alert` method
    var alert = null;
    // To overwrite a global variable, prefix `window`:
    window.alert = null;
} + ')();';
var script = document.createElement('script');
script.textContent = actualCode;
(document.head||document.documentElement).appendChild(script);
script.remove();

This method works, because the + operator on strings and a function converts all objects to a string. If you intend on using the code more than once, it’s wise to create a function to avoid code repetition. An implementation might look like:

function injectScript(func) {
    var actualCode="(" + func + ')();'
    ...
}
injectScript(function() {
   alert("Injected script");
});

Note: Since the function is serialized, the original scope, and all bound properties are lost!

var scriptToInject = function() {
    console.log(typeof scriptToInject);
};
injectScript(scriptToInject);
// Console output:  "undefined"

Method 3: Using an inline event (ManifestV3/MV2)

Sometimes, you want to run some code immediately, e.g. to run some code before the <head> element is created. This can be done by inserting a <script> tag with textContent (see method 2/2b).

An alternative, but not recommended is to use inline events. It is not recommended because if the page defines a Content Security policy that forbids inline scripts, then inline event listeners are blocked. Inline scripts injected by the extension, on the other hand, still run.
If you still want to use inline events, this is how:

var actualCode="// Some code example \n" + 
                 'console.log(document.documentElement.outerHTML);';

document.documentElement.setAttribute('onreset', actualCode);
document.documentElement.dispatchEvent(new CustomEvent('reset'));
document.documentElement.removeAttribute('onreset');

Note: This method assumes that there are no other global event listeners that handle the reset event. If there is, you can also pick one of the other global events. Just open the JavaScript console (F12), type document.documentElement.on, and pick on of the available events.

Method 4: Using chrome.scripting API world (ManifestV3 only)

  • Chrome 95 or newer, chrome.scripting.executeScript with world: 'MAIN'
  • Chrome 102 or newer, chrome.scripting.registerContentScripts with world: 'MAIN', also allows runAt: 'document_start' to guarantee early execution of the page script.

Unlike the other methods, this one is for the background script or the popup script, not for the content script. See the documentation and examples.

Dynamic values in the injected code (MV2)

Occasionally, you need to pass an arbitrary variable to the injected function. For example:

var GREETING = "Hi, I'm ";
var NAME = "Rob";
var scriptToInject = function() {
    alert(GREETING + NAME);
};

To inject this code, you need to pass the variables as arguments to the anonymous function. Be sure to implement it correctly! The following will not work:

var scriptToInject = function (GREETING, NAME) { ... };
var actualCode="(" + scriptToInject + ')(' + GREETING + ',' + NAME + ')';
// The previous will work for numbers and booleans, but not strings.
// To see why, have a look at the resulting string:
var actualCode = "(function(GREETING, NAME) {...})(Hi, I'm ,Rob)";
//                                                 ^^^^^^^^ ^^^ No string literals!

The solution is to use JSON.stringify before passing the argument. Example:

var actualCode="(" + function(greeting, name) { ...
} + ')(' + JSON.stringify(GREETING) + ',' + JSON.stringify(NAME) + ')';

If you have many variables, it’s worthwhile to use JSON.stringify once, to improve readability, as follows:

...
} + ')(' + JSON.stringify([arg1, arg2, arg3, arg4]).slice(1, -1) + ')';

Dynamic values in the injected code (ManifestV3)

  • Method 1 can set the URL of the script element in the content script:

    s.src = chrome.runtime.getURL('script.js?') + new URLSearchParams({foo: 1});
    

    Then script.js can read it:

    const params = new URLSearchParams(document.currentScript.src.split('?')[1]);
    console.log(params.get('foo'));
    
  • Method 4 executeScript has args parameter, registerContentScripts currently doesn’t (hopefully it’ll be added in the future).

55

  • 113

    This answer should be part of official docs. Official docs should ship with recommended way –> 3 ways to do the same thing… Wrong?

    Jun 9, 2013 at 11:17

  • 4

    Usually method 1 is better wherever possible, due to Chrome’s CSP (content security policy) restrictions for some extensions.

    Aug 2, 2013 at 2:33


  • 13

    @Qantas94Heavy The extension’s CSP does not affect content scripts. Only the page’s CSP is relevant. Method 1 can be blocked by using a script-src directive that excludes the extension’s origin, method 2 can be blocked by using a CSP that excludes “unsafe-inline”`.

    – Rob W

    Aug 2, 2013 at 7:24


  • 6

    Someone asked why I remove the script tag using script.parentNode.removeChild(script);. My reason for doing it is because I like to clean up my mess. When an inline script is inserted in the document, it’s immediately executed and the <script> tag can safely be removed.

    – Rob W

    Aug 29, 2013 at 13:35

  • 9

    Other method: use location.href = "javascript: alert('yeah')"; anywhere in your content script. It’s easier for short snippets of code, and can also access the page’s JS objects.

    – Métoule

    Sep 26, 2013 at 21:08


93

The only thing missing hidden from Rob W’s excellent answer is how to communicate between the injected page script and the content script.

On the receiving side (either your content script or the injected page script) add an event listener:

document.addEventListener('yourCustomEvent', function (e) {
  var data = e.detail;
  console.log('received', data);
});

On the initiator side (content script or injected page script) send the event:

var data = {
  allowedTypes: 'those supported by structured cloning, see the list below',
  inShort: 'no DOM elements or classes/functions',
};

document.dispatchEvent(new CustomEvent('yourCustomEvent', { detail: data }));

Notes:

  • DOM messaging uses structured cloning algorithm, which can transfer only some types of data in addition to primitive values. It can’t send class instances or functions or DOM elements.
  • In Firefox, to send an object (i.e. not a primitive value) from the content script to the page context you have to explicitly clone it into the target using cloneInto (a built-in function), otherwise it’ll fail with a security violation error.

    document.dispatchEvent(new CustomEvent('yourCustomEvent', {
      detail: cloneInto(data, document.defaultView),
    }));
    

8

  • 1

    I’ve actually linked to the code and explanation at the second line of my answer, to stackoverflow.com/questions/9602022/….

    – Rob W

    Oct 11, 2013 at 9:00

  • 1

    Do you have a reference for your updated method (e.g. a bug report or a test case?) The CustomEvent constructor supersedes the deprecated document.createEvent API.

    – Rob W

    Nov 6, 2013 at 16:23

  • For me ‘dispatchEvent(new CustomEvent…’ worked. I have Chrome 33. Also it didn’t work before because I wrote the addEventListener after injecting the js code.

    – jscripter

    Mar 10, 2014 at 9:15


  • 1

    I think the official way is to use window.postMessage: developer.chrome.com/extensions/…

    – Enrique

    Dec 15, 2018 at 13:08

  • 2

    how to send response back from content script to initiator script

    – Vinay

    Sep 16, 2019 at 7:41

8

I’ve also faced the problem of ordering of loaded scripts, which was solved through sequential loading of scripts. The loading is based on Rob W’s answer.

function scriptFromFile(file) {
    var script = document.createElement("script");
    script.src = chrome.extension.getURL(file);
    return script;
}

function scriptFromSource(source) {
    var script = document.createElement("script");
    script.textContent = source;
    return script;
}

function inject(scripts) {
    if (scripts.length === 0)
        return;
    var otherScripts = scripts.slice(1);
    var script = scripts[0];
    var onload = function() {
        script.parentNode.removeChild(script);
        inject(otherScripts);
    };
    if (script.src != "") {
        script.onload = onload;
        document.head.appendChild(script);
    } else {
        document.head.appendChild(script);
        onload();
    }
}

The example of usage would be:

var formulaImageUrl = chrome.extension.getURL("formula.png");
var codeImageUrl = chrome.extension.getURL("code.png");

inject([
    scriptFromSource("var formulaImageUrl="" + formulaImageUrl + "";"),
    scriptFromSource("var codeImageUrl="" + codeImageUrl + "";"),
    scriptFromFile("EqEditor/eq_editor-lite-17.js"),
    scriptFromFile("EqEditor/eq_config.js"),
    scriptFromFile("highlight/highlight.pack.js"),
    scriptFromFile("injected.js")
]);

Actually, I’m kinda new to JS, so feel free to ping me to the better ways.

7

  • 3

    This way of inserting scripts is not nice, because you’re polluting the namespace of the web page. If the web page uses a variable called formulaImageUrl or codeImageUrl, then you’re effectively destroying the functionality of the page. If you want to pass a variable to the web page, I suggest to attach the data to the script element (e.g. script.dataset.formulaImageUrl = formulaImageUrl;) and use e.g. (function() { var dataset = document.currentScript.dataset; alert(dataset.formulaImageUrl;) })(); in the script to access the data.

    – Rob W

    May 17, 2015 at 17:27

  • @RobW thank you for your note, although it’s more about the sample. Can you please clarify, why I should use IIFE instead of just getting dataset?

    May 17, 2015 at 17:36

  • 4

    document.currentScript only points to the script tag while it is executing. If you ever want to access the script tag and/or its attributes/properties (e.g. dataset), then you need to store it in a variable. We need an IIFE to get a closure to store this variable without polluting the global namespace.

    – Rob W

    May 17, 2015 at 17:38


  • @RobW excellent! But can’t we just use some variable name, which would hardly intersect with the existing. Is it just non-idiomatic or we can have some other problems with it?

    May 17, 2015 at 17:51

  • 2

    You could, but the cost of using an IIFE is negligible, so I don’t see a reason to prefer namespace pollution over an IIFE. I value the certainly that I won’t break the web page of others in some way, and the ability to use short variable names. Another advantage of using an IIFE is that you can exit the script earlier if wanted (return;).

    – Rob W

    May 17, 2015 at 17:58