@wranggle/rpc-browser-extension-transport v0.3.6-bad.0
BrowserExtensionTransport
DEPRECATED: {old/buggy; todo: drop in newer from cannery}
A WranggleRpc transport for browser extensions, sending and receiving messages over either chrome.runtime or chrome.tabs.
Firefox and Edge also support these Chromium APIs.
Setup
If you are using the full @wranggle/rpc package, the BrowserExtensionTransport is already bundled within. You can import/require it with:
import { WranggleRpc, BrowserExtensionTransport } from '@wranggle/rpc';
// or
const { WranggleRpc, BrowserExtensionTransport } = require('@wranggle/rpc');
Unbundled Alternative
If you prefer using just the packages you need, the unbundled es6 is also available on NPM:
yarn add @wranggle/rpc-core @wranggle/rpc-browser-extension-transport
# or
npm install @wranggle/rpc-core @wranggle/rpc-browser-extension-transport
Unbundled import:
import WranggleRpc from '@wranggle/rpc-core';
import BrowserExtensionTransport from '@wranggle/rpc-browser-extension-transport';
Construction
When creating your WranggleRpc endpoint, you can use the browserExtension
shortcut to also construct this transport. Eg:
const rpc = new WranggleRpc({
browserExtension: opts,
channel: 'some-channel'
});
Or:
const rpc = new WranggleRpc({
transport: new BrowserExtensionTransport(opts),
channel: 'some-channel'
});
Options
The options relate filtering and security.
Filtering
permitMessage An optional filter function for inspecting incoming messages sender and payload. Return true to accept message, anything else to rejects. Here a background page ensures the message originates from popup as expected:
const rpc = new WranggleRpc({ browserExtension: { permitMessage: (payload, sender) => sender.url === `chrome-extension://${chrome.runtime.id}/popup.html` })
skipExtensionIdCheck By default, messages received from other browser extensions are ignored. Set this option to true to permit them. Note: when set, the presence of a
permitMessage
filter is required.
Communicating with content scripts / tabs
These options are for the endpoint on the priviledged side (eg, a background page) that is communicating with a sandboxed content script (for a browser tab page.)
You'll need the tabId for these options. There are various ways to it in a chrome extension, such as:
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => console.log('Tab id is: ', tabs[0].id));
sendToTabId Sends messages from main extension to a single, specific content script (rather than broadcasting to any listening.) When set, messages are sent using chrome.tabs.sendMessage. Accepts tab id as a number.
receiveFromTabId Checks tab id of received messages, and ignores all from other tabs. Accepts tab id as a number.
forTabId Sets both sendToTabId and receiveFromTabId to the same tabId number.