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.

La mayoría de los miembros de esta API no requieren ningún permiso. Se necesita este permiso para connectNative(), sendNativeMessage() y onNativeConnect.

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

manifest.json:

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

Conceptos y uso

La API de Runtime proporciona métodos para admitir una serie de áreas que tus extensiones pueden 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 en el dispositivo del usuario mediante 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 la plataforma. Los métodos de esta categoría incluyen getManifest() y getPlatformInfo().
Cómo administrar 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 proporcionan una utilidad, como la conversión de representaciones de recursos internos a 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 restart() y restartAfterDelay().

Comportamiento de las extensiones sin empaquetar

Cuando una extensión desempaquetada se vuelve a cargar, se trata como una actualización. Esto significa que el evento chrome.runtime.onInstalled se activará con el motivo "update". Esto incluye cuando la extensión se vuelve a cargar con chrome.runtime.reload().

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 deben exponerse como recursos accesibles desde la Web y que, por lo general, las secuencias de comandos de contenido son responsables de insertar los recursos de 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 mediante runtime.getURL() para crear una URL completamente calificada. Sin embargo, primero se debe declarar el recurso como 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);
}

Cómo enviar datos desde una secuencia de comandos de contenido al service worker

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

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

service-worker.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 servir mejor 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

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

Tipos

ContextFilter

Chrome 114 y versiones posteriores

Un filtro que debe coincidir con determinados contextos de extensión. Los contextos coincidentes deben coincidir con todos los filtros especificados. Cualquier filtro que no se especifique coincide 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.

ExtensionContext

Chrome 114 y versiones posteriores

Un contexto que aloja el contenido de la extensión.

Propiedades

  • contextId

    cadena

    Un identificador único para este contexto

  • contextType

    ContextType

    Es el tipo de contexto al que corresponde este elemento.

  • documentId

    cadena opcional

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

  • documentOrigin

    cadena opcional

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

  • documentUrl

    cadena opcional

    Es la URL del documento asociado con este contexto, o no está definido 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

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

    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 fotogramas de nivel superior, positivo para fotogramas secundarios. Esto 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

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

  • origin

    cadena opcional

    Chrome 80 y versiones posteriores

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

  • tab

    Tab opcional

    El tabs.Tab que abrió la conexión, si corresponde Esta propiedad solo estará presente cuando se abra la conexión desde una pestaña (incluidas las secuencias de comandos del 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 lo solicita la extensión y si está disponible.

  • url

    cadena 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 de la página que lo aloja.

OnInstalledReason

Chrome 44 y versiones posteriores

La razón por la 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

La razón por la que se envía 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 debe reiniciarse porque el navegador o el SO están actualizados a una versión más reciente. "periodic" se usa cuando el sistema se ejecuta durante un tiempo de actividad superior al permitido 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 nativa del cliente 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 Puede ser diferente de la arquitectura en algunas plataformas.

Enum

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

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

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

"mips"
Especifica la arquitectura nativa del cliente 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 de Fuchsia.

Port

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

Propiedades

  • name

    cadena

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

  • onDisconnect

    Evento<functionvoidvoid>

    Se activa cuando el puerto se desconecta de los otros extremos. Se puede establecer runtime.lastError si el puerto se desconectó por un error. Si el puerto se cierra por desconexión, este evento solo se activa en el otro extremo. Este evento se activa como máximo una vez (consulta también Ciclo de vida del puerto).

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

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

    • callback

      la función

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

      (port: Port)=>void

  • onMessage

    Evento<functionvoidvoid>

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

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

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

    • callback

      la función

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

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

      • message

        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 envían eventos nuevos a él.

    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 mostrará un error.

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

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

    • message

      cualquiera

      Chrome 52 y versiones posteriores

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

RequestUpdateCheckStatus

Chrome 44 y versiones posteriores

Resultado de la búsqueda de actualizaciones.

Enum

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

cadena

lastError

Se propaga con un mensaje de error si falla la llamada a una función de la API; de lo contrario, no está definido. 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 con la función de la API que produjo el error. Las funciones de API que muestran promesas no establecen esta propiedad.

Tipo

objeto

Propiedades

  • message

    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 de 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 del contenido incorporadas en pestañas por medio de tabs.connect.

Parámetros

  • extensionId

    cadena opcional

    El ID de la extensión a la que se conectará. 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 mensajes web.

  • connectInfo

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Establece si el ID del canal TLS se pasará a onConnectExternal para los procesos que están a la escucha del evento de conexión.

    • name

      cadena opcional

      Se pasará a onConnect para los procesos que están a la escucha del evento de conexión.

Devuelve

  • 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 Mensajería nativa para obtener más información.

Parámetros

  • aplicación

    cadena

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

Devuelve

  • 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 eventos, 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 produce 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 de fondo.

Devuelve

  • Promesa<Window|undefined>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getContexts()

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

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

Parámetros

  • filter

    ContextFilter

    Un filtro para encontrar contextos que coincidan. 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

Devuelve

  • Promise<ExtensionContext[]>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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.

Devuelve

  • 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

Devuelve

  • Promise<DirectoryEntry>

    Chrome 122 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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

Devuelve

  • Promise<PlatformInfo>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Parámetros

  • ruta de acceso

    cadena

    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.

Devuelve

  • cadena

    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 tecla [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 la compatibilidad de Chrome en ese momento. Por ejemplo, la página puede abrirse en una pestaña nueva, dentro de chrome://extensions, en una aplicación, o bien puede destacar una página de opciones abierta. Nunca hará que se vuelva a cargar la página del emisor.

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 configurará lastError.

Parámetros

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

reload()

chrome.runtime.reload()

Vuelve a cargar la app o extensión. No se admite este método 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 app o extensión.

Importante: La mayoría de las extensiones o apps no deben usar este método, dado 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 del cliente está muy desactualizada y quieres pedirle a un usuario que la actualice. La mayoría de los demás usos de requestUpdateCheck, como llamarlo incondicionalmente según un temporizador recurrente, probablemente solo sirvan para desperdiciar recursos del cliente, de la red y del servidor.

Nota: Cuando se llama con una devolución de llamada, en lugar de mostrar un objeto, esta función muestra 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

      El 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

        cadena opcional

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

Devuelve

  • Promise<object>

    Chrome 109 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

restart()

chrome.runtime.restart()

Reinicia el dispositivo ChromeOS cuando la app se ejecute en modo kiosco. De lo contrario, no funcionará.

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 determinados segundos. Si se vuelve a llamar antes de que finalice el horario, se retrasará el reinicio. Si se llama con un valor de -1, se cancelará el reinicio. Es una no-op en el modo sin kiosco. Solo se permite que la primera extensión la llame de manera repetida para 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

Devuelve

  • Promise<void>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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 una extensión o app diferente. Es similar a runtime.connect, pero envía un solo mensaje, con una respuesta opcional. Si envías contenido a tu extensión, se activará el evento runtime.onMessage en cada marco de tu extensión (excepto 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 del contenido con este método. Para enviar mensajes a las secuencias de comandos del contenido, usa tabs.sendMessage.

Parámetros

  • extensionId

    cadena opcional

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

  • message

    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 TLS se pasará a onMessageExternal para los procesos que están a la escucha del 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

      Objeto de respuesta JSON enviado por 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 se establecerá runtime.lastError en el mensaje de error.

Devuelve

  • Promesa<cualquiera>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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

    cadena

    Es el nombre del host de mensajería nativa.

  • message

    objeto

    Es 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 se establecerá runtime.lastError en el mensaje de error.

Devuelve

  • Promesa<cualquiera>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

setUninstallURL()

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

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

Parámetros

  • url

    cadena

    La URL que se abrirá después de desinstalar la extensión. Esta URL debe tener un esquema http: o https:. Establecer 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

Devuelve

  • Promise<void>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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

    la 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 mediante un proceso de extensión o una secuencia de comandos de contenido (de runtime.connect).

Parámetros

  • callback

    la 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 puede conectar de forma externa.

Parámetros

  • callback

    la 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 el Sistema operativo Chrome.

Parámetros

  • callback

    la 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 la extensión se actualiza a una nueva versión y cuando Chrome se actualiza a una nueva versión.

Parámetros

  • callback

    la 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 importada de módulos compartidos que se actualizó. Esto solo está presente si el “motivo” 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 “motivo” es “actualización”.

      • La razón por la 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 (por parte de runtime.sendMessage) o desde una secuencia de comandos de contenido (de tabs.sendMessage).

Parámetros

  • callback

    la función

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

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

    • message

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      la función

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

      ()=>void

    • resultados

      boolean|undefined

onMessageExternal

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

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

Parámetros

  • callback

    la función

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

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

    • message

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      la función

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

      ()=>void

    • resultados

      boolean|undefined

onRestartRequired

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

Se activa cuando se necesita reiniciar una app o el dispositivo en el que se ejecuta. La app debe cerrar todas las ventanas lo antes posible para que se produzca el reinicio. Si la app no realiza ninguna acción, se ejecutará un reinicio de manera forzosa después de un período de gracia de 24 horas. Actualmente, este evento solo está activado para las aplicaciones de kiosco de ChromeOS.

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 funciona en modo incógnito “dividido”.

Parámetros

  • callback

    la 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 dará la oportunidad de hacer una limpieza. Ten en cuenta que, como se descarga la página, no se garantiza que se completen las operaciones asíncronas iniciadas 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

    la 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, después de todo, la app no se descargará.

Parámetros

  • callback

    la 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 en ese momento. 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 la extensión utiliza una página en segundo plano persistente, la página de fondo nunca se descarga, por lo que, 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 Chrome se reinicie. Si ningún controlador recibe este evento, y la extensión tiene una página en segundo plano persistente, se comporta como si se llamara a chrome.runtime.reload() en respuesta a este evento.

Parámetros

  • callback

    la función

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

    (details: object)=>void

    • detalles

      objeto

      • versión

        cadena

        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 de usuario desde esta extensión.

Parámetros

  • callback

    la 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 de usuario asociada con la misma extensión.

Parámetros

  • callback

    la función

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

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

    • message

      cualquiera

    • remitente

      MessageSender

    • sendResponse

      la función

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

      ()=>void

    • resultados

      boolean|undefined