Live Embed with BoardsPicker for registered users

Embed Miro boards in a website with BoardsPicker to enable setting additional access permissions for registered Miro users when they access the embedded boards.

Integrating Miro’s BoardsPicker into your website enables site users to collaborate and share ideas with Miro boards in real time. BoardsPicker enables users to embed and share the details of their boards on your website for free, without the need for authentication protocols, such as Open Authorization (OAuth) or APIs.

This guide gives an overview of Miro’s BoardsPicker, and it walks you through the steps to implement it.

📘

Request enabling BoardsPicker

To enable the BoardsPicker component for your app for public use, you need to contact Miro by submitting this form.
The procedure takes a couple of days.

BoardsPicker

Miro’s BoardsPicker enables registered users to sign in to Miro, select a board from their user dashboard, and embed it in a web application using an iframe. When selecting the board to embed, BoardsPicker can also enable setting custom user access rights to the embedded board.

Unregistered users can use BoardsPicker to create temporary Miro boards and embed them in the same way. Contact Miro to request this functionality.

Set up BoardsPicker

To use BoardsPicker on your websites, you must enable it on Miro’s side.

  1. Create a developer team in Miro and build an app.
  2. In the app’s settings view, enter the domain names of the websites you want to host BoardsPicker on. Add one domain name at a time. Miro adds the domains to an allow list to prevent other websites from trying to impersonate your app.
    When developing locally, you can use localhost as the domain name.
  3. To enable your integration for public use, submit this form.
    We’ll evaluate your request and green-light your client ID for the relevant use cases.
    Usually, this takes a couple of days.


Figure 1. Enter the domain names of the websites hosting BoardsPicker, one at a time.

Use BoardsPicker in your application

To add the BoardsPicker component to your website, add the following JavaScript snippets to your HTML file.
This is basic boilerplate code to use BoardsPicker. You can customize it to suit your needs.

  • The first script loads Miro’s web SDK for the BoardsPicker component.
    Add the script to the head section of the HTML document:

    <script type="text/javascript" src="https://miro.com/app/static/boardsPicker.1.0.js"></script>
    
  • In the second script, the miroBoardsPicker.open method launches BoardsPicker, and it opens the BoardsPicker component in a modal.
    miroBoardsPicker.open must be initiated by a user-initiated event, such as a click or a tap. This ensures that the user consents to opening the modal. Otherwise, web browsers may block the action.
    Add the script to the body section of the HTML document:

    <script>
      function onSomeButtonClick() {
        miroBoardsPicker.open({
          clientId: 'client_id_from_your_app_on_miro',
          action: 'select',
          success: function (result) {
            console.log(result)
          }
        )
      }
    </script>
    

For more information about arguments that the miroBoardsPicker.open accepts, see Miro Live Embed reference.

Choose the action type

The BoardsPicker component provides two actiontypes: select and access-link.

  • select enables users to select a board from the app panel.
    The response returns a URL pointing to the selected board. For example, you can use this URL to generate an embed link.
    The shared board has the same access permissions as the original board.

  • access-link enables users to select a board from the app panel, set additional access permissions, and then share it.
    The shared board may have different, additional access permissions compared to the original board.

💡 Try it in the demo 👇:

The source code of the demo is available on our GitHub repository.

Handle the response

On a successful call:

  • This triggers executing the success callback function.
  • The callback function is called with a JSON payload containing the details of the board that was selected with BoardsPicker.

Response for action: 'select'

If action is set to select, the response returns the details of the selected board, such as its name, ID, and a URL that links to the board.
You can use the URL and the board ID to create a direct link, which you can then include in an iframe to embed the board on your website.

Example:

<script type="text/javascript" src="https://miro.com/app/static/boardsPicker.1.0.js"></script>
<script>
  function onSomeButtonClick() {
    miroBoardsPicker.open({
      clientId: "<your_app_client_id>", // Replace it with your app Client ID
      action: actionSelect.value,
      success: (data) => {
        document.querySelector(".container").innerHTML = `
          <iframe
            class="iframe"
            width="768"
            height="432"
            src="https://miro.com/app/live-embed/${data?.id}/"
            frameborder="0"
            scrolling="no"
            allowfullscreen
          ></iframe>`;
      }
    }
  }
</script>

This is the result:


Figure 2. BoardsPicker implementation with action type set to select.

Response for action: 'access-link'

If action is set to access-link, the response returns the of the selected board.
The response includes:

  • accessLink with the URL link pointing to the selected board.
  • accessLinkPolicywith the user access level for the shared embedded board.
  • embedHtml with the complete HTML iframe markup to embed the board in an HTML document on a website.

This option is a straightforward approach to embedding a board on your website with BoardsPicker.

Example:

<script type="text/javascript" src="https://miro.com/app/static/boardsPicker.1.0.js"></script>
<script>
  function onSomeButtonClick() {
    miroBoardsPicker.open({
      clientId: "<your_app_client_id>", // Replace it with your app Client ID
      action: actionSelect.value,
      success: (data) => {
        document.querySelector(".container").innerHTML = data?.embedHtml;
      }
    }
  }
</script>

🚧

If your website has a policy for blocking Referer information, boards embedded with the access-link action type don’t load.
To solve the issue, you can override the referrerpolicy attribute inside the iframe HTML element on your site.

Example:

<iframe src="https://miro.com/app/..." referrerpolicy="no-referrer-when-downgrade"></iframe>

This is the result:


Figure 3. BoardsPicker implementation with action type set to access-link.

Let's wrap up

BoardsPicker lets you integrate Miro’s collaborative features into your websites. It enables your users to work, collaborate, and share ideas in real time, all with a few lines of code.

See also