Skip to content
The Wavebox Service API for extending web apps running in Wavebox
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
appstore
examples
images
CONTRIBUTING.md
LICENSE
README.md

README.md

The Wavebox Service API provides a way to customise and enhance services within the Wavebox app. It provides means to inject functionality into specific pages and bubble up information to the Wavebox app that can be useful when specific tabs aren't available.

You can use the Service API to:

  • Show an unread badge and activity on a specific service
  • Show information in the tray about unread items on a page
  • Hook into the Quick Search CmdOrCtrl+T to give keyboard actions

Getting Started

Supported versions and Services

We're working on adding support to all account types in Wavebox, with version 4.7.12+ all apps in the store are supported, with the exception of Gmail, Google Inbox, Outlook, Office 365, Trello, Slack & the Any web link. (Support coming soon).

Using the API

To use the API, first you need to add an account to the Wavebox app. Once done, open the account settings and scroll down to the Service API section

Clicking on the Open directory button will open the service api directory for this account type. To get started you need to create a manifest.json file in this directory which the app can use to load your custom configuration.

Reloading

Each time the app is started, it will reload your manifest.json file. Linked scripts and styles are reloaded every time they are used for convenience. If you need to reload your manifest file without restart the app, you can use the reload button under the Service Api section in settings.

API

Manifest

The manifest.json file responds to the following settings:

Name Type Required Default Info
supportsUnreadActivity Bool No true Whether the service supports the unread activity dot
supportsUnreadCount Bool No true Whether the service supports the unread count
supportsTrayMessages Bool No true Whether the service supports placing items in the tray
supportsWBGAPI Bool No false True if the service should support the guest page writing unreadActivity, unreadCount and trayMessages. To access these fields you can use an adaptor
supportsGuestNotifications Bool No true Whether the service supports HTML5 browser notifications
html5NotificationsGenerateUnreadActivity Bool No true If set to true a new HTML5 browser notification will automatically create an unread dot until the service is opened
documentTitleHasUnread Bool No true True if the document title has the unread count
documentTitleUnreadBlinks Bool No false If the document title has the unread count but also blinks set this to true so the app can cope with this case
faviconUnreadActivityRegexp Bool No undefined If the pages favicon indicates unread activity, the regexp string provided here will run over the favicon url. A match will indicate unread activity
adaptors Bool No [] An array of adaptors that are run on page load. See the adaptor section for more
commands Bool No [] An array of commands that the user can execute from the Quick Search. See the command section for more

Adaptors

Adaptors are scripts and styles that are injected into certain pages on dom-ready. These can be used, for example to pull the unread count out of the dom and bubble it up to the app. Adaptors are split into two parts, firstly the the manifest entry, secondly the linked code

Manifest Entry

Each adaptor in the entry responds to the following settings:

Name Type Required Default Info
matches Array Yes - An array of urls to match. When a match is encountered the adaptor will be executed. Internally the app uses url-pattern for matching
js File No undefined The JavaScript to execute when the page is ready. In this field place the name of the file to load relative to the manifest path
styles File No undefined The CSS to execute when the page is ready. In this field place the name of the file to load relative to the manifest path

In-page Guest API

wavebox.badge.setCount

Sets the unread count on the service badge

  • count (int) the count to display
window.wavebox.badge.setCount(10)
wavebox.badge.setHasUnreadActivity

Sets if the service has unread activity

  • has (bool) true to show the activity indicator, false to hide
window.wavebox.badge.setHasUnreadActivity(true)
wavebox.tray.setMessages

Sets the list of messages in the tray

  • messages (array) an array of messages to display to the user

Each message item provided should validate as so:

  • id=auto (string:max=100) a unique id for this message. Providing this helps improve performance
  • text (string:max=100) text to display to the user
  • title (string:max=100) (Version 4.8.5+) title text to display to the user. Note if title and text are both supplied, title will be used
  • subtitle (string:max=100) (Version 4.8.5+) subtitle text to display to the user
  • date=auto (int) epoch time of the message which can be used for ordering. Will also support incrementing numbers for ordering
window.wavebox.tray.setMessages([
	{
		id: 'message_id_1',
		title: 'Joe Bloggs',
		subtitle: 'You have a message',
		date: 1516022635099
	}
])
wavebox.api.version [prop]

The current API version

console.log(window.wavebox.api.version) //0.0.1-alpha

Commands

Commands provide a way for the user to access quick actions from the Quick Search. This could be composing an email, searching for a tweet etc. Commands can either direct the user to a specific url or run a script on a page or a combination of both. Commands are split into two parts, firstly the the manifest entry, secondly the linked code

Manifest Entry

Each adaptor in the entry responds to the following settings:

Name Type Required Default Info
modifier String Yes - One of / # @ $. Provides the search modifier that the user can enter
keyword String Yes - The keyword the user must use to run the command. For example tweet
helper String No undefined The helper text that might inform the user on the command layout
description String Yes - The description that's displayed to the user before they run the command
url String No undefined The url to open when the user executes the command. See below for more info
js File No undefined The JS to execute in the page. In this field place the name of the file to load relative to the manifest path

Urls

The url is automatically opened in the running service. If the provided url is already open, the page will not be reloaded. To access the command that the user has entered you can use {{args}} within your url and the command arguments will be substituted to the url. For example

  • Url: https://google.com?q={{args}}
  • User types: /search wavebox app
  • Opened Url: https://google.com?q=wavebox%20app

JavaScript

When the JavaScript is executed information about the run search is provided as the following variables so that the behaviour can be customised...

  • modifier: The modifier ran (e.g. /)
  • keyword: The keyword user (e.g. search)
  • args: The remaining arguments in the command (e.g. wavebox app)
  • fullCommand: The full un-parsed command the user entered (e.g. /search wavebox app)

Debugging

Each time the app reads the JSON manifest, it outputs a log in the same directory. This will provide information as to why and when a load of your manifest has failed.

Adaptors and JavaScript Commands and run within the guest page. You can use the developer tools to debug why your code may have failed at runtime. Developer tools are available...

  • Right click > Inspect Element
  • Main Window Menus > View > Developer > Developer Tools
  • Cmd+Alt+I on macOS Ctrl+Shift+I on windows and linux

Examples

Examples can be found in the examples folder:

Contributing

Side-loading your service customisations is just the first step. If you want to include them in the App Store entries, just open up a Pull Request on this repository and place your changes under the appstore folder. The Wavebox team will review them and add them into the store entries.

You can’t perform that action at this time.