If your app currently uses the Miro Web SDK v1, it’s time to plan your migration to v2. The Miro Developer Platform 2.0 has reworked and improved the Web SDK, focusing on performance and reliability, as well as the developer experience. This document will outline the changes in certain data objects, and in how those objects relate to others. For a complete map of each v1 endpoint to its v2 counterpart, be sure to check out the reference guide.
In the Miro Web SDK v1, the
widget endpoint was polymorphic – meaning that one endpoint was used to represent all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 SDK, we have replaced this with an independent constructor for each widget (now called "item") type.
The new constructors should feel familiar to you, as they were designed to mostly follow the structure of the type-specific payloads of the previous
board.widgets.create() call. There are two examples below, and for a full map of v1 endpoint calls to their v2 equivalents, please see the reference guide.
|v1 Create Widget call||v2 Equivalent|
|Create an Image
||Create an Image
|Create a Shape
||Create a Shape
In the v2 Web SDK, we have introduced a new method for each object type –
sync(). This method will refresh the content of an object without needing to refresh the entire Miro board. For example, if you are programmatically updating the description of a specific card, you would call
card.sync() at the end of the update call so that the refreshed data is immediately available for a user. To learn more about the
sync() function and see several examples of its usage, check out this guide.
The Miro UI has evolved significantly since the creation of the v1 Web SDK. When building the v2 SDK, we decided to rethink the way we expose extension points. The goal is to create consistency for the user experience so that all web applications feel like a natural extension of the Miro product, and all apps have an intuitive pattern.
Unfortunately, this means that some options that were available to developers in v1 are no longer available in v2, such as the bottom panel and the left sidebar. As of today, we provide developers with two options: the app panel (also known as the left panel) and the pop-up modal.
- The app panel ("Panel") should be used for the majority of your application's interactions, and can be extended to provide multiple views for the user, depending on the context of your app.
- The pop-up modal ("Modal") steals the focus of the browser window, and should be used for more visually-intensive user interactions (such as scrolling through their third-party data, or configuring settings and customizations, etc.).
We will be adding new extension points over time, and we will continue to share updates as we consider the design implications of each new option. There are several feature requests already noted on our roadmap, and we encourage you to add your votes and subscribe to future updates. You’re also welcome to raise any questions or concerns in our developer Discord or on our community forum.
Several changes were made to improve the developer experience or to introduce consistency between the Web SDK and REST API. These changes include:
- With v2, authentication is now handled automatically when a user clicks on an app icon, meaning developers no longer need to explicitly invoke an authorization flow.
- All experimental endpoints have been removed.
- App names and app icons will now be managed in App Settings. There is no longer a programmatic way to update either the App Name or the App Icon.
- Some endpoints in the v1 SDK were designed to support Enterprise accounts, such as
account.get(). These have been removed from the v2 Web SDK, and any Enterprise-based changes should be managed through the REST API.
The following items currently have no equivalent in the Miro Web SDK v2:
- Certain item properties, such as border color and vertical alignment.
- App notifications, including error notifications, are not currently available in v2.
- Metadata (also referred to as Storage) is available at the board level, but is not yet available at the widget level.
Updated 10 months ago