Revision 1071970 of Using the JavaScript APIs

Revision slug: Mozilla/Add-ons/WebExtensions/Using_the_JavaScript_APIs
Revision title: Using the JavaScript APIs
Revision id: 1071970
Created: Jun 16, 2016, 3:42:58 AM
Creator: wbamberg
Is current revision? No
Comment

Revision Content

The WebExtension JavaScript APIs can be used inside the add-on's background scripts and in any browser action or page action popups that the add-on defines. A few of these APIs can also be accessed by an add-on's content scripts (see the list in the content script guide).

To use the more powerful APIs you need to request permission in your add-on's manifest.json.

You can access the APIs using either the chrome namespace or the browser namespace:

function logTabs(tabs) {
  console.log(tabs);
}

chrome.tabs.query({currentWindow: true}, logTabs);

function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({currentWindow: true}, logTabs);

These are equivalent, except:

the browser namespace isn't available in Google Chrome, so if you want to run the same code on Chrome, use chrome
if you use the browser namespace, you can use promises instead of callbacks for asynchronous functions. See Callbacks and promises below.

See the complete list of JavaScript APIs.

Callbacks and promises

Many of the APIs are asynchronous, returning a value via a callback.

If these functions need to communicate an error, they do so by setting {{WebExtAPIRef("extension.lastError")}}. If a function can set lastError, then you need to check it in your callback.

For example, {{WebExtAPIRef("cookies.set()")}} will set lastError if the add-on does not have permission to set the cookie:

function logCookie(c) {
  if (browser.extension.lastError) {
    console.error(browser.extension.lastError);
  } else {
    console.log(c);
  }
}

browser.cookies.set(
  {url: "https://developer.mozilla.org/"},
  logCookie
);

If you use the browser namespace and omit the callback, then these functions will return a Promise. The first argument to Promise.then() will be given the callback's arguments, and the second argument to Promise.then() will be given lastError:

function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

var setCookie = browser.cookies.set(
  {url: "https://developer.mozilla.org/"}
);
setCookie.then(logCookie, logError);

Revision Source

<div>{{AddonSidebar}}</div>

<p>The WebExtension JavaScript APIs can be used inside the add-on's <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a> and in any <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Browser_actions_2">browser action</a> or page action popups that the add-on defines. A few of these APIs can also be accessed by an add-on's <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">content scripts</a> (see the <a href="/en-US/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">list in the content script guide</a>).</p>

<p>To use the more powerful APIs you need to <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions">request permission</a> in your add-on's manifest.json.</p>

<p>You can access the APIs using either the <code>chrome</code> namespace or the <code>browser</code> namespace:</p>

<pre class="brush: js">
function logTabs(tabs) {
  console.log(tabs);
}

chrome.tabs.query({currentWindow: true}, logTabs);
</pre>

<pre class="brush: js">
function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({currentWindow: true}, logTabs);
</pre>

<p>These are equivalent, except:</p>

<ul>
 <li>the <code>browser</code> namespace isn't available in Google Chrome, so if you want to run the same code on Chrome, use <code>chrome</code></li>
 <li>if you use the <code>browser</code> namespace, you can use promises instead of callbacks for asynchronous functions. See <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API#Callbacks_and_promises">Callbacks and promises</a> below.</li>
</ul>

<p>See the <a href="/en-US/Add-ons/WebExtensions/API">complete list of JavaScript APIs</a>.</p>

<h2 id="Callbacks_and_promises">Callbacks and promises</h2>

<p>Many of the APIs are asynchronous, returning a value via a callback.</p>

<p>If these functions need to communicate an error, they do so by setting {{WebExtAPIRef("extension.lastError")}}. If a function can set <code>lastError</code>, then you need to check it in your callback.</p>

<p>For example, {{WebExtAPIRef("cookies.set()")}} will set <code>lastError</code> if the add-on does not have permission to set the cookie:</p>

<pre class="brush: js">
function logCookie(c) {
  if (browser.extension.lastError) {
    console.error(browser.extension.lastError);
  } else {
    console.log(c);
  }
}

browser.cookies.set(
  {url: "https://developer.mozilla.org/"},
  logCookie
);</pre>

<p>If you use the <code>browser</code> namespace and omit the callback, then these functions will return a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>. The first argument to <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then">Promise.then()</a></code> will be given the callback's arguments, and the second argument to <code>Promise.then()</code> will be given <code>lastError</code>:</p>

<pre class="brush: js">
function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

var setCookie = browser.cookies.set(
  {url: "https://developer.mozilla.org/"}
);
setCookie.then(logCookie, logError);</pre>

Revert to this revision