Topee

Topee is a framework that runs Chrome extension code on Safari.

While Google Chrome, Firefox and Edge share the same extension API, Safari extensions are going in a different direction, requiring developers to use a different set of APIs and partly also Swift instead of JavaScript.

The Topee project provides the Google Chrome Extension API for Safari, allowing you to run a single codebase on all the browsers.

Status: API complete enough for a product.

Integration

If you are completely new to Xcode, read basic setup first.

Xcode Project

• Add github "https://github.com/avast/topee" ~> 1.0.0 to your Cartfile
• Link the Topee to your Appex target
• Add a resource to your Appex pointing to Carthage/Build/Mac/Topee.framework/Resources/topee-content.js
• Make sure the topee-content.js script is referenced in the plist of your appex under: NSExtension / SFSafariContentScript and appears as the first script in the array
• Add a subclass of TopeeSafariExtensionHandler and reference your background script in the NSExtension / TopeeSafariBackgroundScript attribute like shown in the snippet below
• Make sure the the plist entry: NSExtension > NSExtensionPrincipalClass of your appex plist points to $(PRODUCT_MODULE_NAME).SafariExtensionHandler where SafariExtensionHandler is the name of your TopeeSafariExtensionHandler subclass

See xcode.md for more details.

Extension parts

Content scripts are listed in Info.plist as specified for the app extensions. Make sure to list Topee API (topee-content.js) as the first one. Content scripts are injected when document starts loading by default. src/Framework/Scripts/run-at-document-end.sh preprocesses them at build time to run when document body already exists.

Background scripts are also listed in Info.plist in the same manner as content scripts, under SFSafariBackgroundScript key. topee-background.js should not be listed, but place it into the Appex resources.

Injected iframes from web accessible resources need to reference topee-iframe-resources.js.

Place browserAction icons into the Appex resources.

How it works

To run Chrome-API-based extension, Topee creates an invisible WebView to run background scripts and chrome namespace implementations for background and content scripts, that provides messaging and other functionality.

Tests

Once you have the demo extension installed in Safari, you can run unit tests by visiting https://pamcdn.avast.com/pamcdn/extensions/install/mac/blank.html