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 pueden usar tus extensiones:

Pasaje de mensajes
Tu 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 la 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 proporcionan utilidad, como la conversión de representaciones de recursos internos a 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 para incluir un recurso de extensión en una página web. Las dos diferencias son que los recursos de la extensión deben exponerse como recursos accesibles a través de la Web y que, por lo general, las secuencias de comandos de contenido son responsables de insertar los recursos de la extensión.

En este ejemplo, la extensión agregará logo.png a la página en la que se inyecta la secuencia de comandos de contenido con runtime.getURL() para crear una URL 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);
}

Cómo enviar datos del trabajador del servicio a una secuencia de comandos de contenido

Es común que las secuencias de comandos de contenido de una extensión necesiten datos que administra otra parte de la extensión, como el trabajador de servicio. 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 el pase de mensajes para coordinarse en 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 la extensión podría brindar un mejor servicio a sus usuarios 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

Es un filtro para hacer coincidir ciertos contextos de extensión. 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 la extensión.

"BACKGROUND"
Especifica el tipo de contexto como un trabajador de servicio.

"OFFSCREEN_DOCUMENT"
Especifica el tipo de contexto como un documento fuera de la 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

    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

    Es el origen del documento asociado con este contexto, o bien no está definido si el contexto no se aloja en un documento.

  • documentUrl

    cadena opcional

    Es la URL del documento asociado con este contexto, o no se define si el contexto no se aloja en un documento.

  • frameId

    número

    El ID del marco para este contexto, o -1 si este contexto no se aloja en un marco.

  • incógnito

    booleano

    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

Es 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

    cadena 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

    cadena opcional

    Chrome 74 y versiones posteriores

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

  • origin

    cadena opcional

    Chrome 80 y versiones posteriores

    Es el origen de la página o el marco que abrió la conexión. Puede variar según la propiedad url (p.ej., about:blank) o puede ser opaca (p.ej., iframes en zona de pruebas). Esto es útil para identificar si se puede confiar en el origen si no podemos saberlo de inmediato a partir de la URL.

  • tab

    Tab 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

    cadena 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

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

"chrome_update"
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 envía el evento. "app_update" se usa cuando se necesita el reinicio porque la aplicación se actualiza a una versión más reciente. "os_update" se usa cuando se necesita el reinicio porque el navegador o el SO se actualizaron a una versión más reciente. "Periódico" se usa cuando el sistema se ejecuta durante más tiempo que el tiempo de actividad permitido establecido en la política empresarial.

Enum

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

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 del cliente nativo Esto puede ser diferente de arch en algunas plataformas.

  • El sistema operativo en el que se ejecuta Chrome

PlatformNaclArch

Chrome 44 y versiones posteriores

La arquitectura del cliente nativo Esto puede ser diferente de arch en algunas plataformas.

Enum

"arm"
Especifica la arquitectura del cliente nativo 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. Consulta Conexiones de larga duración para obtener más informació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 de los otros extremos. 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 o onConnectNative.

  • desconectar

    void

    Desconecta el puerto de inmediato. Llamar a disconnect() en un puerto que ya se desactivó 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 poder convertirse a JSON.

RequestUpdateCheckStatus

Chrome 44 y versiones posteriores

Resultado de la verificación de actualización.

Enum

"throttled"
Especifica que se limitó la verificación de estado. Esto puede ocurrir después de realizar varias verificaciones 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

El ID de la extensión o app.

Tipo

string

lastError

Se completa con un mensaje de error si falla la llamada a una función de la API; de lo contrario, no se define. 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 que indica la función de la API que produjo el error. Las funciones de la API que muestran promesas no establecen 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) o en otras extensiones o apps. Esto es útil para las secuencias de comandos de contenido que se conectan a sus procesos de extensión, 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 secuencias de comandos de contenido incorporadas en pestañas a través de tabs.connect.

Parámetros

  • extensionId

    cadena 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 envías mensajes desde una página web para la 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 escuchan el evento de conexión.

Muestra

  • Es el puerto a través del cual se pueden enviar y recibir mensajes. Si la extensión no existe, se activa el evento onDisconnect del puerto.

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 Mensajes nativos 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

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

      El objeto "window" de JavaScript para la página en segundo plano

Muestra

  • Promise<Window | undefined>

    Chrome 99 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getContexts()

Promesa Chrome 116 y versiones posteriores MV3 y versiones posteriores 
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 coincide 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<ExtensionContext[]>

    Las promesas solo se admiten para 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,
)

Devuelve un 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<DirectoryEntry>

    Chrome 122 y versiones posteriores

    Las promesas solo se admiten para 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

    Es 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

    La URL completamente calificada del recurso.

openOptionsPage()

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

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

El comportamiento preciso puede depender de la clave options_ui o options_page de tu manifiesto, o de lo que Chrome admita en ese momento. Por ejemplo, la página se puede abrir en una pestaña nueva, en chrome://extensions, en una app o simplemente enfocar 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

  • Promise<void>

    Chrome 99 y versiones posteriores

    Las promesas solo se admiten para 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 repetitivo, probablemente solo sirvan para desperdiciar recursos del cliente, de la red y del servidor.

Nota: Cuando se llame con una devolución de llamada, en lugar de mostrar un objeto, esta función mostrará las dos propiedades como argumentos separados que se pasan 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

      Objeto RequestUpdateCheckResult que contiene el estado de la verificación de actualización 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

  • Promise<object>

    Chrome 109 y versiones posteriores

    Las promesas solo se admiten para 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, no se realiza ninguna acción.

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 los segundos indicados. Si se vuelve a llamar antes de que finalice el tiempo, se retrasará el reinicio. Si se lo 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 que invoque esta API puede llamarla de forma reiterada.

Parámetros

  • segundos

    número

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

  • Promise<void>

    Chrome 99 y versiones posteriores

    Las promesas solo se admiten para 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

    cadena opcional

    Es 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 se pueda convertir a JSON.

  • opciones

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Indica si el ID del canal 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 mientras se conecta 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 se admiten para 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

      Es 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á cuando se desinstale el complemento. Se puede usar para limpiar 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. Esta 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

  • Promise<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 de inmediato porque se requiere 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 (a través de runtime.connect) o desde un sitio web que se puede 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

        cadena 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 se incluye si "reason" es "update".

      • El motivo por el que se envía 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

      booleano | no definido

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

      booleano | no definido

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 realice el reinicio. 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 apps de kiosco de ChromeOS.

Parámetros

onStartup

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

Se activa cuando se inicia por primera vez un perfil que tiene instalada esta extensión. Este evento no se activa cuando se inicia un perfil de Incógnito, incluso si esta extensión funciona en el modo Incógnito "dividido".

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 completen las operaciones asíncronas que se inician 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 quieres que se instale antes, puedes llamar explícitamente a chrome.runtime.reload(). Si tu extensión usa una página en segundo plano persistente, esta nunca se descarga, por lo que, a menos que llames a chrome.runtime.reload() de forma manual 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

        Es el número de versión de la actualización disponible.

onUserScriptConnect

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

Se activa cuando se establece una conexión desde una secuencia de comandos del usuario de 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

      booleano | no definido