Connecting an Extension from a Kiosk PWA

Chrome apps will be deprecated after Chrome 102 for Windows, Linux, and MacOS. For ChromeOS, Chrome Apps will be supported until at least January 2025⁠⁠, but we strongly recommend migrating to web apps as Chrome Apps are scheduled for deprecation. Previously, Chrome Apps had extra functionality available to them in kiosk mode that is not currently supported by web apps alone. You can continue to use some of this functionality by deploying an companion extension with your kiosk web application.

How are extensions deployed?

Extensions are deployed through the Chrome Admin Console in the kiosk configuration screen (found by navigating Devices > Chrome > Apps & Extensions > Kiosks). The extensions can either be self hosted at a publicly accessible link or by hosting the extension in the Chrome Web Store. For more information on managing extensions in an enterprise or education setting, please refer to this document⁠⁠.

How can I call extension APIs from my web app?

Because you can deploy companion extensions with your kiosk web app, you can take advantage of extension capabilities by calling extension APIs⁠ to do things like get useful information about the device and hardware platform or manage Chrome accessibility features.

If you'll be using kiosk-only APIs, you'll need to enable them in the manifest. Then implement message passing between your kiosk web app and companion extension so they can communicate with each other.

Enable kiosk-only extension APIs

There are some extension APIs that are only available in kiosk mode. In order for your extension to call these kiosk-only APIs, you need to add the "kiosk_enabled" field to the manifest and set it to true:

{
    "manifest_version": 3,
    "version": "1.0",
    ...
    "kiosk_enabled": true
 }

Implement message passing

Extension setup

To receive and respond to messages from your web app, you will need to expose a background script that listens for messages to arrive from the client (your web app) and then proxy those requests to a corresponding API call. In the following example, a request is proxied to restart the ChromeOS device when the web app sends a custom message object that contains a methodName of callRestart.

// message handler - extension code
chrome.runtime.onMessageExternal.addListener(function (request, sender, sendResponse) {
  if (request.methodName == 'callRestart') {
    chrome.runtime.restart();
  }
});

The manifest for the extension can be configured to allow external function calls to the extension via the externally_connectable⁠⁠ key which specifies what sites and extensions are allowed to call methods in the extension. More information about Chrome extensions and manifest v3 can be found in the official documentation⁠⁠.

{
    "background": {
       "service_worker": "background.js"
    },
    "description": "This restarts your ChromeOS device. Lucky you!",
    "manifest_version": 3,
    "name": "Restart your kiosk app",
    "version": "1.0",
    "kiosk_enabled": true,
    "externally_connectable": {
         "accepts_tls_channel_id": false,
         "matches": [ "\*://chromeos.dev/\*" ]
      },
 }

Web app setup

To call the extension from a web app, you need to know its static extension id. This id can be found on the chrome://extensions page, shown when you install your Chrome extension, or from the Chrome Web Store after the extension has been uploaded. This allows your web app to specify the exact extension that they wish to communicate with. After that, call chrome.runtime.sendMessage⁠⁠ and pass in the extension id with a message that you wish to send to the extension.

const STATIC_EXTENSION_ID = 'abcdefghijklmnopqrstuvwxyz'; // found from chrome extensions page of chrome web store.
const callExtensionAPI = function (method) {
  chrome.runtime.sendMessage(STATIC_EXTENSION_ID, {
    methodName: method,
  });
};
callExtensionAPI('callRestart');

For more information on connecting web pages to extensions for message passing, please refer to this documentation⁠⁠.