chrome.runtime

Descrição

Use a API chrome.runtime para recuperar o service worker, retornar detalhes sobre o manifesto e detectar e responder a eventos no ciclo de vida da extensão. Também é possível usar essa API para converter o caminho relativo de URLs em URLs totalmente qualificados.

A maioria dos membros dessa API não exige permissões. Essa permissão é necessária para connectNative(), sendNativeMessage() e onNativeConnect.

O exemplo a seguir mostra como declarar a permissão "nativeMessaging" no manifesto:

manifest.json:

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

Conceitos e uso

A API Runtime oferece métodos para oferecer suporte a várias áreas que suas extensões podem usar:

Transmissão de mensagens
Sua extensão pode se comunicar com diferentes contextos dentro dela e também com outras extensões usando estes métodos e eventos: connect(), onConnect, onConnectExternal, sendMessage(), onMessage e onMessageExternal. Além disso, a extensão pode transmitir mensagens para aplicativos nativos no dispositivo do usuário usando connectNative() e sendNativeMessage().
Como acessar metadados de extensão e plataforma
Esses métodos permitem recuperar várias partes específicas de metadados sobre a extensão e a plataforma. Os métodos nessa categoria incluem getManifest() e getPlatformInfo().
Gerenciar o ciclo de vida e as opções de extensão
Essas propriedades permitem realizar algumas metaoperações na extensão e mostrar a página de opções. Os métodos e eventos nessa categoria incluem onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() e setUninstallURL().
Utilitários auxiliares
Esses métodos oferecem utilidade, como a conversão de representações de recursos internos em formatos externos. Os métodos nessa categoria incluem getURL().
Utilitários do modo quiosque
Esses métodos estão disponíveis apenas no ChromeOS e existem principalmente para oferecer suporte a implementações de quiosques. Os métodos nessa categoria incluem restart() e restartAfterDelay()`.

Comportamento de extensões descompactadas

Quando uma extensão descompactada é recarregada, isso é tratado como uma atualização. Isso significa que o evento chrome.runtime.onInstalled será acionado com o motivo "update". Isso inclui quando a extensão é recarregada com chrome.runtime.reload().

Casos de uso

Adicionar uma imagem a uma página da Web

Para que uma página da Web acesse um recurso hospedado em outro domínio, ela precisa especificar o URL completo do recurso (por exemplo, <img src="https://example.com/logo.png">). O mesmo vale para incluir um recurso de extensão em uma página da Web. As duas diferenças são que os recursos da extensão precisam ser expostos como recursos acessíveis à Web e que, normalmente, os scripts de conteúdo são responsáveis por injetar recursos de extensão.

Neste exemplo, a extensão adiciona logo.png à página em que o script de conteúdo está sendo injetado usando runtime.getURL() para criar um URL totalmente qualificado. Mas primeiro, o recurso precisa ser declarado como um recurso acessível da Web no manifesto.

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);
}

Enviar dados de um script de conteúdo para o service worker

É comum que os scripts de conteúdo de uma extensão precisem de dados gerenciados por outra parte da extensão, como o service worker. Assim como duas janelas de navegador abertas na mesma página da Web, esses dois contextos não podem acessar diretamente os valores um do outro. Em vez disso, a extensão pode usar a transmissão de mensagens para coordenar esses diferentes contextos.

Neste exemplo, o script de conteúdo precisa de alguns dados do service worker da extensão para inicializar a interface. Para receber esses dados, ele transmite a mensagem get-user-data definida pelo desenvolvedor ao service worker, que responde com uma cópia das informações do usuário.

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);
  }
});

Coletar feedback sobre a desinstalação

Muitas extensões usam pesquisas pós-desinstalação para entender como elas podem atender melhor aos usuários e melhorar a retenção. O exemplo a seguir mostra como adicionar essa funcionalidade.

background.js:

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

Exemplos

Confira mais exemplos da API Runtime na demonstração de recursos acessíveis da Web do Manifest V3.

Tipos

ContextFilter

Chrome 114 ou mais recente

Um filtro para corresponder a determinados contextos de extensão. Os contextos correspondentes precisam corresponder a todos os filtros especificados. Qualquer filtro não especificado corresponde a todos os contextos disponíveis. Assim, um filtro de `{}` vai corresponder a todos os contextos disponíveis.

Propriedades

  • contextIds

    string[] opcional

  • contextTypes

    ContextType[] opcional

  • documentIds

    string[] opcional

  • documentOrigins

    string[] opcional

  • documentUrls

    string[] opcional

  • frameIds

    number[] opcional

  • navegação anônima

    booleano opcional

  • tabIds

    number[] opcional

  • windowIds

    number[] opcional

ContextType

Chrome 114 ou mais recente

Enumeração

"TAB"
Especifica o tipo de contexto como uma guia

"POPUP"
Especifica o tipo de contexto como uma janela pop-up de extensão

"BACKGROUND"
Especifica o tipo de contexto como um service worker.

"OFFSCREEN_DOCUMENT"
Especifica o tipo de contexto como um documento fora da tela.

"SIDE_PANEL"
Especifica o tipo de contexto como um painel lateral.

"DEVELOPER_TOOLS"
Especifica o tipo de contexto como ferramentas para desenvolvedores.

ExtensionContext

Chrome 114 ou mais recente

Um conteúdo de extensão de hospedagem de contexto.

Propriedades

  • contextId

    string

    Um identificador exclusivo para este contexto.

  • contextType

    ContextType

    O tipo de contexto a que isso corresponde.

  • documentId

    string opcional

    Um UUID para o documento associado a esse contexto ou indefinido se o contexto não estiver hospedado em um documento.

  • documentOrigin

    string opcional

    A origem do documento associado a esse contexto ou indefinida se o contexto não estiver hospedado em um documento.

  • documentUrl

    string opcional

    O URL do documento associado a esse contexto ou indefinido se o contexto não estiver hospedado em um documento.

  • frameId

    número

    O ID do frame para este contexto ou -1 se ele não estiver hospedado em um frame.

  • navegação anônima

    booleano

    Indica se o contexto está associado a um perfil anônimo.

  • tabId

    número

    O ID da guia para este contexto ou -1 se ele não estiver hospedado em uma guia.

  • windowId

    número

    O ID da janela para este contexto ou -1 se o contexto não estiver hospedado em uma janela.

MessageSender

Um objeto que contém informações sobre o contexto do script que enviou uma mensagem ou solicitação.

Propriedades

  • documentId

    string opcional

    Chrome 106 ou mais recente

    Um UUID do documento que abriu a conexão.

  • documentLifecycle

    string opcional

    Chrome 106 ou mais recente

    O ciclo de vida do documento que abriu a conexão no momento em que a porta foi criada. O estado do ciclo de vida do documento pode ter mudado desde a criação da portabilidade.

  • frameId

    número optional

    O frame que abriu a conexão. 0 para frames de nível superior e positivo para frames secundários. Isso só será definido quando tab estiver definido.

  • ID

    string opcional

    O ID da extensão que abriu a conexão, se houver.

  • nativeApplication

    string opcional

    Chrome 74 ou mais recente

    O nome do aplicativo nativo que abriu a conexão, se houver.

  • origem

    string opcional

    Chrome 80+

    A origem da página ou do frame que abriu a conexão. Ele pode variar da propriedade "url" (por exemplo, "about:blank") ou ser opaco (por exemplo, iframes em sandbox). Isso é útil para identificar se a origem é confiável quando não é possível saber imediatamente pelo URL.

  • tab

    Guia opcional

    O tabs.Tab que abriu a conexão, se houver. Essa propriedade só estará presente quando a conexão for aberta em uma guia (incluindo scripts de conteúdo) e somente se o destinatário for uma extensão, não um app.

  • tlsChannelId

    string opcional

    O ID do canal TLS da página ou do frame que abriu a conexão, se solicitado pela extensão e se disponível.

  • url

    string opcional

    O URL da página ou do frame que abriu a conexão. Se o remetente estiver em um iframe, será o URL do iframe, não o URL da página que o hospeda.

OnInstalledReason

Chrome 44 ou mais recente

O motivo pelo qual esse evento está sendo enviado.

Enumeração

"install"
Especifica o motivo do evento como uma instalação.

"update"
Especifica o motivo do evento como uma atualização de extensão.

"chrome_update"
Especifica o motivo do evento como uma atualização do Chrome.

"shared_module_update"
Especifica o motivo do evento como uma atualização de um módulo compartilhado.

OnRestartRequiredReason

Chrome 44 ou mais recente

O motivo pelo qual o evento está sendo enviado. "app_update" é usado quando a reinicialização é necessária porque o aplicativo foi atualizado para uma versão mais recente. "os_update" é usado quando a reinicialização é necessária porque o navegador/SO foi atualizado para uma versão mais recente. "periodic" é usado quando o sistema é executado por mais tempo do que o tempo de atividade permitido definido na política corporativa.

Enumeração

"app_update"
Especifica o motivo do evento como uma atualização do app.

"os_update"
Especifica o motivo do evento como uma atualização do sistema operacional.

"periodic"
Especifica o motivo do evento como uma reinicialização periódica do app.

PlatformArch

Chrome 44 ou mais recente

A arquitetura do processador da máquina.

Enumeração

"arm"
Especifica a arquitetura do processador como arm.

"arm64"
Especifica a arquitetura do processador como arm64.

"x86-32"
Especifica a arquitetura do processador como x86-32.

"x86-64"
Especifica a arquitetura do processador como x86-64.

"mips"
Especifica a arquitetura do processador como mips.

"mips64"
Especifica a arquitetura do processador como mips64.

"riscv64"
Especifica a arquitetura do processador como riscv64.

PlatformInfo

Um objeto que contém informações sobre a plataforma atual.

Propriedades

  • A arquitetura do processador da máquina.

  • nacl_arch

    PlatformNaclArch opcional

    A arquitetura do cliente nativo. Isso pode ser diferente da arquitetura em algumas plataformas.

  • O sistema operacional em que o Chrome está sendo executado.

PlatformNaclArch

Chrome 44 ou mais recente

A arquitetura do cliente nativo. Isso pode ser diferente da arquitetura em algumas plataformas.

Enumeração

"arm"
Especifica a arquitetura do cliente nativo como arm.

"x86-32"
Especifica a arquitetura do cliente nativo como x86-32.

"x86-64"
Especifica a arquitetura do cliente nativo como x86-64.

"mips"
Especifica a arquitetura do cliente nativo como mips.

"mips64"
Especifica a arquitetura do cliente nativo como mips64.

PlatformOs

Chrome 44 ou mais recente

O sistema operacional em que o Chrome está sendo executado.

Enumeração

"mac"
Especifica o sistema operacional MacOS.

"win"
Especifica o sistema operacional Windows.

"android"
Especifica o sistema operacional Android.

"cros"
Especifica o sistema operacional Chrome.

"linux"
Especifica o sistema operacional Linux.

"openbsd"
Especifica o sistema operacional OpenBSD.

Port

Um objeto que permite a comunicação bidirecional com outras páginas. Consulte Conexões de longa duração para mais informações.

Propriedades

  • nome

    string

    O nome da porta, conforme especificado na chamada para runtime.connect.

  • onDisconnect

    Event<functionvoidvoid>

    Disparado quando a porta é desconectada das outras extremidades. runtime.lastError pode ser definido se a porta foi desconectada por um erro. Se a porta for fechada usando disconnect, esse evento será acionado apenas na outra extremidade. Esse evento é disparado no máximo uma vez. Consulte também Ciclo de vida da porta.

    A função onDisconnect.addListener tem esta aparência: 

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

    • callback

      função

      O parâmetro callback tem esta aparência: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    Esse evento é acionado quando postMessage é chamado pela outra extremidade da porta.

    A função onMessage.addListener tem esta aparência: 

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

    • callback

      função

      O parâmetro callback tem esta aparência: 

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

      • mensagem

        qualquer

      • porta

        Porta

  • remetente

    MessageSender opcional

    Essa propriedade só estará presente em portas transmitidas para listeners onConnect / onConnectExternal / onConnectNative.

  • desconectar

    void

    Desconecte a porta imediatamente. Chamar disconnect() em uma porta já desconectada não tem efeito. Quando uma porta é desconectada, nenhum novo evento é enviado a ela.

    A função disconnect tem esta aparência: 

    () => {...}

  • postMessage

    void

    Envie uma mensagem para a outra extremidade da porta. Se a porta estiver desconectada, um erro será gerado.

    A função postMessage tem esta aparência: 

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

    • mensagem

      qualquer

      Chrome 52 ou mais recente

      A mensagem a ser enviada. Esse objeto precisa ser JSON-ifiable.

RequestUpdateCheckStatus

Chrome 44 ou mais recente

Resultado da verificação de atualização.

Enumeração

"throttled"
Especifica que a verificação de status foi limitada. Isso pode acontecer após verificações repetidas em um curto período.

"no_update"
Especifica que não há atualizações disponíveis para instalação.

"update_available"
Especifica que há uma atualização disponível para instalação.

Propriedades

id

O ID da extensão/app.

Tipo

string

lastError

Preenchido com uma mensagem de erro se a chamada de uma função de API falhar. Caso contrário, é indefinido. Isso só é definido no escopo do callback dessa função. Se um erro for produzido, mas runtime.lastError não for acessado no callback, uma mensagem será registrada no console listando a função da API que produziu o erro. As funções de API que retornam promessas não definem essa propriedade.

Tipo

objeto

Propriedades

  • mensagem

    string opcional

    Detalhes sobre o erro que ocorreu.

Métodos

connect()

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

Tenta conectar listeners em uma extensão (como a página em segundo plano) ou em outras extensões/apps. Isso é útil para scripts de conteúdo que se conectam aos processos de extensão, comunicação entre apps/extensões e mensagens da Web. Isso não se conecta a nenhum listener em um script de conteúdo. As extensões podem se conectar a scripts de conteúdo incorporados em guias usando tabs.connect.

Parâmetros

  • extensionId

    string opcional

    O ID da extensão a ser conectada. Se omitido, uma conexão será tentada com sua própria extensão. Obrigatório ao enviar mensagens de uma página da Web para mensagens da Web.

  • connectInfo

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Se o ID do canal TLS será transmitido para onConnectExternal em processos que estão detectando o evento de conexão.

    • nome

      string opcional

      Será transmitido para onConnect em processos que estão aguardando o evento de conexão.

Retorna

  • Porta pela qual as mensagens podem ser enviadas e recebidas. O evento onDisconnect da porta é acionado se a extensão não existir.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

Conecta-se a um aplicativo nativo na máquina host. Esse método exige a permissão "nativeMessaging". Consulte Mensagens nativas para mais informações.

Parâmetros

  • aplicativo

    string

    O nome do aplicativo registrado a ser conectado.

Retorna

  • Porta pela qual as mensagens podem ser enviadas e recebidas com o aplicativo.

getBackgroundPage()

Somente em primeiro plano Suspenso desde o Chrome 133
chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

As páginas em segundo plano não existem em extensões MV3.

Recupera o objeto "window" do JavaScript para a página em segundo plano em execução na extensão/app atual. Se a página em segundo plano for uma página de evento, o sistema vai garantir que ela seja carregada antes de chamar o callback. Se não houver uma página em segundo plano, um erro será definido.

Retorna

  • Promise<Window | undefined>

    Chrome 99+

getContexts()

Chrome 116+ MV3+ 
chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

Busca informações sobre contextos ativos associados a esta extensão.

Parâmetros

  • filtrar

    ContextFilter

    Um filtro para encontrar contextos correspondentes. Um contexto corresponde se corresponder a todos os campos especificados no filtro. Qualquer campo não especificado no filtro corresponde a todos os contextos.

Retorna

getManifest()

chrome.runtime.getManifest(): object

Retorna detalhes sobre o app ou a extensão do manifesto. O objeto retornado é uma serialização do arquivo de manifesto completo.

Retorna

  • objeto

    Os detalhes do manifesto.

getPackageDirectoryEntry()

Somente em primeiro plano 
chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

Retorna um DirectoryEntry para o diretório do pacote.

Retorna

  • Promise<DirectoryEntry>

    Chrome 122+

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

Retorna informações sobre a plataforma atual.

Retorna

getURL()

chrome.runtime.getURL(
  path: string,
): string

Converte um caminho relativo em um diretório de instalação de app/extensão em um URL totalmente qualificado.

Parâmetros

  • caminho

    string

    Um caminho para um recurso em um app/extensão expresso em relação ao diretório de instalação.

Retorna

  • string

    O URL totalmente qualificado do recurso.

getVersion()

Pendente
chrome.runtime.getVersion(): string

Retorna a versão da extensão conforme declarado no manifesto.

Retorna

  • string

    A versão da extensão.

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

Abra a página de opções da extensão, se possível.

O comportamento exato pode depender da chave options_ui ou options_page do manifesto ou do que o Chrome oferece suporte no momento. Por exemplo, a página pode ser aberta em uma nova guia, em chrome://extensions, em um app ou apenas focar uma página de opções aberta. Isso nunca fará com que a página do autor da chamada seja recarregada.

Se a extensão não declarar uma página de opções ou se o Chrome não conseguir criar uma por algum outro motivo, o callback vai definir lastError.

Retorna

  • Promessa<void>

    Chrome 99+

reload()

chrome.runtime.reload(): void

Recarrega o app ou a extensão. Esse método não é compatível com o modo quiosque. Para o modo quiosque, use o método chrome.runtime.restart().

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

Solicita uma verificação imediata de atualização para este app/extensão.

Importante: a maioria das extensões/apps não deve usar esse método, já que o Chrome faz verificações automáticas a cada poucas horas, e você pode detectar o evento runtime.onUpdateAvailable sem precisar chamar requestUpdateCheck.

Esse método só é adequado para chamar em circunstâncias muito limitadas, como se a extensão se comunicar com um serviço de back-end, e o serviço de back-end determinar que a versão da extensão do cliente está muito desatualizada e você quiser pedir que um usuário atualize. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer repetido, provavelmente só serve para desperdiçar recursos de cliente, rede e servidor.

Observação: quando chamada com um callback, em vez de retornar um objeto, essa função retorna as duas propriedades como argumentos separados transmitidos ao callback.

Retorna

  • Promise<object>

    Chrome 109+

restart()

chrome.runtime.restart(): void

Reinicie o dispositivo ChromeOS quando o app estiver no modo quiosque. Caso contrário, não vai acontecer nada.

restartAfterDelay()

Chrome 53 ou mais recente 
chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque após o número de segundos especificado. Se for chamado novamente antes do fim do tempo, a reinicialização será adiada. Se for chamado com o valor -1, a reinicialização será cancelada. É uma operação nula no modo que não é quiosque. Só é permitido que a primeira extensão chame essa API repetidamente.

Parâmetros

  • segundos

    número

    Tempo de espera em segundos antes de reiniciar o dispositivo ou -1 para cancelar uma reinicialização programada.

Retorna

  • Promessa<void>

    Chrome 99+

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

Envia uma única mensagem para listeners de eventos na sua extensão ou em outra extensão/app. Semelhante a runtime.connect, mas envia apenas uma mensagem, com uma resposta opcional. Se você estiver enviando para sua extensão, o evento runtime.onMessage será acionado em todos os frames da extensão (exceto o do remetente) ou runtime.onMessageExternal, se for uma extensão diferente. As extensões não podem enviar mensagens para scripts de conteúdo usando esse método. Para enviar mensagens aos scripts de conteúdo, use tabs.sendMessage.

Parâmetros

  • extensionId

    string opcional

    O ID da extensão para enviar a mensagem. Se omitido, a mensagem será enviada para sua própria extensão/app. Obrigatório se você estiver enviando mensagens de uma página da Web para mensagens da Web.

  • mensagem

    qualquer

    A mensagem a ser enviada. Essa mensagem precisa ser um objeto JSON.

  • opções

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Se o ID do canal TLS será transmitido para onMessageExternal para processos que estão detectando o evento de conexão.

Retorna

  • Promise<any>

    Chrome 99+

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

Envie uma única mensagem para um aplicativo nativo. Esse método exige a permissão "nativeMessaging".

Parâmetros

  • aplicativo

    string

    O nome do host de mensagens nativas.

  • mensagem

    objeto

    A mensagem que será transmitida ao host de mensagens nativas.

Retorna

  • Promise<any>

    Chrome 99+

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

Define o URL a ser visitado após a desinstalação. Isso pode ser usado para limpar dados do lado do servidor, fazer análises e implementar pesquisas. Máximo de 1.023 caracteres.

Parâmetros

  • url

    string

    URL a ser aberto depois que a extensão for desinstalada. O URL precisa ter um esquema http: ou https:. Defina uma string vazia para não abrir uma nova guia ao desinstalar.

Retorna

  • Promessa<void>

    Chrome 99+

Eventos

onBrowserUpdateAvailable

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

Use runtime.onRestartRequired.

Disparado quando uma atualização do Chrome está disponível, mas não é instalada imediatamente porque é necessário reiniciar o navegador.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onConnect

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

Disparado quando uma conexão é feita por um processo de extensão ou um script de conteúdo (por runtime.connect).

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (port: Port) => void

onConnectExternal

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

Disparado quando uma conexão é feita de outra extensão (por runtime.connect) ou de um site da Web conectável externamente.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (port: Port) => void

onConnectNative

Chrome 76 ou mais recente 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Disparado quando uma conexão é feita de um aplicativo nativo. Esse evento requer a permissão "nativeMessaging". Ele só está disponível no Chrome OS.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (port: Port) => void

onInstalled

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

Disparado quando a extensão é instalada pela primeira vez, quando ela é atualizada para uma nova versão e quando o Chrome é atualizado para uma nova versão.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) => void

    • detalhes

      objeto

      • ID

        string opcional

        Indica o ID da extensão do módulo compartilhado importado que foi atualizada. Isso só estará presente se "reason" for "shared_module_update".

      • previousVersion

        string opcional

        Indica a versão anterior da extensão, que acabou de ser atualizada. Isso só estará presente se "reason" for "update".

      • O motivo pelo qual esse evento está sendo enviado.

onMessage

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

Disparado quando uma mensagem é enviada de um processo de extensão (por runtime.sendMessage) ou de um script de conteúdo (por tabs.sendMessage).

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • mensagem

      qualquer

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | undefined

onMessageExternal

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

Disparado quando uma mensagem é enviada de outra extensão (por runtime.sendMessage). Não pode ser usado em um script de conteúdo.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • mensagem

      qualquer

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | undefined

onRestartRequired

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

Disparado quando um app ou o dispositivo em que ele é executado precisa ser reiniciado. O app precisa fechar todas as janelas assim que possível para permitir a reinicialização. Se o app não fizer nada, uma reinicialização será forçada após um período de carência de 24 horas. No momento, esse evento só é acionado para apps de quiosque do Chrome OS.

Parâmetros

onStartup

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

Disparado quando um perfil com essa extensão instalada é iniciado pela primeira vez. Esse evento não é acionado quando um perfil anônimo é iniciado, mesmo que a extensão esteja operando no modo de navegação anônima "dividido".

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onSuspend

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

Enviado para a página do evento pouco antes de ela ser descarregada. Isso dá à extensão a oportunidade de fazer uma limpeza. Como a página está sendo descarregada, não há garantia de que as operações assíncronas iniciadas durante o processamento desse evento serão concluídas. Se houver mais atividade na página do evento antes do descarregamento, o evento onSuspendCanceled será enviado e a página não será descarregada.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onSuspendCanceled

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

Enviado após onSuspend para indicar que o app não será descarregado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onUpdateAvailable

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

Disparado quando uma atualização está disponível, mas não é instalada imediatamente porque o app está em execução. Se você não fizer nada, a atualização será instalada na próxima vez que a página em segundo plano for descarregada. Se quiser que ela seja instalada antes, chame explicitamente chrome.runtime.reload(). Se a extensão estiver usando uma página em segundo plano persistente, ela nunca será descarregada. Portanto, a menos que você chame chrome.runtime.reload() manualmente em resposta a esse evento, a atualização não será instalada até a próxima vez que o Chrome for reiniciado. Se nenhum manipulador estiver aguardando esse evento e sua extensão tiver uma página em segundo plano persistente, ela vai se comportar como se chrome.runtime.reload() fosse chamado em resposta a esse evento.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) => void

    • detalhes

      objeto

      • version

        string

        O número da versão da atualização disponível.

onUserScriptConnect

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

Disparado quando uma conexão é feita de um script de usuário desta extensão.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (port: Port) => void

onUserScriptMessage

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

Disparado quando uma mensagem é enviada de um script de usuário associado à mesma extensão.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • mensagem

      qualquer

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | undefined