browser.runtime

Descrizione

Utilizza l'API chrome.runtime per recuperare il service worker, restituire i dettagli del manifest e ascoltare e rispondere agli eventi nel ciclo di vita dell'estensione. Puoi anche utilizzare questa API per convertire il percorso relativo degli URL in URL completi.

La maggior parte dei membri di questa API non richiede autorizzazioni. Questa autorizzazione è necessaria per connectNative(), sendNativeMessage() e onNativeConnect.

L'esempio seguente mostra come dichiarare l'autorizzazione "nativeMessaging" nel file manifest:

manifest.json:

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

Concetti e utilizzo

L'API Runtime fornisce metodi per supportare una serie di aree che le tue estensioni possono utilizzare:

Passaggio di messaggi
L'estensione può comunicare con contesti diversi al suo interno e anche con altre estensioni utilizzando questi metodi ed eventi: connect(), onConnect, onConnectExternal, sendMessage(), onMessage e onMessageExternal. Inoltre, l'estensione può trasmettere messaggi alle applicazioni native sul dispositivo dell'utente utilizzando connectNative() e sendNativeMessage().
Accesso ai metadati di estensioni e piattaforme
Questi metodi ti consentono di recuperare diversi metadati specifici sull'estensione e sulla piattaforma. I metodi di questa categoria includono getManifest() e getPlatformInfo().
Gestione del ciclo di vita e delle opzioni delle estensioni
Queste proprietà ti consentono di eseguire alcune meta-operazioni sull'estensione e di visualizzare la pagina delle opzioni. I metodi e gli eventi di questa categoria includono onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() e setUninstallURL().
Utilità di supporto
Questi metodi forniscono utilità come la conversione delle rappresentazioni delle risorse interne in formati esterni. I metodi di questa categoria includono getURL().
Utilità della modalità kiosk
Questi metodi sono disponibili solo su ChromeOS ed esistono principalmente per supportare le implementazioni kiosk. I metodi di questa categoria includono restart() e restartAfterDelay()`.

Comportamento delle estensioni non pacchettizzate

Quando un'estensione non pacchettizzata viene ricaricata, l'operazione viene considerata un aggiornamento. Ciò significa che l'evento browser.runtime.onInstalled verrà attivato con il motivo "update". Ciò include i casi in cui l'estensione viene ricaricata con browser.runtime.reload().

Casi d'uso

Aggiungi un'immagine a una pagina web

Affinché una pagina web possa accedere a un asset ospitato su un altro dominio, deve specificare l'URL completo della risorsa (ad es. <img src="https://example.com/logo.png">). Lo stesso vale per includere un asset di estensione in una pagina web. Le due differenze sono che gli asset dell'estensione devono essere esposti come risorse accessibili dal web e che in genere gli script dei contenuti sono responsabili dell'inserimento degli asset dell'estensione.

In questo esempio, l'estensione aggiungerà logo.png alla pagina in cui viene inserito lo script dei contenuti utilizzando runtime.getURL() per creare un URL completo. Ma prima, l'asset deve essere dichiarato come risorsa accessibile dal web nel file manifest.

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 = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

Invia dati da uno script di contenuti al service worker

È comune che gli script dei contenuti di un'estensione abbiano bisogno di dati gestiti da un'altra parte dell'estensione, come il service worker. Come due finestre del browser aperte sulla stessa pagina web, questi due contesti non possono accedere direttamente ai valori l'uno dell'altro. L'estensione può invece utilizzare il passaggio di messaggi per coordinare questi diversi contesti.

In questo esempio, lo script dei contenuti ha bisogno di alcuni dati dal service worker dell'estensione per inizializzare la sua UI. Per ottenere questi dati, trasmette il messaggio get-user-data definito dallo sviluppatore al service worker, che risponde con una copia delle informazioni dell'utente.

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.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'
};

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

Raccogli feedback sulla disinstallazione

Molte estensioni utilizzano sondaggi post-disinstallazione per capire come l'estensione potrebbe soddisfare meglio le esigenze degli utenti e migliorare la fidelizzazione. L'esempio seguente mostra come aggiungere questa funzionalità.

background.js:

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

Esempi

Per altri esempi di API di runtime, consulta la demo di Manifest V3 - Risorse accessibili dal web.

Tipi

ContextFilter

Chrome 114 e versioni successive

Un filtro da confrontare con determinati contesti di estensione. I contesti corrispondenti devono corrispondere a tutti i filtri specificati; qualsiasi filtro non specificato corrisponde a tutti i contesti disponibili. Pertanto, un filtro `{}` corrisponderà a tutti i contesti disponibili.

Proprietà

  • contextIds

    string[] facoltativo

  • contextTypes

    ContextType[] facoltativo

  • documentIds

    string[] facoltativo

  • documentOrigins

    string[] facoltativo

  • documentUrls

    string[] facoltativo

  • frameIds

    number[] facoltativo

  • incognito

    boolean facoltativo

  • tabIds

    number[] facoltativo

  • windowIds

    number[] facoltativo

ContextType

Chrome 114 e versioni successive

Enum

"TAB"
Specifica il tipo di contesto come scheda

"POPUP"
Specifica il tipo di contesto come finestra popup dell'estensione

"BACKGROUND"
Specifica il tipo di contesto come service worker.

"OFFSCREEN_DOCUMENT"
Specifica il tipo di contesto come documento fuori schermo.

"SIDE_PANEL"
Specifica il tipo di contesto come riquadro laterale.

"DEVELOPER_TOOLS"
Specifica il tipo di contesto come strumenti per sviluppatori.

ExtensionContext

Chrome 114 e versioni successive

Un contesto che ospita i contenuti dell'estensione.

Proprietà

  • contextId

    stringa

    Un identificatore univoco per questo contesto

  • contextType

    ContextType

    Il tipo di contesto a cui corrisponde.

  • documentId

    stringa facoltativa

    Un UUID per il documento associato a questo contesto o undefined se questo contesto non è ospitato in un documento.

  • documentOrigin

    stringa facoltativa

    L'origine del documento associato a questo contesto o undefined se il contesto non è ospitato in un documento.

  • documentUrl

    stringa facoltativa

    L'URL del documento associato a questo contesto o undefined se il contesto non è ospitato in un documento.

  • frameId

    numero

    L'ID del frame per questo contesto o -1 se questo contesto non è ospitato in un frame.

  • incognito

    booleano

    Indica se il contesto è associato a un profilo di navigazione in incognito.

  • tabId

    numero

    L'ID della scheda per questo contesto o -1 se questo contesto non è ospitato in una scheda.

  • windowId

    numero

    L'ID della finestra per questo contesto o -1 se questo contesto non è ospitato in una finestra.

ExtensionLoadDetails

Chrome 157+

Dettagli sull'evento di caricamento dell'estensione.

Proprietà

  • previousVersion

    stringa facoltativa

    Indica la versione precedente dell'estensione. Questo campo è presente solo se "reason" è "update" o "enable". Se "reason" è "update", si tratta della versione dell'estensione prima dell'aggiornamento. Se "reason" è "enable", questa è la versione corrente dell'estensione.

  • Il motivo per cui viene inviato questo evento.

MessageSender

Un oggetto contenente informazioni sul contesto dello script che ha inviato un messaggio o una richiesta.

Proprietà

  • documentId

    stringa facoltativa

    Chrome 106 e versioni successive

    Un UUID del documento che ha aperto la connessione.

  • documentLifecycle

    stringa facoltativa

    Chrome 106 e versioni successive

    Il ciclo di vita in cui si trova il documento che ha aperto la connessione al momento della creazione della porta. Tieni presente che lo stato del ciclo di vita del documento potrebbe essere cambiato dalla creazione della porta.

  • frameId

    number optional

    Il frame che ha aperto la connessione. 0 per i frame di primo livello, positivo per i frame secondari. Questo valore verrà impostato solo se è impostato tab.

  • id

    stringa facoltativa

    L'ID dell'estensione che ha aperto la connessione, se presente.

  • nativeApplication

    stringa facoltativa

    Chrome 74 e versioni successive

    Il nome dell'applicazione nativa che ha aperto la connessione, se presente.

  • origine

    stringa facoltativa

    Chrome 80 e versioni successive

    L'origine della pagina o del frame che ha aperto la connessione. Può variare in base alla proprietà url (ad es. about:blank) o può essere opaca (ad es. iframe con sandbox). Questo è utile per identificare se l'origine è attendibile se non possiamo stabilirlo immediatamente dall'URL.

  • tab

    Tab facoltativo

    tabs.Tab che ha aperto la connessione, se presente. Questa proprietà sarà presente solo quando la connessione è stata aperta da una scheda (inclusi gli script dei contenuti) e solo se il ricevitore è un'estensione, non un'app.

  • tlsChannelId

    stringa facoltativa

    L'ID canale TLS della pagina o del frame che ha aperto la connessione, se richiesto dall'estensione e se disponibile.

  • url

    stringa facoltativa

    L'URL della pagina o del frame che ha aperto la connessione. Se il mittente si trova in un iframe, sarà l'URL dell'iframe, non l'URL della pagina che lo ospita.

OnInstalledReason

Chrome 44 e versioni successive

Il motivo per cui viene inviato questo evento.

Enum

"install"
Specifica il motivo dell'evento come installazione.

"update"
Specifica il motivo dell'evento come aggiornamento dell'estensione.

"chrome_update"
Specifica il motivo dell'evento come aggiornamento di Chrome.

"shared_module_update"
Specifica il motivo dell'evento come aggiornamento di un modulo condiviso.

OnLoadedReason

Chrome 157+

Il motivo per cui viene inviato questo evento.

Enum

"install"
L'estensione è stata appena installata.

"update"
L'estensione è stata ricaricata dopo un aggiornamento.

"browser_update"
Il browser è stato aggiornato a una nuova versione.

"enable"
L'estensione è stata riattivata da uno stato di disattivazione.

"startup"
L'estensione viene caricata durante l'avvio del browser.

"reload"
L'estensione è stata ricaricata (ad es. tramite chrome.runtime.reload() o l'utente ha ricaricato manualmente l'estensione).

OnRestartRequiredReason

Chrome 44 e versioni successive

Il motivo per cui l'evento viene inviato. "app_update" viene utilizzato quando è necessario il riavvio perché l'applicazione è stata aggiornata a una versione più recente. "os_update" viene utilizzato quando il riavvio è necessario perché il browser/sistema operativo è stato aggiornato a una versione più recente. "periodic" viene utilizzato quando il sistema viene eseguito per un periodo di tempo superiore all'uptime consentito impostato nella policy aziendale.

Enum

"app_update"
Specifica il motivo dell'evento come aggiornamento dell'app.

"os_update"
Specifica il motivo dell'evento come aggiornamento del sistema operativo.

"periodic"
Specifica il motivo dell'evento come riavvio periodico dell'app.

PlatformArch

Chrome 44 e versioni successive

L'architettura del processore della macchina.

Enum

"arm"
Specifica l'architettura del processore come arm.

"arm64"
Specifica l'architettura del processore come arm64.

"x86-32"
Specifica l'architettura del processore come x86-32.

"x86-64"
Specifica l'architettura del processore come x86-64.

"mips"
Specifica l'architettura del processore come mips.

"mips64"
Specifica l'architettura del processore come mips64.

"riscv64"
Specifica l'architettura del processore come riscv64.

PlatformInfo

Un oggetto contenente informazioni sulla piattaforma corrente.

Proprietà

  • L'architettura del processore della macchina.

  • nacl_arch

    PlatformNaclArch facoltativo

    Ritirato da Chrome 149

    Questo attributo è deprecato in seguito alla rimozione completa di Native Client.

    L'architettura del client nativo. Questo potrebbe essere diverso da arch su alcune piattaforme.

  • Il sistema operativo su cui è in esecuzione Chrome.

PlatformNaclArch

Chrome 44 e versioni successive Ritirato da Chrome 149

Questo enum è deprecato in seguito alla rimozione completa di Native Client.

L'architettura client nativa. Potrebbe essere diverso da arch su alcune piattaforme.

Enum

"arm"
Specifica l'architettura del client nativo come arm.

"x86-32"
Specifica l'architettura Native Client come x86-32.

"x86-64"
Specifica l'architettura client nativa come x86-64.

"mips"
Specifica l'architettura del client nativo come mips.

"mips64"
Specifica l'architettura client nativa come mips64.

PlatformOs

Chrome 44 e versioni successive

Il sistema operativo su cui è in esecuzione Chrome.

Enum

"mac"
Specifica il sistema operativo MacOS.

"win"
Specifica il sistema operativo Windows.

"android"
Specifica il sistema operativo Android.

"cros"
Specifica il sistema operativo Chrome.

"linux"
Specifica il sistema operativo Linux.

"openbsd"
Specifica il sistema operativo OpenBSD.

Port

Un oggetto che consente la comunicazione bidirezionale con altre pagine. Per saperne di più, consulta Connessioni di lunga durata.

Proprietà

  • nome

    stringa

    Il nome della porta, come specificato nella chiamata a runtime.connect.

  • onDisconnect

    Event<functionvoidvoid>

    Attivato quando la porta viene scollegata dall'altra estremità. runtime.lastError può essere impostato se la porta è stata disconnessa a causa di un errore. Se la porta viene chiusa tramite disconnect, questo evento viene attivato solo sull'altra estremità. Questo evento viene attivato al massimo una volta (vedi anche Durata della porta).

    La funzione onDisconnect.addListener ha il seguente aspetto: 

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

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    Questo evento viene attivato quando postMessage viene chiamato dall'altra estremità della porta.

    La funzione onMessage.addListener ha il seguente aspetto: 

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

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

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

      • messaggio

        qualsiasi

      • porta

        Porta

  • mittente

    MessageSender facoltativo

    Questa proprietà sarà presente solo sulle porte passate ai listener onConnect/onConnectExternal/onConnectNative.

  • disconnetti

    void

    Scollega immediatamente la porta. La chiamata di disconnect() su una porta già disconnessa non ha alcun effetto. Quando una porta viene scollegata, non vengono inviati nuovi eventi a questa porta.

    La funzione disconnect ha il seguente aspetto: 

    () => {...}

  • postMessage

    void

    Invia un messaggio all'altra estremità della porta. Se la porta è scollegata, viene generato un errore.

    La funzione postMessage ha il seguente aspetto: 

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

    • messaggio

      qualsiasi

      Chrome 52 e versioni successive

      Il messaggio da inviare. Questo oggetto deve essere convertibile in JSON.

RequestUpdateCheckStatus

Chrome 44 e versioni successive

Risultato del controllo degli aggiornamenti.

Enum

"throttled"
Specifica che il controllo dello stato è stato limitato. Questo può accadere dopo controlli ripetuti in un breve periodo di tempo.

"no_update"
Specifica che non sono disponibili aggiornamenti da installare.

"update_available"
Specifica che è disponibile un aggiornamento da installare.

Proprietà

id

L'ID dell'estensione/app.

Tipo

stringa

lastError

Compilato con un messaggio di errore se la chiamata di una funzione API non va a buon fine; altrimenti non definito. Questo è definito solo nell'ambito del callback della funzione. Se viene generato un errore, ma non viene eseguito l'accesso a runtime.lastError all'interno del callback, nella console viene registrato un messaggio che elenca la funzione API che ha generato l'errore. Le funzioni API che restituiscono promise non impostano questa proprietà.

Tipo

oggetto

Proprietà

  • messaggio

    stringa facoltativa

    Dettagli sull'errore che si è verificato.

Metodi

connect()

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

Tenta di connettere i listener all'interno di un'estensione (ad esempio la pagina di sfondo) o di altre estensioni/app. Questo è utile per gli script dei contenuti che si connettono ai processi delle estensioni, per la comunicazione tra app/estensioni e per la messaggistica web. Tieni presente che questa operazione non si connette ad alcun listener in uno script di contenuti. Le estensioni possono connettersi agli script dei contenuti incorporati nelle schede tramite tabs.connect.

Parametri

  • extensionId

    stringa facoltativa

    L'ID dell'estensione a cui connettersi. Se omesso, verrà tentata una connessione con la tua estensione. Obbligatorio se invii messaggi da una pagina web per la messaggistica web.

  • connectInfo

    object facoltativo

    • includeTlsChannelId

      boolean facoltativo

      Indica se l'ID canale TLS verrà passato a onConnectExternal per i processi che sono in ascolto dell'evento di connessione.

    • nome

      stringa facoltativa

      Verrà passato a onConnect per i processi che sono in ascolto dell'evento di connessione.

Resi

  • Porta attraverso la quale è possibile inviare e ricevere messaggi. Se l'estensione non esiste, viene attivato l'evento onDisconnect della porta.

connectNative()

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

Si connette a un'applicazione nativa nella macchina host. Questo metodo richiede l'autorizzazione "nativeMessaging". Per saperne di più, consulta la sezione Native Messaging.

Parametri

  • applicazione

    stringa

    Il nome dell'applicazione registrata a cui connettersi.

Resi

  • Porta attraverso la quale è possibile inviare e ricevere messaggi con l'applicazione

getBackgroundPage()

Solo in primo piano Ritirato da Chrome 133
chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

Le pagine in background non esistono nelle estensioni MV3.

Recupera l'oggetto "window" JavaScript per la pagina di sfondo in esecuzione nell'estensione/app corrente. Se la pagina di sfondo è una pagina di eventi, il sistema si assicura che venga caricata prima di chiamare il callback. Se non esiste una pagina di sfondo, viene impostato un errore.

Resi

  • Promise<Window | undefined>

    Chrome 99 e versioni successive

getContexts()

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

Recupera informazioni sui contesti attivi associati a questa estensione

Parametri

  • filtro

    ContextFilter

    Un filtro per trovare i contesti corrispondenti. Un contesto corrisponde se corrisponde a tutti i campi specificati nel filtro. Qualsiasi campo non specificato nel filtro corrisponde a tutti i contesti.

Resi

  • Promise<ExtensionContext[]>

    Promise che si risolve con i contesti corrispondenti, se presenti.

getManifest()

chrome.runtime.getManifest(): object

Restituisce i dettagli sull'app o sull'estensione dal manifest. L'oggetto restituito è una serializzazione del file manifest completo.

Resi

  • oggetto

    I dettagli del manifest.

getPackageDirectoryEntry()

Solo in primo piano 
chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

Restituisce un DirectoryEntry per la directory del pacchetto.

Resi

  • Promise<DirectoryEntry>

    Chrome 122 e versioni successive

getPlatformInfo()

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

Restituisce informazioni sulla piattaforma corrente.

Resi

  • Promise<PlatformInfo>

    Chrome 99 e versioni successive

    Promise che si risolve con le informazioni sulla piattaforma corrente.

getURL()

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

Converte un percorso relativo all'interno di una directory di installazione di un'app o di un'estensione in un URL completo.

Parametri

  • percorso

    stringa

    Un percorso a una risorsa all'interno di un'app o di un'estensione espresso in relazione alla relativa directory di installazione.

Resi

  • stringa

    L'URL completo della risorsa.

getVersion()

Chrome 143 e versioni successive 
chrome.runtime.getVersion(): string

Restituisce la versione dell'estensione dichiarata nel manifest.

Resi

  • stringa

    La versione dell'estensione.

openOptionsPage()

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

Se possibile, apri la pagina delle opzioni dell'estensione.

Il comportamento preciso potrebbe dipendere dalla chiave options_ui o options_page del manifest o da ciò che Chrome supporta in quel momento. Ad esempio, la pagina potrebbe essere aperta in una nuova scheda, all'interno di chrome://extensions, all'interno di un'app o potrebbe semplicemente attivare una pagina di opzioni aperta. Non causerà mai il ricaricamento della pagina chiamante.

Se l'estensione non dichiara una pagina di opzioni o se Chrome non è riuscito a crearne una per qualche altro motivo, il callback imposterà lastError.

Resi

  • Promise<void>

    Chrome 99 e versioni successive

reload()

chrome.runtime.reload(): void

Ricarica l'app o l'estensione. Questo metodo non è supportato in modalità kiosk. Per la modalità kiosk, utilizza il metodo chrome.runtime.restart().

requestUpdateCheck()

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

Richiede un controllo immediato degli aggiornamenti per questa app/estensione.

Importante: la maggior parte delle estensioni/app non deve utilizzare questo metodo, poiché Chrome esegue già controlli automatici ogni poche ore e puoi ascoltare l'evento runtime.onUpdateAvailable senza dover chiamare requestUpdateCheck.

Questo metodo è appropriato solo per le chiamate in circostanze molto limitate, ad esempio se l'estensione comunica con un servizio di backend e quest'ultimo ha stabilito che la versione dell'estensione client è molto obsoleta e vuoi chiedere a un utente di eseguire l'aggiornamento. La maggior parte degli altri utilizzi di requestUpdateCheck, ad esempio la chiamata incondizionata basata su un timer ripetuto, probabilmente serve solo a sprecare risorse del client, della rete e del server.

Nota: se chiamata con un callback, anziché restituire un oggetto, questa funzione restituirà le due proprietà come argomenti separati passati al callback.

Resi

  • Promise<object>

    Chrome 109+

restart()

chrome.runtime.restart(): void

Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk. In caso contrario, non viene eseguita alcuna operazione.

restartAfterDelay()

Chrome 53 e versioni successive 
chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk dopo i secondi specificati. Se viene richiamato prima della fine del tempo, il riavvio verrà ritardato. Se viene chiamato con un valore pari a -1, il riavvio verrà annullato. Non è un'operazione in modalità non kiosk. Può essere chiamata ripetutamente solo dalla prima estensione che richiama questa API.

Parametri

  • secondi

    numero

    Tempo di attesa in secondi prima del riavvio del dispositivo o -1 per annullare un riavvio programmato.

Resi

  • Promise<void>

    Chrome 99 e versioni successive

    Promise che si risolve quando una richiesta di riavvio è stata ripianificata correttamente.

sendMessage()

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

Invia un singolo messaggio ai listener di eventi all'interno della tua estensione o di un'altra estensione/app. Simile a runtime.connect, ma invia un solo messaggio, con una risposta facoltativa. Se l'invio avviene alla tua estensione, l'evento runtime.onMessage verrà attivato in ogni frame dell'estensione (ad eccezione del frame del mittente) o runtime.onMessageExternal, se si tratta di un'estensione diversa. Tieni presente che le estensioni non possono inviare messaggi agli script di contenuti utilizzando questo metodo. Per inviare messaggi agli script dei contenuti, utilizza tabs.sendMessage.

Parametri

  • extensionId

    stringa facoltativa

    L'ID dell'estensione a cui inviare il messaggio. Se omesso, il messaggio verrà inviato alla tua estensione/app. Obbligatorio se i messaggi vengono inviati da una pagina web per la messaggistica web.

  • messaggio

    qualsiasi

    Il messaggio da inviare. Questo messaggio deve essere un oggetto convertibile in JSON.

  • opzioni

    object facoltativo

    • includeTlsChannelId

      boolean facoltativo

      Indica se l'ID canale TLS verrà passato a onMessageExternal per i processi che sono in ascolto dell'evento di connessione.

Resi

  • Promise<any>

    Chrome 99 e versioni successive

    Il supporto delle promise è stato aggiunto per i contesti delle estensioni in Chrome 99. Quando si comunica da una pagina web a un'estensione, le promise sono disponibili a partire da Chrome 118.

sendNativeMessage()

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

Invia un singolo messaggio a un'applicazione nativa. Questo metodo richiede l'autorizzazione "nativeMessaging".

Parametri

  • applicazione

    stringa

    Il nome dell'host di messaggistica nativa o i dettagli della destinazione.

  • messaggio

    oggetto

    Il messaggio che verrà passato all'host di messaggistica nativa.

Resi

  • Promise<any>

    Chrome 99 e versioni successive

setUninstallURL()

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

Imposta l'URL da visitare al momento della disinstallazione. Questi dati possono essere utilizzati per ripulire i dati lato server, eseguire analisi e implementare sondaggi. Massimo 1023 caratteri.

Parametri

  • url

    stringa

    URL da aprire dopo la disinstallazione dell'estensione. Questo URL deve avere uno schema http: o https:. Imposta una stringa vuota per non aprire una nuova scheda al momento della disinstallazione.

Resi

  • Promise<void>

    Chrome 99 e versioni successive

    Promise che si risolve quando viene impostato l'URL di disinstallazione. Se l'URL fornito non è valido, la promise verrà rifiutata.

Eventi

onBrowserUpdateAvailable

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

Utilizza runtime.onRestartRequired.

Attivato quando è disponibile un aggiornamento di Chrome, ma non viene installato immediatamente perché è necessario riavviare il browser.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onConnect

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

Viene attivato quando viene stabilita una connessione da un processo di estensione o da uno script di contenuti (tramite runtime.connect).

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onConnectExternal

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

Attivato quando viene stabilita una connessione da un'altra estensione (tramite runtime.connect) o da un sito web collegabile esternamente.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onConnectNative

Chrome 76 e versioni successive 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Attivato quando viene stabilita una connessione da un'applicazione nativa. Questo evento richiede l'autorizzazione "nativeMessaging". È supportata solo su ChromeOS.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onEnabled

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

Attivato quando un'estensione passa da uno stato disattivato a uno stato attivato.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onExtensionLoaded

Chrome 157+ 
chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

Attivato quando l'estensione viene aggiunta all'insieme di estensioni attive. Questo può verificarsi in più scenari: quando un'estensione viene installata per la prima volta, aggiornata a una nuova versione, riattivata dopo essere stata disattivata, ricaricata, caricata durante l'avvio del browser o caricata quando il browser viene aggiornato a una nuova versione.

Parametri

onInstalled

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

Viene attivato quando l'estensione viene installata per la prima volta, quando viene aggiornata a una nuova versione e quando Chrome viene aggiornato a una nuova versione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (details: object) => void

    • dettagli

      oggetto

      • id

        stringa facoltativa

        Indica l'ID dell'estensione del modulo condiviso importato che è stata aggiornata. Questo campo è presente solo se "reason" è "shared_module_update".

      • previousVersion

        stringa facoltativa

        Indica la versione precedente dell'estensione, che è stata appena aggiornata. Questo campo è presente solo se "reason" è "update".

      • Il motivo per cui viene inviato questo evento.

onMessage

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

Attivato quando viene inviato un messaggio da runtime.sendMessage o tabs.sendMessage.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • messaggio

      qualsiasi

    • mittente

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      (response?: any) => void

      • risposta

        any optional

        La risposta da restituire al mittente del messaggio.

    • returns

      boolean | Promise<any> | undefined

onMessageExternal

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

Viene attivato quando un messaggio viene inviato da un'altra estensione (tramite runtime.sendMessage). Non può essere utilizzato in uno script di contenuti.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • messaggio

      qualsiasi

    • mittente

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      (response?: any) => void

      • risposta

        any optional

        La risposta da restituire al mittente del messaggio.

    • returns

      boolean | Promise<any> | undefined

onRestartRequired

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

Attivato quando è necessario riavviare un'app o il dispositivo su cui viene eseguita. L'app deve chiudere tutte le finestre il prima possibile per consentire il riavvio. Se l'app non esegue alcuna azione, verrà applicato un riavvio dopo un periodo di tolleranza di 24 ore. Al momento, questo evento viene attivato solo per le app kiosk di ChromeOS.

Parametri

onStartup

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

Viene attivato quando un profilo in cui è installata questa estensione viene avviato per la prima volta. Questo evento non viene attivato quando viene avviato un profilo Incognito, anche se l'estensione è in modalità Incognito "divisa".

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onSuspend

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

Inviato alla pagina degli eventi appena prima che venga scaricata. In questo modo, l'estensione ha la possibilità di eseguire alcune operazioni di pulizia. Tieni presente che, poiché la pagina si sta scaricando, non è garantito il completamento di eventuali operazioni asincrone avviate durante la gestione di questo evento. Se si verifica un'ulteriore attività per la pagina degli eventi prima che venga scaricata, verrà inviato l'evento onSuspendCanceled e la pagina non verrà scaricata.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onSuspendCanceled

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

Inviato dopo onSuspend per indicare che l'app non verrà scaricata.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onUpdateAvailable

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

Attivato quando è disponibile un aggiornamento, ma non viene installato immediatamente perché l'app è attualmente in esecuzione. Se non fai nulla, l'aggiornamento verrà installato la prossima volta che la pagina di sfondo viene scaricata. Se vuoi che venga installato prima, puoi chiamare esplicitamente chrome.runtime.reload(). Se l'estensione utilizza una pagina di sfondo persistente, la pagina di sfondo non viene mai scaricata, quindi, a meno che non chiami chrome.runtime.reload() manualmente in risposta a questo evento, l'aggiornamento non verrà installato fino al successivo riavvio di Chrome. Se non ci sono gestori in ascolto di questo evento e l'estensione ha una pagina di sfondo persistente, si comporta come se chrome.runtime.reload() venisse chiamato in risposta a questo evento.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (details: object) => void

    • dettagli

      oggetto

      • versione

        stringa

        Il numero di versione dell'aggiornamento disponibile.

onUserScriptConnect

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

Attivato quando viene stabilita una connessione da uno script utente di questa estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onUserScriptMessage

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

Viene attivato quando un messaggio viene inviato da uno script utente associato alla stessa estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • messaggio

      qualsiasi

    • mittente

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      (response?: any) => void

      • risposta

        any optional

        La risposta da restituire al mittente del messaggio.

    • returns

      boolean | undefined