chrome.runtime

refresh date: 2026-09-25 robots: noindex

Description

Utilisez l'API chrome.runtime pour récupérer le service worker, renvoyer des détails sur le fichier manifeste, et écouter les événements du cycle de vie de l'extension et y répondre. Vous pouvez également utiliser cette API pour convertir le chemin relatif des URL en URL complètes.

Présentation

L'API Runtime fournit des méthodes permettant de prendre en charge un certain nombre de fonctionnalités que vos extensions peuvent utiliser :

Transmission de messages
Votre extension peut communiquer avec différents contextes au sein de votre extension, ainsi qu'avec d'autres extensions à l'aide de ces méthodes et événements : connect(), onConnect, onConnectExternal, sendMessage(), onMessage et onMessageExternal. De plus, votre extension peut transmettre des messages aux applications natives sur l'appareil de l'utilisateur à l'aide de connectNative() et sendNativeMessage().
Accéder aux métadonnées de l'extension et de la plate-forme
Ces méthodes vous permettent de récupérer plusieurs métadonnées spécifiques sur l'extension et la plate-forme. Les méthodes de cette catégorie incluent getManifest() et getPlatformInfo().
Gérer le cycle de vie et les options des extensions
Ces propriétés vous permettent d'effectuer des méta-opérations sur l'extension et d'afficher la page des options. Les méthodes et événements de cette catégorie incluent onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() et setUninstallURL().
Utilitaires d'assistance
Ces méthodes fournissent des utilitaires tels que la conversion de représentations de ressources internes en formats externes. Les méthodes de cette catégorie incluent getURL().
Utilitaires du mode Kiosque
Ces méthodes ne sont disponibles que sur ChromeOS et existent principalement pour prendre en charge les implémentations de kiosques. Les méthodes de cette catégorie incluent restart et restartAfterDelay.

Autorisations

La plupart des méthodes de l'API Runtime ne nécessitent aucune autorisation, à l'exception de sendNativeMessage et connectNative, qui nécessitent l'autorisation nativeMessaging.

Fichier manifeste

L'exemple suivant montre comment déclarer l'autorisation nativeMessaging dans le fichier manifeste :

manifest.json:

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

Cas d'utilisation

Ajouter une image à une page Web

Pour qu'une page Web puisse accéder à un élément hébergé sur un autre domaine, elle doit spécifier l'URL complète de la ressource (par exemple, <img src="https://example.com/logo.png">). Il en va de même pour inclure un élément d'extension sur une page Web. Les deux différences sont que les éléments de l'extension doivent être exposés en tant que ressources accessibles sur le Web et que les scripts de contenu sont généralement chargés d'injecter les éléments de l'extension.

Dans cet exemple, l'extension ajoute logo.png à la page dans laquelle le script de contenu est injecté en utilisant runtime.getURL() pour créer une URL complète. Mais d'abord, l'asset doit être déclaré comme ressource accessible sur le Web dans le fichier manifeste.

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

Envoyer des données du service worker à un script de contenu

Il est courant que les scripts de contenu d'une extension aient besoin de données gérées par une autre partie de l'extension, comme le service worker. Tout comme deux fenêtres de navigateur ouvertes sur la même page Web, ces deux contextes ne peuvent pas accéder directement aux valeurs de l'autre. À la place, l'extension peut utiliser la transmission de messages pour coordonner ces différents contextes.

Dans cet exemple, le script de contenu a besoin de certaines données du service worker de l'extension pour initialiser son UI. Pour obtenir ces données, il transmet un message get-user-data au service worker, qui répond avec une copie des informations de l'utilisateur.

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

Recueillir des commentaires sur la désinstallation

De nombreuses extensions utilisent des enquêtes post-désinstallation pour comprendre comment elles pourraient mieux répondre aux besoins de leurs utilisateurs et améliorer leur fidélisation. L'exemple suivant montre comment ajouter cette fonctionnalité.

background.js:

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

Exemples d'extensions

Pour obtenir d'autres exemples d'API Runtime, consultez la démo Manifest V3 – Ressources accessibles sur le Web.

Types

ContextFilter

Chrome 114 ou version ultérieure

Filtre à appliquer à certains contextes d'extension. Les contextes correspondants doivent correspondre à tous les filtres spécifiés. Tout filtre non spécifié correspond à tous les contextes disponibles. Ainsi, un filtre `{}` correspondra à tous les contextes disponibles.

Propriétés

  • contextIds

    string[] facultatif

  • contextTypes

    ContextType[] facultatif

  • documentIds

    string[] facultatif

  • documentOrigins

    string[] facultatif

  • documentUrls

    string[] facultatif

  • frameIds

    number[] facultatif

  • navigation privée

    boolean facultatif

  • tabIds

    number[] facultatif

  • windowIds

    number[] facultatif

ContextType

Chrome 114 ou version ultérieure

Énumération

"TAB"
Spécifie le type de contexte en tant qu'onglet

"POPUP"
Spécifie le type de contexte en tant que fenêtre pop-up d'extension

"BACKGROUND"
Spécifie le type de contexte en tant que service worker.

"OFFSCREEN_DOCUMENT"
Spécifie le type de contexte en tant que document hors écran.

"SIDE_PANEL"
Spécifie le type de contexte en tant que panneau latéral.

"DEVELOPER_TOOLS"
Spécifie le type de contexte en tant qu'outils pour les développeurs.

ExtensionContext

Chrome 114 ou version ultérieure

Contexte hébergeant le contenu de l'extension.

Propriétés

  • ID de contexte

    chaîne

    Identifiant unique de ce contexte

  • contextType

    ContextType

    Type de contexte auquel cela correspond.

  • documentId

    chaîne facultatif

    UUID du document associé à ce contexte, ou non défini si ce contexte n'est pas hébergé dans un document.

  • documentOrigin

    chaîne facultatif

    Origine du document associé à ce contexte, ou "undefined" si le contexte n'est pas hébergé dans un document.

  • documentUrl

    chaîne facultatif

    URL du document associé à ce contexte, ou "undefined" si le contexte n'est pas hébergé dans un document.

  • frameId

    nombre

    ID du frame pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans un frame.

  • navigation privée

    booléen

    Indique si le contexte est associé à un profil de navigation privée.

  • tabId

    nombre

    ID de l'onglet pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans un onglet.

  • windowId

    nombre

    ID de la fenêtre pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans une fenêtre.

ExtensionLoadDetails

Chrome 157 ou version ultérieure

Détails sur l'événement de chargement de l'extension.

Propriétés

  • previousVersion

    chaîne facultatif

    Indique la version précédente de l'extension. Ce champ n'est présent que si "reason" est défini sur "update" ou "enable". Si la valeur de "reason" est "update", il s'agit de la version de l'extension avant sa mise à jour. Si la valeur de "reason" est "enable", il s'agit de la version actuelle de l'extension.

  • Raison pour laquelle cet événement est envoyé.

MessageSender

Objet contenant des informations sur le contexte du script qui a envoyé un message ou une requête.

Propriétés

  • documentId

    chaîne facultatif

    Chrome 106 ou version ultérieure

    UUID du document qui a ouvert la connexion.

  • documentLifecycle

    chaîne facultatif

    Chrome 106 ou version ultérieure

    Cycle de vie du document qui a ouvert la connexion au moment de la création du port. Notez que l'état du cycle de vie du document peut avoir changé depuis la création du port.

  • frameId

    number facultatif

    Le frame qui a ouvert la connexion. 0 pour les frames de niveau supérieur, positif pour les frames enfants. Cette valeur n'est définie que lorsque tab est défini.

  • id

    chaîne facultatif

    ID de l'extension qui a ouvert la connexion, le cas échéant.

  • nativeApplication

    chaîne facultatif

    Chrome 74 ou version ultérieure

    Nom de l'application native qui a ouvert la connexion, le cas échéant.

  • origin

    chaîne facultatif

    Chrome 80 ou version ultérieure

    Origine de la page ou du frame qui a ouvert la connexion. Elle peut être différente de la propriété "url" (par exemple, about:blank) ou être opaque (par exemple, les iFrames en bac à sable). Cela permet d'identifier si l'origine est fiable si nous ne pouvons pas le déterminer immédiatement à partir de l'URL.

  • tabulation

    Tab facultatif

    Le tabs.Tab qui a ouvert la connexion, le cas échéant. Cette propriété n'est présente que lorsque la connexion a été ouverte à partir d'un onglet (y compris les scripts de contenu) et uniquement si le récepteur est une extension, et non une application.

  • tlsChannelId

    chaîne facultatif

    L'ID de canal TLS de la page ou du frame qui a ouvert la connexion, si l'extension l'a demandé et s'il est disponible.

  • url

    chaîne facultatif

    URL de la page ou du frame qui a ouvert la connexion. Si l'expéditeur se trouve dans un iFrame, il s'agira de l'URL de l'iFrame, et non de l'URL de la page qui l'héberge.

OnInstalledReason

Chrome 44 ou version ultérieure

Raison pour laquelle cet événement est envoyé.

Énumération

"install"
Spécifie que l'événement est une installation.

"update"
Spécifie que la raison de l'événement est une mise à jour de l'extension.

"chrome_update"
Spécifie que la raison de l'événement est une mise à jour de Chrome.

"shared_module_update"
Spécifie que la raison de l'événement est une mise à jour d'un module partagé.

OnLoadedReason

Chrome 157 ou version ultérieure

Raison pour laquelle cet événement est envoyé.

Énumération

"install"
L'extension vient d'être installée.

"update"
L'extension a été actualisée après une mise à jour.

"browser_update"
Le navigateur a été mis à jour vers une nouvelle version.

"enable"
L'extension a été réactivée après avoir été désactivée.

"startup"
L'extension est chargée au démarrage du navigateur.

"reload"
L'extension a été actualisée (par exemple, via chrome.runtime.reload() ou l'utilisateur l'a actualisée manuellement).

OnRestartRequiredReason

Chrome 44 ou version ultérieure

Raison pour laquelle l'événement est distribué. "app_update" est utilisé lorsque le redémarrage est nécessaire, car l'application est mise à jour vers une version plus récente. "os_update" est utilisé lorsque le redémarrage est nécessaire, car le navigateur/l'OS est mis à jour vers une version plus récente. "periodic" est utilisé lorsque le système s'exécute pendant une durée supérieure au temps d'activité autorisé défini dans la règle d'entreprise.

Énumération

"app_update"
Indique que l'événement est dû à une mise à jour de l'application.

"os_update"
Spécifie que la raison de l'événement est une mise à jour du système d'exploitation.

"periodic"
Spécifie que la raison de l'événement est un redémarrage périodique de l'application.

PlatformArch

Chrome 44 ou version ultérieure

Architecture du processeur de la machine.

Énumération

"arm"
Spécifie l'architecture du processeur en tant qu'arm.

"arm64"
Spécifie l'architecture du processeur en tant qu'arm64.

"x86-32"
Spécifie l'architecture du processeur comme x86-32.

"x86-64"
Spécifie l'architecture du processeur comme x86-64.

"mips"
Spécifie l'architecture du processeur en tant que mips.

"mips64"
Spécifie l'architecture du processeur en tant que mips64.

"riscv64"
Spécifie l'architecture du processeur comme riscv64.

PlatformInfo

Objet contenant des informations sur la plate-forme actuelle.

Propriétés

  • Architecture du processeur de la machine.

  • nacl_arch

    PlatformNaclArch facultatif

    Obsolète depuis Chrome 149

    Cet attribut est obsolète suite à la suppression complète de Native Client.

    Architecture du client natif. Cette valeur peut être différente de l'architecture sur certaines plates-formes.

  • Système d'exploitation sur lequel Chrome est exécuté.

PlatformNaclArch

Chrome 44 et versions ultérieures Obsolète depuis Chrome 149

Cette énumération est obsolète suite à la suppression complète de Native Client.

Architecture du client natif. Cette valeur peut être différente de l'architecture sur certaines plates-formes.

Énumération

"arm"
Spécifie l'architecture du client natif en tant qu'arm.

"x86-32"
Spécifie l'architecture du client natif en tant que x86-32.

"x86-64"
Spécifie l'architecture du client natif en tant que x86-64.

"mips"
Spécifie l'architecture du client natif en tant que mips.

"mips64"
Spécifie l'architecture du client natif en tant que mips64.

PlatformOs

Chrome 44 ou version ultérieure

Système d'exploitation sur lequel Chrome est exécuté.

Énumération

"mac"
Spécifie le système d'exploitation macOS.

"win"
Spécifie le système d'exploitation Windows.

"android"
Spécifie le système d'exploitation Android.

"cros"
Spécifie le système d'exploitation Chrome.

"linux"
Spécifie le système d'exploitation Linux.

"openbsd"
Spécifie le système d'exploitation OpenBSD.

Port

Objet permettant une communication bidirectionnelle avec d'autres pages. Pour en savoir plus, consultez Connexions de longue durée.

Propriétés

  • nom

    chaîne

    Nom du port, tel que spécifié dans l'appel à runtime.connect.

  • onDisconnect

    Event<functionvoidvoid>

    Se déclenche lorsque le port est déconnecté de l'autre extrémité. runtime.lastError peut être défini si le port a été déconnecté en raison d'une erreur. Si le port est fermé via disconnect, cet événement n'est déclenché que à l'autre extrémité. Cet événement est déclenché au maximum une fois (voir aussi Durée de vie du port).

    La fonction onDisconnect.addListener se présente comme suit : 

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

    • callback

      fonction

      Le paramètre callback se présente comme suit : 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    Cet événement est déclenché lorsque postMessage est appelé par l'autre extrémité du port.

    La fonction onMessage.addListener se présente comme suit : 

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

    • callback

      fonction

      Le paramètre callback se présente comme suit : 

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

      • message

        tous

      • port

        Port

  • expéditeur

    MessageSender facultatif

    Cette propriété ne sera présente que sur les ports transmis aux écouteurs onConnect / onConnectExternal / onConnectNative.

  • déconnecter

    vide

    Déconnectez immédiatement le port. L'appel de disconnect() sur un port déjà déconnecté n'a aucun effet. Lorsqu'un port est déconnecté, aucun nouvel événement ne lui est envoyé.

    La fonction disconnect se présente comme suit : 

    () => {...}

  • postMessage

    vide

    Envoyez un message à l'autre extrémité du port. Si le port est déconnecté, une erreur est générée.

    La fonction postMessage se présente comme suit : 

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

    • message

      tous

      Chrome 52 ou version ultérieure

      Message à envoyer. Cet objet doit être convertible au format JSON.

RequestUpdateCheckStatus

Chrome 44 ou version ultérieure

Résultat de la vérification de la mise à jour.

Énumération

"throttled"
Indique que la vérification de l'état a été limitée. Cela peut se produire après des vérifications répétées sur une courte période.

"no_update"
Indique qu'aucune mise à jour n'est disponible pour l'installation.

"update_available"
Indique qu'une mise à jour est disponible pour l'installation.

Propriétés

id

ID de l'extension/application.

Type

chaîne

lastError

Contient un message d'erreur si l'appel d'une fonction d'API échoue. Sinon, non défini. Il n'est défini que dans le champ d'application du rappel de cette fonction. Si une erreur se produit, mais que runtime.lastError n'est pas accessible dans le rappel, un message est consigné dans la console, listant la fonction d'API qui a produit l'erreur. Les fonctions d'API qui renvoient des promesses ne définissent pas cette propriété.

Type

objet

Propriétés

  • message

    chaîne facultatif

    Détails de l'erreur qui s'est produite.

Méthodes

connect()

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

Tente de connecter des écouteurs dans une extension (comme la page d'arrière-plan) ou d'autres extensions/applications. Cela est utile pour les scripts de contenu qui se connectent à leurs processus d'extension, pour la communication entre applications/extensions et pour la messagerie Web. Notez que cela ne se connecte à aucun écouteur dans un script de contenu. Les extensions peuvent se connecter aux scripts de contenu intégrés dans les onglets via tabs.connect.

Paramètres

  • extensionId

    chaîne facultatif

    ID de l'extension à laquelle se connecter. Si vous omettez ce paramètre, une connexion sera tentée avec votre propre extension. Obligatoire si vous envoyez des messages depuis une page Web pour la messagerie Web.

  • connectInfo

    objet facultatif

    • includeTlsChannelId

      boolean facultatif

      Indique si l'ID de canal TLS sera transmis à onConnectExternal pour les processus qui écoutent l'événement de connexion.

    • nom

      chaîne facultatif

      Sera transmis à onConnect pour les processus qui écoutent l'événement de connexion.

Renvoie

  • Port par lequel les messages peuvent être envoyés et reçus. L'événement onDisconnect du port est déclenché si l'extension n'existe pas.

connectNative()

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

Se connecte à une application native sur la machine hôte. Cette méthode nécessite l'autorisation "nativeMessaging". Pour en savoir plus, consultez Messagerie native.

Paramètres

  • application

    chaîne

    Nom de l'application enregistrée à laquelle se connecter.

Renvoie

  • Port par lequel les messages peuvent être envoyés et reçus avec l'application

getBackgroundPage()

Promise Premier plan uniquement Obsolète depuis Chrome 133
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

Les pages d'arrière-plan n'existent pas dans les extensions MV3.

Récupère l'objet JavaScript "window" de la page d'arrière-plan exécutée dans l'extension/application actuelle. Si la page d'arrière-plan est une page d'événement, le système s'assure qu'elle est chargée avant d'appeler le rappel. Si aucune page d'arrière-plan n'est définie, une erreur est générée.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (backgroundPage?: Window) => void

    • backgroundPage

      Fenêtre facultatif

      Objet JavaScript "window" pour la page d'arrière-plan.

Renvoie

  • Promise<Window | undefined>

    Chrome 99 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getManifest()

chrome.runtime.getManifest(): object

Renvoie des informations sur l'application ou l'extension à partir du fichier manifeste. L'objet renvoyé est une sérialisation du fichier manifeste complet.

Renvoie

  • objet

    Détails du fichier manifeste.

getPackageDirectoryEntry()

Promise Premier plan uniquement 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

Renvoie un DirectoryEntry pour le répertoire du package.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Renvoie

  • Promise<DirectoryEntry>

    Chrome 122 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getPlatformInfo()

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

Renvoie des informations sur la plate-forme actuelle.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (platformInfo: PlatformInfo) => void

Renvoie

  • Promise<PlatformInfo>

    Chrome 99 ou version ultérieure

    Promesse qui se résout avec des informations sur la plate-forme actuelle.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getURL()

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

Convertit un chemin relatif dans un répertoire d'installation d'application/extension en URL complète.

Paramètres

  • chemin d'accès

    chaîne

    Chemin d'accès à une ressource dans une application/extension, exprimé par rapport à son répertoire d'installation.

Renvoie

  • chaîne

    URL complète de la ressource.

getVersion()

Chrome 143 ou version ultérieure 
chrome.runtime.getVersion(): string

Renvoie la version de l'extension telle qu'elle est déclarée dans le fichier manifeste.

Renvoie

  • chaîne

    La version de l'extension.

openOptionsPage()

Promise 
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

Ouvrez la page d'options de votre extension, si possible.

Le comportement précis peut dépendre de la clé options_ui ou options_page de votre fichier manifeste, ou de ce que Chrome accepte à ce moment-là. Par exemple, la page peut être ouverte dans un nouvel onglet, dans chrome://extensions, dans une application, ou elle peut simplement se concentrer sur une page d'options ouverte. Elle n'entraîne jamais l'actualisation de la page appelante.

Si votre extension ne déclare pas de page d'options ou si Chrome n'a pas pu en créer une pour une autre raison, le rappel définira lastError.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 99 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

reload()

chrome.runtime.reload(): void

Recharge l'application ou l'extension. Cette méthode n'est pas compatible avec le mode Kiosque. Pour le mode Kiosque, utilisez la méthode chrome.runtime.restart().

requestUpdateCheck()

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

Demande qu'une recherche de mise à jour immédiate soit effectuée pour cette application/extension.

Important : La plupart des extensions/applications ne doivent pas utiliser cette méthode, car Chrome effectue déjà des vérifications automatiques toutes les quelques heures, et vous pouvez écouter l'événement runtime.onUpdateAvailable sans avoir à appeler requestUpdateCheck.

Cette méthode ne doit être appelée que dans des circonstances très limitées, par exemple si votre extension communique avec un service de backend, que ce service a déterminé que la version de l'extension cliente est très obsolète et que vous souhaitez inviter l'utilisateur à la mettre à jour. La plupart des autres utilisations de requestUpdateCheck, comme l'appeler de manière inconditionnelle en fonction d'un minuteur répétitif, ne servent probablement qu'à gaspiller les ressources du client, du réseau et du serveur.

Remarque : Lorsqu'elle est appelée avec un rappel, cette fonction renvoie les deux propriétés sous forme d'arguments distincts transmis au rappel, au lieu de renvoyer un objet.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (result: object) => void

    • résultat

      objet

      Chrome 109 ou version ultérieure

      Objet RequestUpdateCheckResult contenant l'état de la vérification de la mise à jour et les détails du résultat si une mise à jour est disponible

      • Résultat de la vérification de la mise à jour.

      • version

        chaîne facultatif

        Si une mise à jour est disponible, ce champ contient la version de la mise à jour disponible.

Renvoie

  • Promise<object>

    Chrome 109 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

restart()

chrome.runtime.restart(): void

Redémarrez l'appareil ChromeOS lorsque l'application s'exécute en mode Kiosque. Sinon, il s'agit d'une opération sans effet.

restartAfterDelay()

Promise Chrome 53 et versions ultérieures 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

Redémarrez l'appareil ChromeOS lorsque l'application s'exécute en mode Kiosque après le nombre de secondes indiqué. Si elle est appelée à nouveau avant la fin du délai, le redémarrage sera retardé. Si elle est appelée avec la valeur -1, le redémarrage sera annulé. Il s'agit d'une opération sans effet en mode autre que kiosque. Seule la première extension à appeler cette API est autorisée à l'appeler de manière répétée.

Paramètres

  • secondes

    nombre

    Délai d'attente en secondes avant de redémarrer l'appareil, ou -1 pour annuler un redémarrage programmé.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 99 ou version ultérieure

    Promesse qui se résout lorsqu'une demande de redémarrage a bien été reprogrammée.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

sendMessage()

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

Envoie un seul message aux écouteurs d'événements de votre extension ou d'une autre extension/application. Semblable à runtime.connect, mais n'envoie qu'un seul message, avec une réponse facultative. Si l'envoi est destiné à votre extension, l'événement runtime.onMessage sera déclenché dans chaque frame de votre extension (à l'exception de la frame de l'expéditeur) ou runtime.onMessageExternal s'il s'agit d'une autre extension. Notez que les extensions ne peuvent pas envoyer de messages aux scripts de contenu à l'aide de cette méthode. Pour envoyer des messages aux scripts de contenu, utilisez tabs.sendMessage.

Paramètres

  • extensionId

    chaîne facultatif

    ID de l'extension à laquelle envoyer le message. Si ce paramètre est omis, le message sera envoyé à votre propre extension/application. Obligatoire si vous envoyez des messages depuis une page Web pour la messagerie Web.

  • message

    tous

    Message à envoyer. Ce message doit être un objet JSON-ifiable.

  • options

    objet facultatif

    • includeTlsChannelId

      boolean facultatif

      Indique si l'ID de canal TLS sera transmis à onMessageExternal pour les processus qui écoutent l'événement de connexion.

  • callback

    function facultatif

    Chrome 99 ou version ultérieure

    Le paramètre callback se présente comme suit : 

    (response: any) => void

    • réponse

      tous

      Objet de réponse JSON envoyé par le gestionnaire du message. Si une erreur se produit lors de la connexion à l'extension, le rappel sera appelé sans argument et runtime.lastError sera défini sur le message d'erreur.

Renvoie

  • Promise<any>

    Chrome 99 ou version ultérieure

    La prise en charge des promesses a été ajoutée pour les contextes d'extension dans Chrome 99. Lors de la communication entre une page Web et une extension, les promesses sont disponibles à partir de Chrome 118.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

sendNativeMessage()

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

Envoyer un seul message à une application native. Cette méthode nécessite l'autorisation "nativeMessaging".

Paramètres

  • application

    chaîne

    Nom de l'hôte de messagerie natif ou détails de la cible.

  • message

    objet

    Message qui sera transmis à l'hôte de messagerie natif.

  • callback

    function facultatif

    Chrome 99 ou version ultérieure

    Le paramètre callback se présente comme suit : 

    (response: any) => void

    • réponse

      tous

      Message de réponse envoyé par l'hôte de messagerie native. Si une erreur se produit lors de la connexion à l'hôte de messagerie natif, le rappel est appelé sans argument et runtime.lastError est défini sur le message d'erreur.

Renvoie

  • Promise<any>

    Chrome 99 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setUninstallURL()

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

Définit l'URL à visiter lors de la désinstallation. Cela peut être utilisé pour nettoyer les données côté serveur, effectuer des analyses et mettre en œuvre des enquêtes. 1 023 caractères maximum.

Paramètres

  • url

    chaîne

    URL à ouvrir après la désinstallation de l'extension. Cette URL doit utiliser le schéma http: ou https:. Définissez une chaîne vide pour ne pas ouvrir de nouvel onglet lors de la désinstallation.

  • callback

    function facultatif

    Chrome 45 ou version ultérieure

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 99 ou version ultérieure

    Promesse qui se résout lorsque l'URL de désinstallation est définie. Si l'URL fournie n'est pas valide, la promesse sera rejetée.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onBrowserUpdateAvailable

Obsolète
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Veuillez utiliser runtime.onRestartRequired.

Se déclenche lorsqu'une mise à jour de Chrome est disponible, mais qu'elle n'est pas installée immédiatement, car un redémarrage du navigateur est requis.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onConnect

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

Se déclenche lorsqu'une connexion est établie à partir d'un processus d'extension ou d'un script de contenu (par runtime.connect).

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (port: Port) => void

onConnectExternal

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

Se déclenche lorsqu'une connexion est établie à partir d'une autre extension (par runtime.connect) ou d'un site Web connectable en externe.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (port: Port) => void

onConnectNative

Chrome 76 ou version ultérieure 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Déclenché lorsqu'une connexion est établie à partir d'une application native. Cet événement nécessite l'autorisation "nativeMessaging". Il n'est compatible qu'avec ChromeOS.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (port: Port) => void

onEnabled

Chrome 155 ou version ultérieure 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

Se déclenche lorsqu'une extension passe de l'état désactivé à l'état activé.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onExtensionLoaded

Chrome 157 ou version ultérieure 
chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

Déclenché lorsque l'extension est ajoutée à l'ensemble des extensions actives. Cela peut se produire dans plusieurs scénarios : lorsqu'une extension est installée pour la première fois, mise à jour vers une nouvelle version, réactivée après avoir été désactivée, rechargée, chargée au démarrage du navigateur ou chargée lorsque le navigateur est mis à jour vers une nouvelle version.

Paramètres

onInstalled

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

Déclenché lors de la première installation de l'extension, de la mise à jour de l'extension vers une nouvelle version et de la mise à jour de Chrome vers une nouvelle version.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • id

        chaîne facultatif

        Indique l'ID de l'extension de module partagé importée qui a été mise à jour. Ce champ n'est présent que si la valeur de "reason" est "shared_module_update".

      • previousVersion

        chaîne facultatif

        Indique la version précédente de l'extension, qui vient d'être mise à jour. Ce champ n'est présent que si la valeur de "reason" est "update".

      • Raison pour laquelle cet événement est envoyé.

onMessage

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

Déclenché lorsqu'un message est envoyé depuis runtime.sendMessage ou tabs.sendMessage.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

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

    • message

      tous

    • expéditeur

      MessageSender

    • sendResponse

      fonction

      Le paramètre sendResponse se présente comme suit : 

      (response?: any) => void

      • réponse

        facultatif

        Réponse à renvoyer à l'expéditeur du message.

    • Renvoie

      boolean | Promise<any> | undefined

onMessageExternal

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

Se déclenche lorsqu'un message est envoyé depuis une autre extension (par runtime.sendMessage). Ne peut pas être utilisé dans un script de contenu.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

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

    • message

      tous

    • expéditeur

      MessageSender

    • sendResponse

      fonction

      Le paramètre sendResponse se présente comme suit : 

      (response?: any) => void

      • réponse

        facultatif

        Réponse à renvoyer à l'expéditeur du message.

    • Renvoie

      boolean | Promise<any> | undefined

onRestartRequired

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

Déclenché lorsqu'une application ou l'appareil sur lequel elle s'exécute doit être redémarré. L'application doit fermer toutes ses fenêtres dès que possible pour permettre le redémarrage. Si l'application ne fait rien, un redémarrage sera appliqué après un délai de grâce de 24 heures. Actuellement, cet événement n'est déclenché que pour les applications kiosque Chrome OS.

Paramètres

onStartup

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

Déclenché lorsqu'un profil sur lequel cette extension est installée démarre pour la première fois. Cet événement n'est pas déclenché lorsqu'un profil de navigation privée est démarré, même si cette extension fonctionne en mode navigation privée "split".

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onSuspend

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

Envoyé à la page d'événement juste avant qu'elle ne soit déchargée. Cela permet à l'extension d'effectuer un nettoyage. Notez que, comme la page est en cours de déchargement, il n'est pas garanti que les opérations asynchrones démarrées lors du traitement de cet événement se terminent. Si d'autres activités se produisent sur la page d'événement avant qu'elle ne soit déchargée, l'événement onSuspendCanceled est envoyé et la page n'est pas déchargée.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onSuspendCanceled

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

Envoyé après onSuspend pour indiquer que l'application ne sera finalement pas déchargée.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onUpdateAvailable

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

Déclenché lorsqu'une mise à jour est disponible, mais qu'elle n'est pas installée immédiatement, car l'application est en cours d'exécution. Si vous ne faites rien, la mise à jour sera installée la prochaine fois que la page d'arrière-plan sera déchargée. Si vous souhaitez qu'elle soit installée plus tôt, vous pouvez appeler explicitement chrome.runtime.reload(). Si votre extension utilise une page d'arrière-plan persistante, celle-ci n'est bien sûr jamais déchargée. Par conséquent, à moins que vous n'appeliez manuellement chrome.runtime.reload() en réponse à cet événement, la mise à jour ne sera pas installée avant le prochain redémarrage de Chrome. Si aucun gestionnaire n'écoute cet événement et que votre extension comporte une page d'arrière-plan persistante, elle se comporte comme si chrome.runtime.reload() était appelé en réponse à cet événement.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • version

        chaîne

        Numéro de version de la mise à jour disponible.