chrome.runtime

Descrição

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

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

O exemplo abaixo 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 diversas áreas em que suas extensões pode usar:

Transmissão de mensagens
A extensão pode se comunicar com diferentes contextos dentro dela e também com outras extensões usando os seguintes métodos e eventos: connect(), onConnect, onConnectExternal, sendMessage(), onMessage e onMessageExternal. Além disso, sua 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 que você recupere vários metadados específicos sobre a extensão e o de plataforma. Os métodos nessa categoria incluem getManifest() e getPlatformInfo()
Como gerenciar o ciclo de vida e as opções da extensão
Essas propriedades permitem realizar algumas metaoperações na extensão e exibir 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 e 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 são compatíveis principalmente com implementações de quiosque. Os métodos nessa categoria incluem restart() e restartAfterDelay()
.

Comportamento da extensão descompactada

Quando uma extensão descompactada é recarregada, isso é tratado como uma atualização. Isso significa que O evento chrome.runtime.onInstalled será disparado 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 ativo hospedado em outro domínio, ela deve 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 devem ser expostos como web recursos acessíveis e que normalmente os scripts de conteúdo são responsáveis por injetar de extensão.

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

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 dela. como o service worker. Assim como duas janelas do navegador abertas na mesma página da Web, essas dois contextos não podem acessar diretamente os valores um do outro. Em vez disso, a extensão pode usar mensagens passando 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 conseguir esses dados, ele transmite a mensagem get-user-data definida pelo desenvolvedor. ao service worker, e ele 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 desinstalação

Muitas extensões usam pesquisas pós-desinstalação para entender como a extensão pode atender melhor à sua 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

Consulte o Manifesto V3 - Demonstração de recursos acessíveis na Web para mais exemplos da API Runtime.

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. Portanto, um filtro de `{}` 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.

ExtensionContext

Chrome 114 ou mais recente

Um contexto que hospeda o conteúdo da extensão.

Propriedades

  • contextId

    string

    Um identificador exclusivo para este contexto

  • contextType

    ContextType

    O tipo de contexto ao qual corresponde.

  • documentId

    string opcional

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

  • documentOrigin

    string opcional

    A origem do documento associada ao contexto, ou "indefinida se o contexto não estiver hospedado em um documento".

  • documentUrl

    string opcional

    O URL do documento associado a este contexto, ou "undefined" se o contexto não estiver hospedado em um documento.

  • frameId

    number

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

  • navegação anônima

    booleano

    Se o contexto está associado a um perfil de navegação anônima.

  • tabId

    number

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

  • windowId

    number

    O ID da janela para o 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 versões mais recentes

    Um UUID do documento que abriu a conexão.

  • documentLifecycle

    string opcional

    Chrome 106 ou versões mais recentes

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

  • frameId

    número opcional

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

  • id

    string opcional

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

  • nativeApplication

    string opcional

    Chrome 74 ou superior

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

  • origem

    string opcional

    Chrome 80 ou superior

    A origem da página ou frame que abriu a conexão. Ela pode variar em relação à propriedade do URL (por exemplo, about:blank) ou opaca (por exemplo, iframes em sandbox). Isso é útil para identificar se a origem pode ser confiável caso não possamos afirmar imediatamente a partir do URL.

  • tab

    Guia opcional

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

  • 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 frame que abriu a conexão. Se o remetente estiver em um iframe, esse será o URL do iframe, e não o URL da página que o hospeda.

OnInstalledReason

Chrome 44 ou superior

O motivo pelo qual esse evento está sendo despachado.

Enumeração

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

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

&quot;chrome_update&quot;
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 superior

O motivo pelo qual o evento está sendo despachado. "app_update" é usada quando a reinicialização é necessária porque o aplicativo é atualizado para uma versão mais recente. "os_update" é usada quando é necessário reiniciar porque o navegador/SO é atualizado para uma versão mais recente. 'periódico' é 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.

&quot;os_update&quot;
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 superior

A arquitetura do processador da máquina.

Enumeração

"arm"
Especifica a arquitetura do processador como um 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.

PlatformInfo

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

Propriedades

  • A arquitetura do processador da máquina.

  • nacl_arch

    PlatformNaclArch

    A arquitetura do cliente nativo. Ele pode ser diferente do arco em algumas plataformas.

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

PlatformNaclArch

Chrome 44 ou superior

A arquitetura do cliente nativo. Ele pode ser diferente do arco em algumas plataformas.

Enumeração

"arm"
Especifica a arquitetura do cliente nativo como um braço.

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

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 do Chrome.

"linux"
Especifica o sistema operacional Linux.

&quot;openbsd&quot;
Especifica o sistema operacional OpenBSD.

"fuchsia"
Especifica o sistema operacional Fuchsia.

Port

Um objeto que permite 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

    Evento<functionvoidvoid>

    Disparado quando a porta é desconectada das outras extremidades. runtime.lastError poderá ser definido se a porta for desconectada por um erro. Se a porta for fechada por disconnect, esse evento é disparado apenas na outra extremidade. Este 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

    Evento<functionvoidvoid>

    Este evento é disparado 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 um

      • porta

        Port

  • remetente

    MessageSender opcional

    Essa propriedade estará presente apenas nas portas transmitidas para os 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 evento novo é 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, será gerado um erro.

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

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

    • mensagem

      qualquer um

      Chrome 52 ou superior

      A mensagem a ser enviada. Esse objeto precisa ser compatível com JSON.

RequestUpdateCheckStatus

Chrome 44 ou superior

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

Enumeração

"boundd"
Especifica que a verificação de status foi limitada. Isso pode ocorrer 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, será indefinido. Isso é definido apenas dentro do 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 gerou o erro. As funções da API que retornam promessas não definem essa propriedade.

Tipo

objeto

Propriedades

  • mensagem

    string opcional

    Detalhes sobre o erro ocorrido.

Métodos

connect()

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

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

Parâmetros

  • extensionId

    string opcional

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

  • connectInfo

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Define se o ID do canal TLS será transmitido para onConnectExternal para processos que estejam detectando o evento de conexão.

    • nome

      string opcional

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

Retorna

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

Parâmetros

  • aplicativo

    string

    O nome do aplicativo registrado ao qual se conectar.

Retorna

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

getBackgroundPage()

Promessa Somente primeiro plano 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Recupera a "janela" do JavaScript. para a página de fundo executada dentro da extensão ou do aplicativo atual. Se a página de fundo for uma página de evento, o sistema garantirá o carregamento dela antes de chamar o callback. Se não houver uma página de plano de fundo, um erro será definido.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Janela opcional

      A "janela" do JavaScript para a página de plano de fundo.

Retorna

  • Promise&lt;Window | indefinido>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getContexts()

Promessa Chrome 116 ou versões mais recentes MV3 ou mais 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

Parâmetros

  • filtro

    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.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (contexts: ExtensionContext[]) => void

Retorna

  • Promise&lt;ExtensionContext[]&gt;

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getManifest()

chrome.runtime.getManifest()

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

Retorna

  • objeto

    Detalhes do manifesto.

getPackageDirectoryEntry()

Promessa Somente primeiro plano 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Retorna uma DirectoryEntry para o diretório do pacote.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Retorna

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getPlatformInfo()

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

Retorna informações sobre a plataforma atual.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (platformInfo: PlatformInfo) => void

Retorna

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Parâmetros

  • caminho

    string

    Um caminho para um recurso dentro de um aplicativo/extensão expresso relativo ao respectivo diretório de instalação.

Retorna

  • string

    O URL totalmente qualificado para o recurso.

openOptionsPage()

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

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

O comportamento exato pode depender da chave [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) ou [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) do manifesto ou do suporte do Chrome no momento. Por exemplo, a página pode ser aberta em uma nova guia, em chrome://extensions, em um app ou apenas focar em uma página de opções aberta. Isso nunca recarrega a página do autor da chamada.

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

reload()

chrome.runtime.reload()

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()

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

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

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

Esse método só é apropriado para chamadas em circunstâncias muito limitadas, por exemplo, se sua extensão se comunica com um serviço de back-end e ele determinou que a versão da extensão de cliente está muito desatualizada e você gostaria de solicitar a atualização do usuário. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer de repetição, provavelmente serve apenas para desperdiçar recursos do cliente, da rede e do servidor.

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: object) => void

    • resultado

      objeto

      Chrome 109 ou versões mais recentes

      Objeto RequestUpdateCheckResult que contém o status da verificação de atualização e todos os detalhes do resultado, se houver uma atualização disponível

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

      • version

        string opcional

        Se uma atualização estiver disponível, esse item contém a versão da atualização disponível.

Retorna

  • Promise&lt;object&gt;

    Chrome 109 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

restart()

chrome.runtime.restart()

Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque. Caso contrário, será um ambiente autônomo.

restartAfterDelay()

Promessa Chrome 53 ou versão mais recente 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Reinicia o dispositivo ChromeOS quando o aplicativo é executado no modo quiosque após os segundos especificados. Se a chamada for chamada novamente antes do término desse período, a reinicialização será adiada. Se chamada com um valor de -1, a reinicialização será cancelada. É um ambiente autônomo no modo não quiosque. Ela só pode ser chamada repetidamente pela primeira extensão para invocar essa API.

Parâmetros

  • segundos

    number

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

sendMessage()

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

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

Parâmetros

  • extensionId

    string opcional

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

  • mensagem

    qualquer um

    A mensagem a ser enviada. Essa mensagem deve ser um objeto separável em JSON.

  • opções

    objeto opcional

    • includeTlsChannelId

      booleano opcional

      Indica se o ID do canal TLS será transmitido para onMessageExternal para processos que estejam detectando o evento de conexão.

  • callback

    função opcional

    Chrome 99 ou versão mais recente

    O parâmetro callback tem esta aparência: 

    (response: any) => void

    • resposta

      qualquer um

      O objeto de resposta JSON enviado pelo gerenciador da mensagem. Se ocorrer um erro ao se conectar à extensão, o callback será chamado sem argumentos, e runtime.lastError será definido como a mensagem de erro.

Retorna

  • Promessa<qualquer>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

sendNativeMessage()

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

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

Parâmetros

  • aplicativo

    string

    O nome do host de mensagens nativas.

  • mensagem

    objeto

    A mensagem que será transmitida para o host de mensagens nativas.

  • callback

    função opcional

    Chrome 99 ou versões mais recentes

    O parâmetro callback tem esta aparência: 

    (response: any) => void

    • resposta

      qualquer um

      A mensagem de resposta enviada pelo host de mensagens nativas. Se ocorrer um erro ao se conectar ao host de mensagens nativas, o callback será chamado sem argumentos, e runtime.lastError será definido como a mensagem de erro.

Retorna

  • Promessa<qualquer>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

setUninstallURL()

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

Define o URL que 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

    O URL que será aberto após a desinstalação da extensão. Esse URL deve ter um esquema http: ou https:. Defina uma string vazia para não abrir uma nova guia após a desinstalação.

  • callback

    função opcional

    Chrome 45 ou superior

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 é instalado 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 de 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 conectável externamente.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (port: Port) => void

onConnectNative

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

Disparado quando uma conexão é feita de um aplicativo nativo. Este evento requer a permissão "nativeMessaging". Ela só é compatível com o ChromeOS.

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 a extensão é atualizada para uma nova versão e quando o Google 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 importada que foi atualizada. Isso está presente apenas se "motivo" é "shared_module_update".

      • previousVersion

        string opcional

        Indica a versão anterior da extensão, que acabou de ser atualizada. Isso está presente apenas se "motivo" é "update".

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

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 um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | indefinido

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 um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | indefinido

onRestartRequired

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

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

Parâmetros

onStartup

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

Disparado quando um perfil que tem essa extensão instalada primeiro é iniciado. Este evento não é disparado quando um perfil de navegação anônima é iniciado, mesmo que esta extensão esteja operando no modo "dividir" o modo de navegação anônima.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onSuspend

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

É enviado à página do evento pouco antes de ser descarregado. Isso dá à extensão a oportunidade de fazer uma limpeza. Como a página está sendo descarregada, não há garantia de que nenhuma operação assíncrona iniciada durante o processamento desse evento seja concluída. Se ocorrer mais atividade na página do evento antes de ela ser descarregada, 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 é instalado imediatamente porque o app está em execução no momento. Se você não fizer nada, a atualização será instalada na próxima vez que a página de segundo plano for descarregada. Se quiser que ela seja instalada antes, chame explicitamente chrome.runtime.reload(). Se sua extensão estiver usando uma página de 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 reinicialização do Chrome. Se nenhum gerenciador estiver detectando esse evento e sua extensão tiver uma página de segundo plano persistente, ela 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 ou versões mais recentes MV3+ 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Disparado quando uma conexão é feita a partir 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 ou versões mais recentes 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 um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem esta aparência: 

      () => void

    • retorna

      boolean | indefinido