Guide on plugin IDs and migrating existing modal plugins to panels

Adobe XD UXP Plugin API
1

As a reminder, when you take advantage of new plugin features and APIs, you’ll need to either:

  1. Update your plugin’s minHostVersion so that the plugin doesn’t install or appear in the Plugin Manager to users on older, incompatible versions of XD, or
  2. Check the hostVersion at runtime, and degrade your plugin’s experience if the new APIs aren’t available to the current user.

Since taking advantage of the new Panel APIs requires a manifest change, which is checked at load time, #2 above is not an option.

While the majority of XD users automatically update to the latest version of XD, there are some users - especially in the enterprise - who choose not to upgrade.

We’ve put together a guide for developers who want to continue supporting an existing modal plugin AND take advantage of the new Panel APIs.

Guide on plugin IDs and migrating existing plugins to panels

The following guide will explain how you can maintain an older version of your plugin in the Plugin Manager for users on older versions of XD, while directing users who do upgrade to a new Panel version of your plugin.

Development steps

In addition to porting your code to support panels:

  1. On the Adobe I/O Console, create a new plugin project for your panel plugin and get the project’s plugin ID.
  2. In your manifest.json for the panel plugin:
    1. Use the new plugin ID you received from the Adobe I/O Console
    2. Set the host.minVersion to 21
    3. Give your plugin a new unique name that users will recognize; for example, “My Plugin 2”.
  3. On the Adobe I/O Console, submit your new panel plugin for review and publishing.
  4. (Optional) Let users of your older non-panel plugin know a new version is available as a separate download from the Plugin Manager.
    1. Update your existing modal plugin code to check host application version.
    2. If 21+, notify the user that there’s a new plugin available, with a link to the new plugin in the Plugin Manager using a deep link.

User experience

  • What users of XD 20 and below will experience:
    • No change. Users can continue to use your old plugin as-is, discover it on the Plugin Manager, and get updates to that version of the plugin if you ship any.
  • What users of XD 21 and above will experience:
    • If you don’t update your old plugin to prompt users to install the new version, the user will not know a new version is available.
    • Either way, the user will need to install the new panel plugin via the Plugin Manager.
    • Assuming you haven’t set a maxVersion in your modal plugin’s manifest, the old plugin continues to work as usual.

FAQ

Q: Let’s say we continue using the same plugin ID for the panel version. What happens to my plugin listing in the plugin manager in older versions of XD?
A: The plugin goes away because the plugin’s minVersion is now XD 21.

Q: Is there a chance that two versions of our plugin will be listed in the plugin manager at the same time?
A: Only if you have two plugins with different plugin IDs that support the same version of XD. Say for example, if your modal plugin supports XD 14–21 and your panel supports XD 21 and up, XD 21 users will see both. Note that the new plugin would have a distinct name, like “My Plugin 2” so users can differentiate.

Q: Why can’t we use the same plugin name for both versions?
A: Your UI entry point is set in the manifest, not in JavaScript. This means that you can’t change your entry point at runtime based on host app version number. Further, since XD validates your manifest at load time, if you indicate panel support and attempt to run the plugin in XD 20 or lower, your plugin will be unusable.

1 Like
3

If you have users using XD 20 and they have your plugin installed and then you post a version that requires XD 21 the user using XD 20 will still be able to use your plugin correct but they won’t see that there is an upgrade to the plugin?

4

if you are using the same ID, users will be able to use the plugin in XD 20 and will see that there is an upgrade to the plugin

1 Like