chrome.runtime

refresh date: 2026-09-25 robots: noindex

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.

Visão geral

A API Runtime oferece métodos para dar suporte a várias áreas de funcionalidade 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, sua extensão pode transmitir mensagens para apps nativos no dispositivo do usuário usando connectNative() e sendNativeMessage().
Como acessar metadados de extensão e plataforma
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().
Gerenciar o ciclo de vida e as opções da extensão
Essas propriedades permitem que você realize algumas metaoperações na extensão e mostre 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 utilitários 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 quiosque. Os métodos nessa categoria incluem restart e restartAfterDelay.

Permissões

A maioria dos métodos na API Runtime não exige permissão, exceto sendNativeMessage e connectNative, que exigem a permissão nativeMessaging.

Manifesto

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

manifest.json:

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

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 pela Web e que, normalmente, os scripts de conteúdo são responsáveis por injetar recursos da 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 pela 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 do service worker para um script de conteúdo

É 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 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, ela transmite uma mensagem get-user-data 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);
});

background.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Coletar feedback sobre a desinstalação

Muitas extensões usam pesquisas pós-desinstalação para entender como 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 de extensões

Consulte a demonstração do Manifest V3: recursos acessíveis pela Web para mais exemplos da API Runtime.

Tipos

ContextFilter

Chrome 114+

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

  • incognito

    booleano opcional

  • tabIds

    number[] opcional

  • windowIds

    number[] opcional

ContextType

Chrome 114+

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+

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

Propriedades

  • contextId

    string

    Um identificador exclusivo para esse contexto

  • contextType

    ContextType

    O tipo de contexto correspondente.

  • 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 esse contexto ou -1 se esse contexto não estiver hospedado em um frame.

  • incognito

    booleano

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

  • tabId

    número

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

  • windowId

    número

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

ExtensionLoadDetails

Chrome 157 ou mais recente

Detalhes sobre o evento de carregamento da extensão.

Propriedades

  • previousVersion

    string opcional

    Indica a versão anterior da extensão. Isso só estará presente se "reason" for "update" ou "enable". Se "reason" for "update", essa será a versão da extensão antes da atualização. Se "reason" for "enable", essa será a versão atual da extensão.

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

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+

    Um UUID do documento que abriu a conexão.

  • documentLifecycle

    string opcional

    Chrome 106+

    O ciclo de vida em que o documento que abriu a conexão está 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 optional

    O frame que abriu a conexão. 0 para frames de nível superior, positivo para frames filhos. 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+

    O nome do app 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. Ela pode variar da propriedade url (por exemplo, about:blank) ou ser opaca (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 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, será o URL do iframe, não o URL da página que o hospeda.

OnInstalledReason

Chrome 44+

O motivo pelo qual este 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 para um módulo compartilhado.

OnLoadedReason

Chrome 157 ou mais recente

O motivo pelo qual este evento está sendo enviado.

Enumeração

"install"
A extensão foi instalada recentemente.

"update"
A extensão foi recarregada após uma atualização.

"browser_update"
O navegador foi atualizado para uma nova versão.

"enable"
A extensão foi reativada de um estado desativado.

"startup"
A extensão está sendo carregada durante a inicialização do navegador.

"reload"
A extensão foi recarregada (por exemplo, via chrome.runtime.reload() ou o usuário recarregou manualmente a extensão).

OnRestartRequiredReason

Chrome 44+

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 permitido 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+

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

    Descontinuado desde o Chrome 149

    Este atributo foi descontinuado após a remoção completa do Native Client.

    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+ Descontinuado desde o Chrome 149

Este tipo enumerado foi descontinuado após a remoção completa do Native Client.

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+

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 da outra extremidade. runtime.lastError poderá ser definido se a porta tiver sido desconectada por um erro. Se a porta for fechada por 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 é semelhante a: 

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

    • callback

      função

      O parâmetro callback é semelhante a: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

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

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

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

    • callback

      função

      O parâmetro callback é semelhante a: 

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

      • mensagem

        qualquer

      • porta

        Porta

  • remetente

    MessageSender opcional

    Essa propriedade só vai 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: 

    () => {...}

  • postMessage

    void

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

    A função postMessage é semelhante a: 

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

    • mensagem

      qualquer

      Chrome 52+

      A mensagem a ser enviada. Esse objeto precisa ser JSON-ificável.

RequestUpdateCheckStatus

Chrome 44+

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

Enumeração

"throttled"
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, indefinido. Isso é definido apenas 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 de 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 se você estiver enviando mensagens de uma página da Web para mensagens da Web.

  • connectInfo

    objeto optional

    • includeTlsChannelId

      booleano opcional

      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 pela qual as mensagens podem ser enviadas e recebidas. O evento onDisconnect da porta será acionado se a extensão não existir.

connectNative()

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

Conecta-se a um app 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()

Promise Somente em primeiro plano Descontinuado desde o Chrome 133
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

As páginas de plano de fundo não existem nas extensões MV3.

Recupera o objeto "window" do JavaScript para a página de plano de fundo em execução na extensão/no app atual. Se a página de plano de fundo 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 plano de fundo, um erro será definido.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Janela opcional

      O objeto "window" do JavaScript para a página de plano de fundo.

Retorna

  • Promise<Window | undefined>

    Chrome 99+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

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

Retorna um DirectoryEntry para o diretório do pacote.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Retorna

  • Promise<DirectoryEntry>

    Chrome 122+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getPlatformInfo()

Promessa 
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

Retorna informações sobre a plataforma atual.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (platformInfo: PlatformInfo) => void

Retorna

  • Promise<PlatformInfo>

    Chrome 99+

    Promessa que é resolvida com informações sobre a plataforma atual.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 para o recurso.

getVersion()

Chrome 143+ 
chrome.runtime.getVersion(): string

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

Retorna

  • string

    A versão da extensão.

openOptionsPage()

Promessa 
chrome.runtime.openOptionsPage(
  callback?: function,
): 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 em uma página de opções aberta. Ela nunca vai fazer 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.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Promessa 
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

Solicita uma verificação de atualização imediata 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ó é apropriado para chamadas em circunstâncias muito limitadas, como quando a extensão se comunica com um serviço de back-end que determinou que a versão da extensão do cliente está muito desatualizada e você quer solicitar que o usuário faça uma atualização. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer repetitivo, provavelmente só serve 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 optional

    O parâmetro callback é semelhante a: 

    (result: object) => void

    • resultado

      objeto

      Chrome 109+

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

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

      • versão

        string opcional

        Se houver uma atualização disponível, esse campo vai conter a versão dela.

Retorna

  • Promise<object>

    Chrome 109+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

restart()

chrome.runtime.restart(): void

Reinicie o dispositivo ChromeOS quando o app estiver no modo quiosque. Caso contrário, não haverá operação.

restartAfterDelay()

Promise Chrome 53+ 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

Reinicia o dispositivo ChromeOS quando o app é executado no modo quiosque após os segundos especificados. Se for chamada novamente antes do fim do tempo, a reinicialização será adiada. Se for chamada com o valor -1, a reinicialização será cancelada. É uma operação sem efeito no modo quiosque. Só é permitido que ela seja chamada repetidamente pela primeira extensão que invocar essa API.

Parâmetros

  • segundos

    número

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

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99+

    Promessa que é resolvida quando uma solicitação de reinicialização é reprogramada.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

sendMessage()

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

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

Parâmetros

  • extensionId

    string opcional

    O ID da extensão para onde a mensagem será enviada. Se omitido, a mensagem será enviada para sua própria extensão/app. Obrigatório ao enviar 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 optional

    • includeTlsChannelId

      booleano opcional

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

  • callback

    função optional

    Chrome 99+

    O parâmetro callback é semelhante a: 

    (response: any) => void

    • resposta

      qualquer

      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+

    O suporte a promessas foi adicionado para contextos de extensão no Chrome 99. Ao se comunicar de uma página da Web com uma extensão, as promessas estão disponíveis no Chrome 118.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

sendNativeMessage()

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

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

Parâmetros

  • aplicativo

    string

    O nome do host de mensagens nativas ou os detalhes do destino.

  • mensagem

    objeto

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

  • callback

    função optional

    Chrome 99+

    O parâmetro callback é semelhante a: 

    (response: any) => void

    • resposta

      qualquer

      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

  • Promise<any>

    Chrome 99+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setUninstallURL()

Promessa 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): 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 após a desinstalação da extensão. Esse URL precisa 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 optional

    Chrome 45+

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 99+

    Promessa que é resolvida quando o URL de desinstalação é definido. Se o URL fornecido for inválido, a promessa será rejeitada.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 é semelhante a: 

    () => 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 é semelhante a: 

    (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 que pode ser conectado externamente.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (port: Port) => void

onConnectNative

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

Acionado quando uma conexão é feita em um app nativo. Esse evento requer a permissão "nativeMessaging". Ele só é compatível com o ChromeOS.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (port: Port) => void

onEnabled

Chrome 155+ 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

Disparado quando uma extensão passa de um estado desativado para um estado ativado.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onExtensionLoaded

Chrome 157 ou mais recente 
chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

Acionado quando a extensão é adicionada ao conjunto de extensões ativas. Isso pode ocorrer em vários cenários: quando uma extensão é instalada pela primeira vez, atualizada para uma nova versão, reativada após ser desativada, recarregada, carregada durante a inicialização do navegador ou carregada quando o navegador é atualizado para uma nova versão.

Parâmetros

onInstalled

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

Disparado 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 é semelhante a: 

    (details: object) => void

    • detalhes

      objeto

      • ID

        string opcional

        Indica o ID da extensão de módulo compartilhado importada 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 este evento está sendo enviado.

onMessage

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

Disparado quando uma mensagem é enviada de runtime.sendMessage ou tabs.sendMessage.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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

    • mensagem

      qualquer

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse é semelhante a: 

      (response?: any) => void

      • resposta

        any optional

        A resposta a ser retornada ao remetente da mensagem.

    • retorna

      boolean | Promise<any> | 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 é semelhante a: 

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

    • mensagem

      qualquer

    • remetente

      MessageSender

    • sendResponse

      função

      O parâmetro sendResponse é semelhante a: 

      (response?: any) => void

      • resposta

        any optional

        A resposta a ser retornada ao remetente da mensagem.

    • retorna

      boolean | Promise<any> | undefined

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 assim que possível 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 é acionado apenas para aplicativos de quiosque do ChromeOS.

Parâmetros

onStartup

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

Disparado quando um perfil que tem 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 é semelhante a: 

    () => void

onSuspend

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

Enviado para a página de eventos 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 as operações assíncronas iniciadas durante o processamento desse evento serão concluídas. Se mais atividades para a página de eventos ocorrerem 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 é semelhante a: 

    () => 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 é semelhante a: 

    () => 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 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 gerenciador estiver detectando esse evento e sua 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 é semelhante a: 

    (details: object) => void

    • detalhes

      objeto

      • versão

        string

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