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 as 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ões e plataformas
Esses métodos permitem recuperar vários metadados específicos sobre a extensão e a plataforma. Os métodos nessa categoria incluem getManifest() e getPlatformInfo().
Como gerenciar o ciclo de vida e as opções da extensão
Com essas propriedades, você pode 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 fornecem utilitários, como a conversão de representações de recursos internos para 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 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á 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 da Web e que, normalmente, os scripts de conteúdo são responsáveis por injetar recursos de extensão.

Neste exemplo, a extensão vai adicionar 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 worker de serviço

É 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 do navegador abertas para a 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 worker de serviço da extensão para inicializar a interface. Para receber esses dados, ele transmite a mensagem get-user-data definida pelo desenvolvedor ao worker de serviço e 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 a extensão pode atender melhor os 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 a demonstração do Manifest V3: recursos acessíveis na Web para conferir mais exemplos da API Runtime.

Tipos

ContextFilter

Chrome 114 e versões mais recentes

Um filtro para corresponder a determinados contextos de extensão. Os contextos correspondentes precisam corresponder a todos os filtros especificados. Qualquer filtro que não seja 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 e versões mais recentes

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 worker de serviço.

"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 e versões mais recentes

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

Propriedades

  • contextId

    string

    Um identificador exclusivo para esse contexto

  • contextType

    ContextType

    O tipo de contexto ao qual ele corresponde.

  • documentId

    string opcional

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

  • documentOrigin

    string opcional

    A origem do documento associado a esse contexto ou indefinido 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

    number

    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

    number

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

  • windowId

    number

    O ID da janela para esse contexto ou -1 se esse 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 e versões mais recentes

    Um UUID do documento que abriu a conexão.

  • documentLifecycle

    string opcional

    Chrome 106 e 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 filhos. Ele 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 e versões mais recentes

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

  • origem

    string opcional

    Chrome 80 e versões mais recentes

    A origem da página ou do frame que abriu a conexão. Ele pode variar de acordo com a propriedade de URL (por exemplo, "about:blank") ou pode ser opaco (por exemplo, iframes em sandbox). Isso é útil para identificar se a origem é confiável se não for 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 receptor 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, ele será o URL do iframe, não o URL da página que o hospeda.

OnInstalledReason

Chrome 44 e versões mais recentes

O motivo pelo qual o 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 da 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 e versões mais recentes

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

"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 e versões mais recentes

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.

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. Isso pode ser diferente de arch em algumas plataformas.

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

PlatformNaclArch

Chrome 44 e versões mais recentes

A arquitetura do cliente nativo. Isso pode ser diferente de arch 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 e versões mais recentes

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.

"fuchsia"
Especifica o sistema operacional Fuchsia.

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

    Evento<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 por desconexão, esse evento será somente acionado na outra extremidade. Esse evento é acionado no máximo uma vez (consulte também Vida útil da porta).

    A função onDisconnect.addListener é semelhante a esta: 

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

    • callback

      função

      O parâmetro callback tem este formato: 

      (port: Port) => void

  • onMessage

    Evento<functionvoidvoid>

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

    A função onMessage.addListener é semelhante a esta: 

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

    • callback

      função

      O parâmetro callback tem este formato: 

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

      • mensagem

        qualquer um

      • porta

        Port

  • remetente

    MessageSender opcional

    Essa propriedade só estará presente 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 para ela.

    A função disconnect é semelhante a esta: 

    () => {...}

  • postMessage

    void

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

    A função postMessage é semelhante a esta: 

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

    • mensagem

      qualquer um

      Chrome 52 e versões mais recentes

      A mensagem a ser enviada. Esse objeto precisa ser JSONificável.

RequestUpdateCheckStatus

Chrome 44 e versões mais recentes

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

Enumeração

"Limitada"
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/do app.

Tipo

string

lastError

Será preenchido com uma mensagem de erro se a chamada de uma função da API falhar. Caso contrário, será indefinido. Isso é definido apenas no escopo do callback da 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 da 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,
)

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 conectado. Se omitido, uma tentativa de conexão será feita com 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

      Indica se o ID do canal TLS será transmitido para onConnectExternal para processos que estão 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 por onde 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,
)

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

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

Recupera o objeto "window" do JavaScript para a página em segundo plano em execução dentro da extensão/atualização 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 de segundo plano, um erro será definido.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Janela opcional

      O objeto "window" do JavaScript para a página em segundo plano.

Retorna

  • Promise<Window | undefined>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getContexts()

Promessa Chrome 116+ MV3+ 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Busca informações sobre contextos ativos associados a essa 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 este formato: 

    (contexts: ExtensionContext[]) => void

Retorna

  • Promise<ExtensionContext[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getManifest()

chrome.runtime.getManifest()

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

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

Retorna uma entrada de diretório para o diretório do pacote.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Retorna

  • Promise<DirectoryEntry>

    Chrome 122 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

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 este formato: 

    (platformInfo: PlatformInfo) => void

Retorna

  • Promise<PlatformInfo>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getURL()

chrome.runtime.getURL(
  path: 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 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 ou options_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 pode apenas focar uma página de opções aberta. Ela nunca vai causar a atualização da 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 conseguir criar uma por algum motivo, o callback vai definir lastError.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

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 precisa usar esse método, já que o Chrome já faz verificações automáticas a cada poucas horas, e você pode acompanhar o evento runtime.onUpdateAvailable sem precisar chamar requestUpdateCheck.

Esse método só é adequado para chamar em circunstâncias muito limitadas, como quando sua extensão se comunica com um serviço de back-end e ele determina que a versão da extensão do cliente está muito desatualizada e você quer solicitar que o usuário faça a atualização. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer recorrente, 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 retorna as duas propriedades como argumentos separados transmitidos ao callback.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: object) => void

    • resultado

      objeto

      Chrome 109 e 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, ela vai conter a versão da atualização disponível.

Retorna

  • Promise<object>

    Chrome 109 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

restart()

chrome.runtime.restart()

Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque. Caso contrário, não vai funcionar.

restartAfterDelay()

Promessa Chrome 53+ 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Reinicia o dispositivo ChromeOS quando o app é executado no modo quiosque após os segundos especificados. Se for chamada novamente antes do término do tempo, a reinicialização será adiada. Se for chamado com um valor de -1, a reinicialização será cancelada. Não há operação no modo que 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 da reinicialização do dispositivo ou -1 para cancelar uma reinicialização programada.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

sendMessage()

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

Envia uma única mensagem para listeners de eventos na sua extensão ou em uma extensão/um app diferente. É semelhante a runtime.connect, mas envia apenas uma mensagem com uma resposta opcional. Se o envio for para sua extensão, o evento runtime.onMessage será acionado em todos os frames da sua extensão (exceto o frame 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 a scripts de conteúdo, use tabs.sendMessage.

Parâmetros

  • extensionId

    string opcional

    O ID da extensão para a qual a mensagem será enviada. 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 na Web.

  • mensagem

    qualquer um

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

  • opções

    objeto opcional

    • includeTlsChannelId

      booleano opcional

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

  • callback

    função opcional

    Chrome 99 e versões mais recentes

    O parâmetro callback tem este formato: 

    (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

  • Promise<any>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

sendNativeMessage()

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

Enviar 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 nativo.

  • callback

    função opcional

    Chrome 99 e versões mais recentes

    O parâmetro callback tem este formato: 

    (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 nativo, o callback será chamado sem argumentos e runtime.lastError será definido como a mensagem de erro.

Retorna

  • Promise<any>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setUninstallURL()

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

Define o URL que será visitado durante 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 após a desinstalação da extensão. Esse URL precisa ter um esquema http: ou https:. Definir uma string vazia para não abrir uma nova guia na desinstalação.

  • callback

    função opcional

    Chrome 45 e versões mais recentes

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 99 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

Eventos

onBrowserUpdateAvailable

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

Use runtime.onRestartRequired.

É acionado quando uma atualização do Chrome está disponível, mas não é instalada imediatamente porque é necessária uma reinicialização do navegador.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => void

onConnect

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (port: Port) => void

onConnectExternal

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

É acionado quando uma conexão é feita de outra extensão (por runtime.connect) ou de um site da Web com conexão externa.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (port: Port) => void

onConnectNative

Chrome 76 e versões mais recentes 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Acionado quando uma conexão é feita de um aplicativo nativo. Esse evento requer a permissão "nativeMessaging". Ele só é compatível com o Chrome OS.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (port: Port) => void

onInstalled

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

É acionado quando a extensão é instalada pela primeira vez, quando é 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 este formato: 

    (details: object) => void

    • detalhes

      objeto

      • id

        string opcional

        Indica o ID da extensão do módulo compartilhado importado que foi atualizada. Isso só vai 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ó vai estar presente se "reason" for "update".

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

onMessage

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

É acionado 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 este formato: 

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

    • mensagem

      qualquer um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem este formato: 

      () => void

    • retorna

      booleano | indefinido

onMessageExternal

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

É acionado 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 este formato: 

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

    • mensagem

      qualquer um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem este formato: 

      () => void

    • retorna

      booleano | indefinido

onRestartRequired

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

É acionado quando um app ou o dispositivo em que ele é executado precisa ser reiniciado. O app precisa fechar todas as janelas no momento mais conveniente para 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ó é acionado para apps de quiosque do Chrome OS.

Parâmetros

onStartup

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

É acionado 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 "dividida".

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => void

onSuspend

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

É enviado para a 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 removida, não há garantia de que as operações assíncronas iniciadas durante o processamento desse evento serão concluídas. Se mais atividade para a página do evento ocorrer antes que ela seja descarregada, o evento onSuspendCanceled será enviado e a página não será descarregada.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => void

onSuspendCanceled

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

É enviado após onSuspend para indicar que o app não será removido.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => void

onUpdateAvailable

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

É acionado 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 você quiser que ela seja instalada mais cedo, 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 reinicialização do Chrome. Se nenhum manipulador estiver detectando esse evento e a extensão tiver uma página de 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 este formato: 

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (port: Port) => void

onUserScriptMessage

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • mensagem

      qualquer um

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse tem este formato: 

      () => void

    • retorna

      booleano | indefinido