Populated with an error message if calling an API function fails;
otherwise undefined. This is only defined within the scope of that
function's callback. If an error is produced, but runtime.lastError is
not accessed within the callback, a message is logged to the console
listing the API function that produced the error. API functions that
return promises do not set this property.
Fired when an app or the device that it runs on needs to be restarted. The
app should close all its windows at its earliest convenient time to let
the restart to happen. If the app does nothing, a restart will be enforced
after a 24-hour grace period has passed. Currently, this event is only
fired for Chrome OS kiosk apps.
Fired when a profile that has this extension installed first starts up.
This event is not fired when an incognito profile is started, even if this
extension is operating in 'split' incognito mode.
Sent to the event page just before it is unloaded. This gives the
extension opportunity to do some clean up. Note that since the page is
unloading, any asynchronous operations started while handling this event
are not guaranteed to complete. If more activity for the event page occurs
before it gets unloaded the onSuspendCanceled event will be sent and the
page won't be unloaded.
Fired when an update is available, but isn't installed immediately because
the app is currently running. If you do nothing, the update will be
installed the next time the background page gets unloaded, if you want it
to be installed sooner you can explicitly call chrome.runtime.reload(). If
your extension is using a persistent background page, the background page
of course never gets unloaded, so unless you call chrome.runtime.reload()
manually in response to this event the update will not get installed until
the next time Chrome itself restarts. If no handlers are listening for
this event, and your extension has a persistent background page, it
behaves as if chrome.runtime.reload() is called in response to this event.
Attempts to connect listeners within an extension (such as the background
page), or other extensions/apps. This is useful for content scripts
connecting to their extension processes, inter-app/extension
communication, and web
messaging. Note that
this does not connect to any listeners in a content script. Extensions may
connect to content scripts embedded in tabs via tabs.connect.
extensionId The ID of the extension to connect to. If omitted, a
connection will be attempted with your own extension. Required if
sending messages from a web page for web
messaging.
returns Port through which messages can be sent and received. The
port's $(ref:Port onDisconnect) event is fired if the extension does not
exist.
Connects to a native application in the host machine. This method requires
the "nativeMessaging" permission. See Native
Messaging for more information.
application The name of the registered application to connect to.
returns Port through which messages can be sent and received with the
application
Retrieves the JavaScript 'window' object for the background page running
inside the current extension/app. If the background page is an event page,
the system will ensure it is loaded before calling the callback. If there
is no background page, an error is set.
Fetches information about active contexts associated with this extension
filter A filter to find matching contexts. A context matches if it
matches all specified fields in the filter. Any unspecified field in the
filter matches all contexts.
returns Promise that resolves with the matching contexts, if any.
Returns details about the app or extension from the manifest. The object
returned is a serialization of the full manifest
file.
returns The manifest details.
Converts a relative path within an app/extension install directory to a
fully-qualified URL.
path A path to a resource within an app/extension expressed relative
to its install directory.
returns The fully-qualified URL to the resource.
Signals that the extension has finished registering its event listeners
for the current service worker instance. The browser replaces persisted
listener registrations with the newly registered listeners and dispatches
any queued events. Only available in the service worker of extensions
declaring "background.async_listener_registration": true.
returns Called once the browser has committed the listener
registration. The promise is rejected if the extension is not opted in,
the caller is not the service worker, or no listener registration is in
progress.
Requests an immediate update check be done for this app/extension.
Important: Most extensions/apps should not use this method, since
Chrome already does automatic checks every few hours, and you can listen
for the runtime.onUpdateAvailable event without needing to call
requestUpdateCheck.
Restart the ChromeOS device when the app runs in kiosk mode after the
given seconds. If called again before the time ends, the reboot will be
delayed. If called with a value of -1, the reboot will be cancelled. It's
a no-op in non-kiosk mode. It's only allowed to be called repeatedly by
the first extension to invoke this API.
seconds Time to wait in seconds before rebooting the device, or -1 to
cancel a scheduled reboot.
returns Promise that resolves when a restart request was successfully
rescheduled.
Sends a single message to event listeners within your extension or a
different extension/app. Similar to runtime.connect but only sends a
single message, with an optional response. If sending to your extension,
the runtime.onMessage event will be fired in every frame of your
extension (except for the sender's frame), or runtime.onMessageExternal,
if a different extension. Note that extensions cannot send messages to
content scripts using this method. To send messages to content scripts,
use tabs.sendMessage.
extensionId The ID of the extension to send the message to. If
omitted, the message will be sent to your own extension/app. Required if
sending messages from a web page for web
messaging.
message The message to send. This message should be a JSON-ifiable
object.
returns Promise support was added for extension contexts in Chrome 99.
When communicating from a web page to an extension, promises are
available from Chrome 118.
Send a single message to a native application. This method requires the
"nativeMessaging" permission.
application The name of the native messaging host, or target details.
message The message that will be passed to the native messaging host.
Sets the URL to be visited upon uninstallation. This may be used to clean
up server-side data, do analytics, and implement surveys. Maximum 1023
characters.
url URL to be opened after the extension is uninstalled. This URL must
have an http: or https: scheme. Set an empty string to not open a new
tab upon uninstallation.
returns Promise that resolves when the uninstall URL is set. If the
given URL is invalid, the promise will be rejected.