chrome.runtime

Descripción

Usa la API de chrome.runtime para recuperar el service worker, mostrar detalles sobre el manifiesto, y detectar eventos en el ciclo de vida de la extensión y responder a ellos. También puedes usar esta API para convertir la ruta de acceso relativa de las URLs en URLs completamente calificadas.

Descripción general

La API de Runtime proporciona métodos para admitir varias áreas de funcionalidad que tus extensiones puede usar:

Transmisión de mensajes
La extensión puede comunicarse con diferentes contextos dentro de ella y también con otras extensiones mediante estos métodos y eventos: connect(), onConnect onConnectExternal, sendMessage(), onMessage y onMessageExternal. Además, tu extensión puede pasar mensajes a aplicaciones nativas del dispositivo del usuario usando connectNative() y sendNativeMessage().
.
Accede a los metadatos de extensiones y plataformas
Estos métodos te permiten recuperar varios metadatos específicos sobre la extensión y el plataforma. Los métodos de esta categoría incluyen getManifest() y getPlatformInfo().
Administra el ciclo de vida y las opciones de las extensiones
Estas propiedades te permiten realizar algunas metaoperaciones en la extensión y mostrar la página de opciones. Los métodos y eventos de esta categoría incluyen onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() y setUninstallURL().
Utilidades auxiliares
Estos métodos son útiles, como la conversión de representaciones de recursos internos en o en formatos externos. Los métodos de esta categoría incluyen getURL().
Utilidades del modo kiosco
Estos métodos solo están disponibles en ChromeOS y existen principalmente para admitir implementaciones de kiosco. Los métodos de esta categoría incluyen reiniciar y restartAfterDelay.

Permisos

La mayoría de los métodos de la API de Runtime no requieren ningún permiso, excepto sendNativeMessage y connectNative, que requieren el permiso nativeMessaging.

Manifiesto

En el siguiente ejemplo, se muestra cómo declarar el permiso nativeMessaging en el manifiesto:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Casos de uso

Agrega una imagen a una página web

Para que una página web acceda a un recurso alojado en otro dominio, debe especificar la URL completa del recurso (p.ej., <img src="https://example.com/logo.png">). Lo mismo sucede cuando se incluye un recurso de extensión en una página web. Las dos diferencias son que los recursos de la extensión se deben exponer como accesibles y que, por lo general, las secuencias de comandos de contenido son responsables de inyectar recursos de extensión.

En este ejemplo, la extensión agregará logo.png a la página donde el contenido de Terraform se inyecta usando runtime.getURL() para crear un completamente calificada. Pero, primero, el recurso debe declararse como un recurso accesible desde la Web en el manifiesto.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Envía datos del service worker a una secuencia de comandos de contenido

Es común que las secuencias de comandos de contenido de una extensión necesiten datos administrados por otra parte de la extensión. como el service worker. Al igual que dos ventanas del navegador abiertas en la misma página web, estas dos contextos no pueden acceder directamente a los valores de otro. En su lugar, la extensión puede usar message pasar para coordinar entre estos contextos diferentes.

En este ejemplo, la secuencia de comandos de contenido necesita algunos datos del service worker de la extensión para inicializamos su IU. Para obtener estos datos, pasa un mensaje get-user-data al service worker responde con una copia de la información del usuario.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

background.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Cómo recopilar comentarios sobre las desinstalaciones

Muchas extensiones usan encuestas posteriores a la desinstalación para comprender cómo podrían funcionar mejor. y mejorar la retención. En el siguiente ejemplo, se muestra cómo agregar esta funcionalidad.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Ejemplos de extensiones

Consulta la demostración de Manifest V3: Recursos accesibles para la Web para obtener más ejemplos de la API de Runtime.

Tipos

ContextFilter

Chrome 114 y versiones posteriores

Un filtro que debe coincidir con ciertos contextos de extensiones. Los contextos coincidentes deben coincidir con todos los filtros especificados. Cualquier filtro que no se especifique coincidirá con todos los contextos disponibles. Por lo tanto, un filtro de `{}` coincidirá con todos los contextos disponibles.

Propiedades

  • contextIds

    string[] opcional

  • contextTypes

    ContextType[] opcional

  • documentIds

    string[] opcional

  • documentOrigins

    string[] opcional

  • documentUrls

    string[] opcional

  • frameIds

    number[] opcional

  • incógnito

    booleano opcional

  • tabIds

    number[] opcional

  • windowIds

    number[] opcional

ContextType

Chrome 114 y versiones posteriores

Enum

"TAB"
Especifica el tipo de contexto como una pestaña

"POPUP"
Especifica el tipo de contexto como una ventana emergente de extensión

"BACKGROUND"
Especifica el tipo de contexto como un service worker.

"OFFSCREEN_DOCUMENT"
Especifica el tipo de contexto como un documento fuera de pantalla.

"SIDE_PANEL"
Especifica el tipo de contexto como panel lateral.

ExtensionContext

Chrome 114 y versiones posteriores

Un contexto que aloja contenido de extensión.

Propiedades

  • ID de contexto

    string

    Un identificador único para este contexto

  • contextType

    ContextType

    Es el tipo de contexto al que corresponde.

  • documentId

    string opcional

    Es un UUID para el documento asociado con este contexto, o no definido si este contexto no está alojado en un documento.

  • documentOrigin

    string opcional

    El origen del documento asociado con este contexto, o indefinido si el contexto no está alojado en un documento.

  • documentUrl

    string opcional

    Es la URL del documento asociado a este contexto, o no definida si el contexto no está alojado en un documento.

  • frameId

    número

    El ID del marco para este contexto, o -1 si este contexto no está alojado en un marco.

  • incógnito

    boolean

    Si el contexto está asociado con un perfil de incógnito.

  • tabId

    número

    El ID de la pestaña para este contexto o -1 si este contexto no está alojado en una pestaña.

  • windowId

    número

    El ID de la ventana para este contexto, o -1 si este contexto no está alojado en una ventana.

MessageSender

Un objeto que contiene información sobre el contexto de la secuencia de comandos que envió un mensaje o una solicitud.

Propiedades

  • documentId

    string opcional

    Chrome 106 y versiones posteriores

    Un UUID del documento que abrió la conexión.

  • documentLifecycle

    string opcional

    Chrome 106 y versiones posteriores

    El ciclo de vida en el que se encontraba el documento que abrió la conexión en el momento en que se creó el puerto. Ten en cuenta que el estado del ciclo de vida del documento puede haber cambiado desde la creación del puerto.

  • frameId

    número opcional

    El marco que abrió la conexión. 0 para los fotogramas de nivel superior, positivo para los fotogramas secundarios Esto solo se establecerá cuando se establezca tab.

  • id

    string opcional

    El ID de la extensión que abrió la conexión, si corresponde.

  • nativeApplication

    string opcional

    Chrome 74 y versiones posteriores

    El nombre de la aplicación nativa que abrió la conexión, si corresponde.

  • origin

    string opcional

    Chrome 80 y versiones posteriores

    El origen de la página o el marco que abrió la conexión. Puede variar de la propiedad de la URL (p.ej., about:blank) o ser opaca (p.ej., iframes de zona de pruebas). Esto es útil para identificar si el origen es confiable en caso de que no se sepa inmediatamente a partir de la URL.

  • tab

    Pestaña opcional

    El tabs.Tab que abrió la conexión, si lo hay. Esta propiedad solo estará presente cuando se abra la conexión desde una pestaña (incluidas las secuencias de comandos de contenido) y solo si la app receptora es una extensión, no una app.

  • tlsChannelId

    string opcional

    El ID del canal TLS de la página o el marco que abrió la conexión, si la extensión lo solicita y si está disponible.

  • url

    string opcional

    La URL de la página o el marco que abrió la conexión. Si el remitente está en un iframe, será la URL del iframe, no la URL de la página que lo aloja.

OnInstalledReason

Chrome 44 y versiones posteriores

El motivo por el que se despacha este evento.

Enum

"install"
Especifica el motivo del evento como una instalación.

"update"
Especifica el motivo del evento como una actualización de la extensión.

&quot;chrome_update&quot;
Especifica el motivo del evento como una actualización de Chrome.

"shared_module_update"
Especifica el motivo del evento como una actualización de un módulo compartido.

OnRestartRequiredReason

Chrome 44 y versiones posteriores

El motivo por el que se despacha el evento. "app_update" se usa cuando es necesario reiniciar porque la aplicación se actualiza a una versión más reciente. "os_update" se usa cuando es necesario reiniciar porque el navegador o el SO están actualizados a una versión más reciente. 'periódico' se usa cuando el sistema se ejecuta por un período superior al establecido en la política empresarial.

Enum

"app_update"
Especifica el motivo del evento como una actualización de la app.

&quot;os_update&quot;
Especifica el motivo del evento como una actualización del sistema operativo.

"periodic"
Especifica el motivo del evento como un reinicio periódico de la app.

PlatformArch

Chrome 44 y versiones posteriores

La arquitectura del procesador de la máquina.

Enum

"arm"
Especifica la arquitectura del procesador como arm.

"arm64"
Especifica la arquitectura del procesador como arm64.

"x86-32"
Especifica la arquitectura del procesador como x86-32.

"x86-64"
Especifica la arquitectura del procesador como x86-64.

"mips"
Especifica la arquitectura del procesador como mips.

"mips64"
Especifica la arquitectura del procesador como mips64.

PlatformInfo

Es un objeto que contiene información sobre la plataforma actual.

Propiedades

  • La arquitectura del procesador de la máquina.

  • nacl_arch

    PlatformNaclArch

    La arquitectura nativa del cliente Esto puede ser diferente de la arquitectura en algunas plataformas.

  • El sistema operativo en el que se ejecuta Chrome.

PlatformNaclArch

Chrome 44 y versiones posteriores

La arquitectura nativa del cliente Esto puede ser diferente de la arquitectura en algunas plataformas.

Enum

"arm"
Especifica la arquitectura nativa del cliente como arm.

"x86-32"
Especifica la arquitectura nativa del cliente como x86-32.

"x86-64"
Especifica la arquitectura del cliente nativo como x86-64.

"mips"
Especifica la arquitectura del cliente nativo como mips.

"mips64"
Especifica la arquitectura del cliente nativo como mips64.

PlatformOs

Chrome 44 y versiones posteriores

El sistema operativo en el que se ejecuta Chrome.

Enum

"mac"
Especifica el sistema operativo MacOS.

"win"
Especifica el sistema operativo Windows.

"android"
Especifica el sistema operativo Android.

"cros"
Especifica el sistema operativo Chrome.

"linux"
Especifica el sistema operativo Linux.

&quot;openbsd&quot;
Especifica el sistema operativo OpenBSD.

"fuchsia"
Especifica el sistema operativo Fuchsia.

Port

Es un objeto que permite una comunicación bidireccional con otras páginas. Para obtener más información, consulta Conexiones de larga duración.

Propiedades

  • nombre

    string

    Es el nombre del puerto, como se especifica en la llamada a runtime.connect.

  • onDisconnect

    Evento<functionvoidvoid>

    Se activa cuando el puerto se desconecta del otro extremo. Es posible que se configure runtime.lastError si el puerto se desconectó por un error. Si el puerto se cierra mediante la opción desconnect, este evento solo se activa en el otro extremo. Este evento se activa como máximo una vez (consulta también Duración del puerto).

    La función onDisconnect.addListener se ve de la siguiente manera: 

    (callback: function) => {...}

    • callback

      función

      El parámetro callback se ve de la siguiente manera: 

      (port: Port) => void

  • onMessage

    Evento<functionvoidvoid>

    Este evento se activa cuando el otro extremo del puerto llama a postMessage.

    La función onMessage.addListener se ve de la siguiente manera: 

    (callback: function) => {...}

    • callback

      función

      El parámetro callback se ve de la siguiente manera: 

      (message: any, port: Port) => void

      • mensaje

        cualquiera

      • puerto

        Puerto

  • remitente

    MessageSender opcional

    Esta propiedad solo estará presente en los puertos que se pasen a los objetos de escucha onConnect / onConnectExternal / onConnectNative.

  • desconectar

    void

    Desconecta el puerto de inmediato. Llamar a disconnect() en un puerto ya desconectado no tiene ningún efecto. Cuando se desconecta un puerto, no se enviarán eventos nuevos a este.

    La función disconnect se ve de la siguiente manera: 

    () => {...}

  • postMessage

    void

    Envía un mensaje al otro extremo del puerto. Si el puerto está desconectado, se genera un error.

    La función postMessage se ve de la siguiente manera: 

    (message: any) => {...}

    • mensaje

      cualquiera

      Chrome 52 y versiones posteriores

      El mensaje que se enviará. Este objeto debe ser JSON.

RequestUpdateCheckStatus

Chrome 44 y versiones posteriores

Resultado de la búsqueda de actualizaciones.

Enum

"throttled"
Especifica que se limitó la verificación de estado. Esto puede ocurrir después de comprobaciones repetidas en un período breve.

"no_update"
Especifica que no hay actualizaciones disponibles para instalar.

"update_available"
Especifica que hay una actualización disponible para instalar.

Propiedades

id

Es el ID de la extensión o la app.

Tipo

string

lastError

Se propaga con un mensaje de error si falla la llamada a una función de API. de lo contrario, indefinido. Esto solo se define dentro del alcance de la devolución de llamada de esa función. Si se produce un error, pero no se accede a runtime.lastError dentro de la devolución de llamada, se registra un mensaje en la consola en el que se indica la función de la API que produjo el error. Las funciones de la API que muestran promesas no configuran esta propiedad.

Tipo

objeto

Propiedades

  • mensaje

    string opcional

    Detalles sobre el error que se produjo.

Métodos

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

Intenta conectar objetos de escucha dentro de una extensión (como la página en segundo plano) u otras extensiones o apps. Esto es útil para las secuencias de comandos de contenido que se conectan a sus procesos de extensiones, la comunicación entre apps o extensiones y los mensajes web. Ten en cuenta que esto no se conecta con ningún objeto de escucha en una secuencia de comandos de contenido. Las extensiones pueden conectarse a las secuencias de comandos de contenido incorporadas en las pestañas a través de tabs.connect.

Parámetros

  • extensionId

    string opcional

    El ID de la extensión a la que se conectará. Si se omite, se intentará establecer una conexión con su propia extensión. Obligatorio si se envían mensajes desde una página web para mensajería web.

  • connectInfo

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Indica si el ID del canal de TLS se pasará a onConnectExternal para los procesos que escuchan el evento de conexión.

    • nombre

      string opcional

      Se pasará a onConnect para los procesos que escuchen el evento de conexión.

Muestra

  • Puerto a través del cual se pueden enviar y recibir mensajes. El evento onDisconnect del puerto se activa si la extensión no existe.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Se conecta a una aplicación nativa en la máquina anfitrión. Este método requiere el permiso "nativeMessaging". Consulta Mensajería nativa para obtener más información.

Parámetros

  • aplicación

    string

    El nombre de la aplicación registrada a la que te conectarás.

Muestra

  • Puerto a través del cual se pueden enviar y recibir mensajes con la aplicación

getBackgroundPage()

Promesa Solo en primer plano .
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Recupera la "ventana" de JavaScript. objeto de la página en segundo plano que se ejecuta dentro de la extensión o aplicación actual. Si la página en segundo plano es una página de evento, el sistema se asegurará de que se cargue antes de llamar a la devolución de llamada. Si no hay una página en segundo plano, se establece un error.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Ventana opcional

      La "ventana" de JavaScript de la página en segundo plano.

Muestra

  • Promise&lt;Window | indefinido>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getContexts()

Promesa Chrome 116 y versiones posteriores MV3+ .
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Recupera información sobre los contextos activos asociados con esta extensión

Parámetros

  • filter

    ContextFilter

    Un filtro para encontrar contextos coincidentes. Un contexto coincide si concuerda con todos los campos especificados en el filtro. Cualquier campo sin especificar en el filtro coincide con todos los contextos.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (contexts: ExtensionContext[]) => void

Muestra

  • Promise&lt;ExtensionContext[]&gt;

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getManifest()

chrome.runtime.getManifest()

Muestra detalles sobre la app o extensión del manifiesto. El objeto que se muestra es una serialización del archivo de manifiesto completo.

Muestra

  • objeto

    Los detalles del manifiesto

getPackageDirectoryEntry()

Promesa Solo en primer plano .
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Muestra una DirectoryEntry para el directorio del paquete.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Muestra

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getPlatformInfo()

Promesa 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

Muestra información sobre la plataforma actual.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (platformInfo: PlatformInfo) => void

Muestra

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getURL()

chrome.runtime.getURL(
  path: string,
)

Convierte una ruta de acceso relativa dentro de un directorio de instalación de app/extensión en una URL completamente calificada.

Parámetros

  • ruta de acceso

    string

    Una ruta de acceso a un recurso dentro de una app o extensión expresada en relación con su directorio de instalación.

Muestra

  • string

    Es la URL completamente calificada al recurso.

openOptionsPage()

Promesa 
chrome.runtime.openOptionsPage(
  callback?: function,
)

Si es posible, abre la página de opciones de tu extensión.

El comportamiento preciso puede depender de la clave [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) o [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) de tu manifiesto, o de lo que Chrome admite en ese momento. Por ejemplo, es posible que la página se abra en una pestaña nueva, en chrome://extensions, en una aplicación o en una página de opciones abierta. Nunca hará que se vuelva a cargar la página del llamador.

Si la extensión no declara una página de opciones o Chrome no pudo crear una por algún otro motivo, la devolución de llamada establecerá el valor lastError.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

reload()

chrome.runtime.reload()

Vuelve a cargar la app o extensión. Este método no se admite en el modo kiosco. Para el modo kiosco, usa el método chrome.runtime.restart().

requestUpdateCheck()

Promesa 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Solicita que se realice una verificación inmediata de actualizaciones de esta aplicación o extensión.

Importante: La mayoría de las extensiones o apps no deben usar este método, ya que Chrome ya realiza verificaciones automáticas cada pocas horas, y puedes escuchar el evento runtime.onUpdateAvailable sin necesidad de llamar a requestUpdateCheck.

Este método solo es apropiado para realizar llamadas en circunstancias muy limitadas, por ejemplo, si tu extensión se comunica con un servicio de backend y el servicio de backend determinó que la versión de la extensión de cliente está muy desactualizada y quieres indicarle a un usuario que la actualice. La mayoría de los otros usos de requestUpdateCheck, como la llamada incondicional en función de un temporizador recurrente, probablemente solo sirvan para desperdiciar recursos de clientes, redes y servidores.

Nota: Cuando se realiza una llamada con una devolución de llamada, en lugar de mostrar un objeto, esta función muestra las dos propiedades como argumentos separados pasados a la devolución de llamada.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: object) => void

    • resultado

      objeto

      Chrome 109 y versiones posteriores

      Un objeto RequestUpdateCheckResult que contiene el estado de la verificación de actualizaciones y cualquier detalle del resultado si hay una actualización disponible.

      • Resultado de la búsqueda de actualizaciones.

      • versión

        string opcional

        Si hay una actualización disponible, contiene la versión de la actualización disponible.

Muestra

  • Promise&lt;object&gt;

    Chrome 109 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

restart()

chrome.runtime.restart()

Reinicia el dispositivo ChromeOS cuando la app se ejecute en modo kiosco. De lo contrario, es no-op.

restartAfterDelay()

Promesa Chrome 53 y versiones posteriores .
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Reinicia el dispositivo ChromeOS cuando la app se ejecute en modo kiosco después de unos segundos determinados. Si se vuelve a llamar antes de que finalice el tiempo, se retrasará el reinicio. Si se llama con un valor de -1, se cancelará el reinicio. Es una no-op que no está en modo kiosco. Solo la primera extensión puede llamarla repetidamente en invocar esta API.

Parámetros

  • segundos

    número

    Tiempo de espera en segundos antes de reiniciar el dispositivo o -1 para cancelar un reinicio programado.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

sendMessage()

Promesa 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Envía un único mensaje a los objetos de escucha de eventos de tu extensión o de una extensión o app diferente. Es similar a runtime.connect, pero solo envía un mensaje con una respuesta opcional. Si envías el evento a tu extensión, se activará el evento runtime.onMessage en cada marco de tu extensión (excepto en el marco del remitente) o runtime.onMessageExternal, si es una extensión diferente. Ten en cuenta que las extensiones no pueden enviar mensajes a las secuencias de comandos de contenido con este método. Para enviar mensajes a las secuencias de comandos de contenido, usa tabs.sendMessage.

Parámetros

  • extensionId

    string opcional

    El ID de la extensión a la que se enviará el mensaje. Si se omite, el mensaje se enviará a tu propia extensión o app. Obligatorio si se envían mensajes desde una página web para mensajería web.

  • mensaje

    cualquiera

    El mensaje que se enviará. Este mensaje debe ser un objeto que admita JSON.

  • opciones

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Indica si el ID del canal de TLS se pasará a onMessageExternal para los procesos que escuchan el evento de conexión.

  • callback

    función opcional

    Chrome 99 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    (response: any) => void

    • respuesta

      cualquiera

      El objeto de respuesta JSON que envía el controlador del mensaje. Si se produce un error durante la conexión a la extensión, se llamará a la devolución de llamada sin argumentos y runtime.lastError se establecerá en el mensaje de error.

Muestra

  • Promesa<cualquiera>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

sendNativeMessage()

Promesa 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Envía un solo mensaje a una aplicación nativa. Este método requiere el permiso "nativeMessaging".

Parámetros

  • aplicación

    string

    El nombre del host de mensajería nativa.

  • mensaje

    objeto

    El mensaje que se transmitirá al host de mensajería nativa.

  • callback

    función opcional

    Chrome 99 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    (response: any) => void

    • respuesta

      cualquiera

      El mensaje de respuesta que envía el host de mensajería nativa. Si se produce un error durante la conexión al host de mensajería nativa, se llamará a la devolución de llamada sin argumentos y runtime.lastError se establecerá en el mensaje de error.

Muestra

  • Promesa<cualquiera>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setUninstallURL()

Promesa 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Establece la URL que se visitará tras la desinstalación. Se puede usar para limpiar datos del servidor, realizar estadísticas e implementar encuestas. Se admiten hasta 1,023 caracteres.

Parámetros

  • url

    string

    URL que se abrirá después de desinstalar la extensión. La URL debe tener un esquema http: o https:. Establece una cadena vacía para no abrir una pestaña nueva tras la desinstalación.

  • callback

    función opcional

    Chrome 45 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 99 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

Eventos

onBrowserUpdateAvailable

Obsoleto
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Usa runtime.onRestartRequired.

Se activa cuando hay una actualización de Chrome disponible, pero no se instala inmediatamente porque es necesario reiniciar el navegador.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Se activa cuando se establece una conexión desde un proceso de extensión o una secuencia de comandos de contenido (de runtime.connect).

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Se activa cuando se establece una conexión desde otra extensión (de runtime.connect) o desde un sitio web que se pueda conectar de forma externa.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (port: Port) => void

onConnectNative

Chrome 76 y versiones posteriores 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Se activa cuando se establece una conexión desde una aplicación nativa. Este evento requiere el permiso "nativeMessaging". Solo es compatible con ChromeOS.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (port: Port) => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Se activa cuando la extensión se instala por primera vez, cuando se actualiza a una nueva versión y cuando Chrome se actualiza a una nueva versión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • id

        string opcional

        Indica el ID de la extensión importada del módulo compartido que se actualizó. Aparece solo si hay un "motivo". es 'shared_module_update'.

      • previousVersion

        string opcional

        Indica la versión anterior de la extensión, que se acaba de actualizar. Aparece solo si hay un "motivo". es "update".

      • El motivo por el que se despacha este evento.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Se activa cuando se envía un mensaje desde un proceso de extensión (de runtime.sendMessage) o una secuencia de comandos de contenido (de tabs.sendMessage).

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • mensaje

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      función

      El parámetro sendResponse se ve de la siguiente manera: 

      () => void

    • muestra

      boolean | indefinido

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Se activa cuando runtime.sendMessage envía un mensaje desde otra extensión. No se puede utilizar en una secuencia de comandos de contenido.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • mensaje

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      función

      El parámetro sendResponse se ve de la siguiente manera: 

      () => void

    • muestra

      boolean | indefinido

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Se activa cuando una app o el dispositivo en el que se ejecuta deben reiniciarse. La app debería cerrar todas las ventanas lo antes posible para permitir que se reinicie. Si la app no realiza ninguna acción, se aplicará de manera forzosa un reinicio después de transcurrido un período de gracia de 24 horas. Actualmente, este evento solo se activa para las aplicaciones de kiosco del Sistema operativo Chrome.

Parámetros

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Se activa cuando se inicia un perfil que tiene esta extensión instalada por primera vez. Este evento no se activa cuando se inicia un perfil de incógnito, incluso si esta extensión opera en “split” modo Incógnito.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Se envía a la página del evento justo antes de que se descargue. Esto le da a la extensión la oportunidad de realizar una limpieza. Ten en cuenta que, como la página se está descargando, no se garantiza que se complete ninguna operación asíncrona iniciada mientras se controla este evento. Si hay más actividad en la página del evento antes de que se descargue, se enviará el evento onSuspendCanceled y no se descargará la página.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Se envía después de onSuspend para indicar que no se descargará la app después de todo.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Se activa cuando hay una actualización disponible, pero no se instala inmediatamente porque la app se está ejecutando. Si no haces nada, la actualización se instalará la próxima vez que se descargue la página en segundo plano. Si deseas que se instale antes, puedes llamar explícitamente a chrome.runtime.reload(). Si tu extensión utiliza una página en segundo plano persistente, esta página nunca se descarga, por lo tanto, a menos que llames a chrome.runtime.reload() manualmente en respuesta a este evento, la actualización no se instalará hasta la próxima vez que se reinicie Chrome. Si no hay controladores que escuchen este evento y tu extensión tiene una página en segundo plano persistente, se comportará como si se llamara a chrome.runtime.reload() en respuesta a este evento.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • versión

        string

        El número de versión de la actualización disponible.

onUserScriptConnect

Chrome 115 y versiones posteriores MV3+ .
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Se activa cuando se establece una conexión desde una secuencia de comandos de usuario desde esta extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (port: Port) => void

onUserScriptMessage

Chrome 115 y versiones posteriores MV3+ .
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Se activa cuando se envía un mensaje desde una secuencia de comandos de usuario asociada con la misma extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • mensaje

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      función

      El parámetro sendResponse se ve de la siguiente manera: 

      () => void

    • muestra

      boolean | indefinido