chrome.runtime (original) (raw)

Ir para o conteúdo principal

chrome.runtime

Descrição

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

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

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

manifest.json:

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

Conceitos e uso

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

Transmissão de mensagens

Sua extensão pode se comunicar com diferentes contextos dentro dela e também com outras extensões usando estes métodos e eventos:connect(),onConnect,onConnectExternal,sendMessage(),onMessage eonMessageExternal. Além disso, a extensão pode transmitir mensagens para aplicativos nativos no dispositivo do usuário usandoconnectNative() esendNativeMessage().

Como acessar metadados de extensão e plataforma

Esses métodos permitem recuperar várias partes específicas de metadados sobre a extensão e a plataforma. Os métodos nessa categoria incluem getManifest() e getPlatformInfo().

Gerenciar o ciclo de vida e as opções de extensão

Essas propriedades permitem realizar algumas metaoperações na extensão e mostrar a página de opções. Os métodos e eventos nessa categoria incluemonInstalled,onStartup,openOptionsPage(),reload(),requestUpdateCheck() esetUninstallURL().

Utilitários auxiliares

Esses métodos oferecem utilidade, como a conversão de representações de recursos internos em formatos externos. Os métodos nessa categoria incluemgetURL().

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 incluemrestart() erestartAfterDelay()`.

Comportamento de extensões descompactadas

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

Casos de uso

Adicionar uma imagem a uma página da Web

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

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

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

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

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

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

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

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

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

Coletar feedback sobre a desinstalação

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

background.js:

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

Exemplos

Consulte a demonstração de recursos acessíveis da Web do Manifest V3 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. Assim, um filtro de `{}` vai corresponder a todos os contextos disponíveis.

Propriedades

ContextType

Chrome 114 ou mais recente

Enumeração

"TAB"
Especifica o tipo de contexto como uma guia

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

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

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

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

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

ExtensionContext

Chrome 114 ou mais recente

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

Propriedades

MessageSender

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

Propriedades

OnInstalledReason

Chrome 44 ou mais recente

O motivo pelo qual esse evento está sendo enviado.

Enumeração

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

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

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

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

OnRestartRequiredReason

Chrome 44 ou mais recente

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

Enumeração

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

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

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

PlatformArch

Chrome 44 ou mais recente

A arquitetura do processador da máquina.

Enumeração

"arm"
Especifica a arquitetura do processador como arm.

"arm64"
Especifica a arquitetura do processador como arm64.

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

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

"mips"
Especifica a arquitetura do processador como mips.

"mips64"
Especifica a arquitetura do processador como mips64.

"riscv64"
Especifica a arquitetura do processador como riscv64.

PlatformInfo

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

Propriedades

PlatformNaclArch

Chrome 44 ou mais recente

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

Enumeração

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

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

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

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

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

PlatformOs

Chrome 44 ou mais recente

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

Enumeração

"mac"
Especifica o sistema operacional MacOS.

"win"
Especifica o sistema operacional Windows.

"android"
Especifica o sistema operacional Android.

"cros"
Especifica o sistema operacional Chrome.

"linux"
Especifica o sistema operacional Linux.

"openbsd"
Especifica o sistema operacional OpenBSD.

Port

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

Propriedades

RequestUpdateCheckStatus

Chrome 44 ou mais recente

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

Enumeração

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

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

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

Propriedades

lastError

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

Propriedades

Métodos

connect()

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

Tenta conectar listeners em uma extensão (como a página em segundo plano) ou em outros apps/extensões. 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

Retorna

connectNative()

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

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

Parâmetros

Retorna

getBackgroundPage()

Somente em primeiro plano Suspenso desde o Chrome 133

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

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

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

Retorna

getContexts()

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

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

Parâmetros

Retorna

getManifest()

chrome.runtime.getManifest(): object

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

Retorna

getPackageDirectoryEntry()

Somente em primeiro plano

chrome.runtime.getPackageDirectoryEntry(): Promise

Retorna um DirectoryEntry para o diretório do pacote.

Retorna

getPlatformInfo()

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

Retorna informações sobre a plataforma atual.

Retorna

getURL()

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

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

Parâmetros

Retorna

getVersion()

Chrome 143 ou mais recente

chrome.runtime.getVersion(): string

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

Retorna

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise

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

O comportamento exato pode depender da chave options_ui ou options_page do manifesto ou do que o Chrome oferece suporte no momento. Por exemplo, a página pode ser aberta em uma nova guia, em chrome://extensions, em um app ou apenas focar uma página de opções aberta. Isso nunca 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.

Retorna

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise

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

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

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

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

Retorna

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

Chrome 53 ou mais recente

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise

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

Parâmetros

Retorna

sendMessage()

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

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

Parâmetros

Retorna

sendNativeMessage()

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

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

Parâmetros

Retorna

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise

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

Retorna

Eventos

onBrowserUpdateAvailable

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

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

onConnectExternal

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

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

Parâmetros

onConnectNative

Chrome 76 ou mais recente

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

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

Parâmetros

onInstalled

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

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

Parâmetros

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

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

onRestartRequired

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

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

Parâmetros

onStartup

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

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

Parâmetros

onSuspend

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

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

Parâmetros

onSuspendCanceled

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

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

Parâmetros

onUpdateAvailable

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

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

Parâmetros

onUserScriptConnect

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

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

Parâmetros

onUserScriptMessage

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

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

Parâmetros

Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.

Última atualização 2024-02-06 UTC.