chrome.runtime

Descripción

Usa la API de chrome.runtime para recuperar el trabajador de servicio, mostrar detalles sobre el manifiesto y escuchar y responder eventos en el ciclo de vida de la extensión. También puedes usar esta API para convertir la ruta de acceso relativa de las URLs en URLs completas.

Descripción general

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

Pasaje 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 en el dispositivo del usuario con connectNative() y sendNativeMessage().
Cómo acceder a los metadatos de la extensión y la plataforma
Estos métodos te permiten recuperar varios metadatos específicos sobre la extensión y el plataforma. Entre los métodos de esta categoría, se incluyen getManifest() y getPlatformInfo().
Cómo administrar el ciclo de vida y las opciones de la extensión
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. Entre los métodos de esta categoría, se incluye getURL().
Utilidades del modo kiosco
Estos métodos solo están disponibles en ChromeOS y existen principalmente para admitir implementaciones de kiosco. Entre los métodos de esta categoría, se incluyen restart 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

Cómo agregar 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 activo debe declararse como un recurso accesible a través de 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, estos dos contextos no pueden acceder directamente a los valores de cada uno. En su lugar, la extensión puede usar message pasando para coordinar estos diferentes contextos.

En este ejemplo, la secuencia de comandos de contenido necesita algunos datos del trabajador de servicio de la extensión para inicializar su IU. Para obtener estos datos, pasa un mensaje get-user-data al trabajador de servicio y 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);
  }
});

Recopila comentarios sobre la desinstalación

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 demo de Manifest V3: Recursos accesibles a través de la Web para ver 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 un panel lateral.

"DEVELOPER_TOOLS"
Especifica el tipo de contexto como herramientas para desarrolladores.

ExtensionContext

Chrome 114 y versiones posteriores

Un contexto que aloja contenido de extensión.

Propiedades

  • ID de contexto

    string

    Es un identificador único para este contexto.

  • contextType

    ContextType

    Es el tipo de contexto al que corresponde.

  • documentId

    cadena opcional

    Un UUID para el documento asociado con este contexto, o no definido si este contexto no se aloja en un documento.

  • documentOrigin

    cadena opcional

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

  • documentUrl

    cadena 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

    Indica 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 se aloja en una pestaña.

  • windowId

    número

    El ID de la ventana para este contexto, o -1 si este contexto no se aloja 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

    cadena opcional

    Chrome 106 y versiones posteriores

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

  • documentLifecycle

    string opcional

    Chrome 106 y versiones posteriores

    Es el ciclo de vida en el que se encuentra 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 marcos de nivel superior, positivo para marcos secundarios. Solo se establecerá cuando se configure tab.

  • id

    cadena 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 de confianza 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 corresponde. Esta propiedad solo estará presente cuando la conexión se haya abierto desde una pestaña (incluidas las secuencias de comandos de contenido) y solo si el receptor 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

    Es 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 envía este evento.

Enum

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

"update"
Especifica el motivo del evento como una actualización de 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

&quot;app_update&quot;
Especifica el motivo del evento como una actualización de la app.

"os_update"
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

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 arch en algunas plataformas.

Enum

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

"x86-32"
Especifica la arquitectura del cliente nativo 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.

"openbsd"
Especifica el sistema operativo OpenBSD.

"fuchsia"
Especifica el sistema operativo Fuchsia.

Port

Es un objeto que permite la 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

    Event<functionvoidvoid>

    Se activa cuando el puerto se desconecta del otro extremo. Es posible que se establezca runtime.lastError si el puerto se desconectó por un error. Si el puerto se cierra mediante desconexión, 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

    Event<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 que ya está desconectado no tiene 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 muestra 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 verificaciones 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

    cadena 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 a 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

    Es el ID de la extensión a la que te conectarás. Si se omite, se intentará establecer una conexión con tu 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 TLS se pasará a onConnectExternal para los procesos que escuchan el evento de conexión.

    • nombre

      cadena opcional

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

Muestra

  • Es el 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

    Es 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 el objeto "window" de JavaScript para la página en segundo plano que se ejecuta dentro de la extensión o app 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<Window | undefined>

    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

    Es 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

  • Promesa<DirectoryEntry>

    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<PlatformInfo>

    Chrome 99 y versiones posteriores

    Las promesas solo se admiten para 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 una app o 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 admita 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 tu extensión no declara una página de opciones o si Chrome no pudo crear una por algún otro motivo, la devolución de llamada establecerá 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 es compatible con 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 de actualización inmediata para esta app 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 adecuado para llamar en circunstancias muy limitadas, por ejemplo, si tu extensión se comunica con un servicio de backend y este determinó que la versión de la extensión del cliente está muy desactualizada y deseas solicitarle al usuario que la actualice. La mayoría de los otros usos de requestUpdateCheck, como llamarlo de forma incondicional en función de un temporizador repetido, probablemente solo sirvan para desperdiciar recursos del cliente, de la red y del servidor.

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 verificación de actualización.

      • versión

        cadena opcional

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

Muestra

  • Promesa<objeto>

    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. No se realiza ninguna acción en el modo que no es de 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 solo mensaje a los objetos de escucha de eventos dentro de tu extensión o a una extensión o app diferente. Es similar a runtime.connect, pero solo envía un solo mensaje, con una respuesta opcional. Si se envía a tu extensión, se activará el evento runtime.onMessage en cada fotograma de tu extensión (excepto en el fotograma del remitente) o runtime.onMessageExternal, si se trata de una extensión diferente. Ten en cuenta que las extensiones no pueden enviar mensajes a secuencias de comandos del 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. Es obligatorio si envías 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

      Es 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

  • Promise<any>

    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

    Es el nombre del host de mensajería nativa.

  • mensaje

    objeto

    Es el mensaje que se pasará 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 mientras se conecta al host de mensajería nativo, se llamará a la devolución de llamada sin argumentos y runtime.lastError se establecerá en el mensaje de error.

Muestra

  • Promise<any>

    Chrome 99 y versiones posteriores

    Las promesas solo se admiten para 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 los datos del servidor, realizar análisis y, también, implementar encuestas. Se admiten hasta 1,023 caracteres.

Parámetros

  • url

    string

    Es la URL que se abrirá después de que se desinstale la extensión. La URL debe tener un esquema http: o https:. Establece una cadena vacía para no abrir una pestaña nueva durante 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 se admiten para 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 (a través 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 se instala la extensión por primera vez, cuando se actualiza a una versión nueva y cuando Chrome se actualiza a una versión nueva.

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 del módulo compartido importado que se actualizó. Solo está presente si "reason" es "shared_module_update".

      • previousVersion

        cadena opcional

        Indica la versión anterior de la extensión, que se acaba de actualizar. Solo está presente si "reason" 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 (a través de runtime.sendMessage) o una secuencia de comandos de contenido (a través 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 se envía un mensaje desde otra extensión (por runtime.sendMessage). No se puede usar 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 se debe reiniciar una app o el dispositivo en el que se ejecuta. La app debe cerrar todas sus ventanas lo antes posible para permitir que se reinicie. Si la app no hace nada, se aplicará un reinicio después de que haya 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 se produce 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 la app no se descargará 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 de inmediato 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 detecten 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 y versiones posteriores 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Se activa cuando se envía un mensaje desde una secuencia de comandos del 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