Overview#

Delver X extensions allow you to build integrations and new features directly within the application. This guide will walk you through the process of writing and using your own extensions.

Extensions in Delver X operate within a sandboxed iframe and activate as soon as the page loads. They communicate with the main application through a message-passing system. A global delver object is available within the extension’s scope.

The extension API is designed to be minimal and evolve based on developer needs. If you find the current API lacking for your project, we encourage you to reach out to us at contact@delverlab.com.

Quick Start#

Let’s create a very simple extension to get a feel for the process. This “True Dark” extension uses the delver.setTheme() API function to make the default dark theme even darker. The entire extension is contained in a single Javascript file.

/*
 * @id true-dark
 * @name True Dark
 * @version 100
 * @short_description Make the dark-theme even darker
 * @description_start
 *  This extension sets a dark theme that's darker than the one available in the app.
 *  This is also a good example of how to use the setTheme API.
 * @description_end
 * @icon_start
 * <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
 * <path d="M17.75,4.09L15.22,6.03L16.13,9.09L13.5,7.28L10.87,9.09L11.78,6.03L9.25,4.09L12.44,4L13.5,1L14.56,4L17.75,4.09M21.25,11L19.61,12.25L20.2,14.23L18.5,13.06L16.8,14.23L17.39,12.25L15.75,11L17.81,10.95L18.5,9L19.19,10.95L21.25,11M18.97,15.95C19.8,15.87 20.69,17.05 20.16,17.8C19.84,18.25 19.5,18.67 19.08,19.07C15.17,23 8.84,23 4.94,19.07C1.03,15.17 1.03,8.83 4.94,4.93C5.34,4.53 5.76,4.17 6.21,3.85C6.96,3.32 8.14,4.21 8.06,5.04C7.79,7.9 8.75,10.87 10.95,13.06C13.14,15.26 16.1,16.22 18.97,15.95M17.33,17.97C14.5,17.81 11.7,16.64 9.53,14.5C7.36,12.31 6.2,9.5 6.04,6.68C3.23,9.82 3.34,14.64 6.35,17.66C9.37,20.67 14.19,20.78 17.33,17.97Z" />
 * </svg>
 * @icon_end
 * @developer Delver Lab
 * @developer_url https://delverlab.com
 */

delver.setTheme({
	colors: {
		primary: '#020617',
		'primary-dark': '#000000',
		'primary-light': '#0f172a',
		secondary: '#000000',

		// background colors
		'dark-background-color-100': '#000000',
		'dark-background-color-200': '#020617',
		'dark-background-color-300': '#0f172a'
	}
})

The Extension Manifest#

You need to provide a manifest with several required fields within your extension’s file. Here is a breakdown of the manifest fields using the “Dropbox Sync” extension as an example:

• @id: A unique, machine-readable identifier for your extension.

  * @id dropbox-sync

• @name: The human-readable name of your extension that will be displayed in the UI.

  * @name Dropbox Sync

• @version: A numeric version for your extension. We recommend a number between 100 and 999 for your initial release. While the version is ignored when an extension is manually installed, it’s used for the update process. Versions are displayed with dots inserted every two digits from the right. For instance, 100 becomes “1.00”, and 10001 is displayed as “1.00.01”.

  * @version 100

• @short_description: A concise, one-line summary of what your extension does.

  * @short_description Sync with Delver Android using Dropbox Sync

• @description_start / @description_end: The full description of your extension. This field supports Markdown for rich formatting. Everything between these two tags will be parsed.

  * @description_start
  * Sync manually with Delver Android via Dropbox Sync.
  *
  * ## How Dropbox Sync works in Delver Android
  *
  * 1. Delver Android uploads two files to Dropbox: user and images.
  * 2. You can manually restore these files in Delver Android.
  * 3. You can force Delver Android to upload these files.
  *
  * ## What this extension does
  *
  * Adds a new "Dropbox Sync" item to the main screen's side menu.
  * From there, you can:
  *
  * 1. Import the user and image files from Dropbox.
  * 2. Export the local data to Dropbox where you can then restore it in Delver Android.
  *
  * This extension facilitates syncing between both apps.
  * Note that synchronization is not automatic;
  * manual import/export between apps is necessary.
  *
  * ## Limitations
  *
  * - List background image is not synced.
  *
  * @description_end

• @icon_start / @icon_end: The icon for your extension. While SVGs are preferred, you can also use a base64 encoded image. Note that icons are displayed against a white background. All entries are sanitized, so scripts will not be executed.

  * @icon_start
  * <svg xmlns="[http://www.w3.org/2000/svg](http://www.w3.org/2000/svg)"
  * viewBox="0 0 24 24" fill="#1e40af">
  * <path d="M3 6.2L8 9.39L13 6.2L8 3L3 6.2M13 6.2L18 9.39L23 6.2L18 3L13 6.2M3 12.55L8 15.74L13 12.55L8 9.35L3 12.55M18 9.35L13 12.55L18 15.74L23 12.55L18 9.35M8.03 16.8L13.04 20L18.04 16.8L13.04 13.61L8.03 16.8Z" />
  * </svg>
  * @icon_end

• @developer: The name of the person or entity that developed the extension.

  * @developer Delver Lab

• @developer_url: A link to the developer’s website or profile.

  * @developer_url [https://delverlab.com](https://delverlab.com)

The Delver X Extensiosn API#

Your extension lives in a sandboxed iframe and communicates with the Delver X application by passing messages back and forth. A global delver object is available to facilitate this interaction.

The complete API, including the source code, is available for your reference here. This file is the definitive source for understanding the available functionalities.

Our philosophy is to add features to the API as they are requested by developers. If you have specific needs, please contact us at contact@delverlab.com to discuss them.

Here’s a non-exhaustive list of some functions that are available to you:

• importScript: Loads an external script, like a third-party library.
• createMainMenuItem: Adds a clickable item to the main side menu.
• createTextSetting: Creates a text-based setting in the extension settings menu.
• [set/get]Setting: Stores and retrieves the value of a setting.
• displayDialog: Shows a dialog box with a title, custom HTML content, and optional action buttons.
• displayProgressDialog: Displays a progress dialog for long-running operations.
• displayToast: Shows a temporary, non-intrusive notification message.
• oauthSignIn: Initiates a third-party OAuth sign-in flow.
• oauthGetToken: Retrieves a stored OAuth access token.
• oauthSignOut: Signs out by removing a stored OAuth token.
• exportV2: Exports the user’s collection data and images as files for backup or transfer.
• importV2: Imports data from files generated by exportV2.
• setTheme: Customizes the theme by applying custom colors.

Handling Authentication#

If your extension requires users to sign in to a third-party service, the Dropbox Sync extension provides a clear example of how to manage the OAuth2 token exchange with the Dropbox API.

Session tokens are stored in the user’s localStorage. Delver X ensures that only your extension can access the session tokens your extension creates.

Important: Always ensure that you do not expose a token with more permissions than is absolutely necessary for your extension to function.

The Future of Extensions#

The Delver X extension system is being developed in phases:

• Phase 1: (Current) Install and uninstall extensions.
• Phase 2: Publish extensions for other users to discover and install.
• Phase 3: Enable monetization for published extensions.

Publishing Your Extension#

While direct publishing of extensions is not yet supported, we are actively looking for developers interested in sharing their creations with the Delver community. If you have an extension you’d like to publish, please contact us with information about what you’ve built.

Here are some guidelines for publication to keep in mind:

• Strive for perfection. Your extensions should be useful, simple, and focused.
• Write clearly. We value straightforward communication over marketing jargon.
• Respect your user’s intelligence.
• Make something people want.