GuidesWeb SDK 2.0REST API 2.0SCIM APILive EmbedChangelogRoadmap
My Apps

Live Embed reference

A reference with an overview of the arguments of the miroBoardsPicker.open method: what they are, what values they accept, and how to pass them when using the method.

Suggest Edits

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

To get an idea of the possibilities, have a look at the Embed Miro section on the Miro Marketplace.

BoardsPicker reference

The BoardsPicker component has a core method: miroBoardsPicker.open.
This reference gives an overview of the arguments that the miroBoardsPicker.open method can take: what they are, what types and values they accept, what they do, and how to pass them when using the method.

The miroBoardsPicker.open method takes a single argument: options.
The options object has the following properties:

clientId

(required)

The unique Client ID of the app that requests user authorization.
To obtain an app client ID:

  1. In Miro, go to your apps.
  2. In the Created apps section, click the app that you want to obtain the client ID for.
    The client ID is displayed in the App Credentials section.

Example:

clientId: "3074451123581321347"

action

(required)

Defines the way in which BoardsPicker enables selecting and sharing a board when it's embedded in a website.
Allowed options:

Example:

action: "select", // Or: "access-link"

select

action: "select" enables selecting a board to share and embed it on a website.
If the request is successful, the function passed to the success property returns JSON-formatted details of the board selected with the BoardsPicker component.

Example:

selectedBoard = {
    "id":"uXjVOD9zD_k=",
    "name":"Demo App",
    "viewLink":"https://miro.com/app/board/uXjVOD9zD_k="
}
  • id is the unique identifier of the selected board.
  • name is the human-friendly name of the board.
  • viewLink is a URL link to the selected board.
    You can pass it to an iframe to embed the board on a website.

For more information about the response to a call with action: "select", see
Response for action: 'select'.

access-link

action: "access-link" enables selecting a user access level to the board being shared and embedded on a website.
The access level applies to all users accessing the embedded board, regardless of their individual, specific user access rights.

If action is set to access-link, the BoardsPicker response includes the same properties that the select action type returns, as well as the accessLink, accessLinkPolicy, and embedHtml additional properties:

selectedBoard = {
    "id":"uXjVOD9zD_k=",
    "name":"Demo App",
    "viewLink":"https://miro.com/app/board/uXjVOD9zD_k=...",
    "accessLink":"https://miro.com/app/live-embed/...",
    "accessLinkPolicy":"EDIT",
    "embedHtml":"<iframe class=\"miro-embedded-board\" src=\"https://miro.com/app/..."></iframe>"
}
  • accessLink defines the URL link pointing to the selected board.
  • accessLinkPolicy sets the user access level for the shared embedded board.
    Allowed values, from most to least restricted:
    • private
    • comment
    • view
    • edit
  • embedHtml is an iframe element that enables linking to the selected board so that you can embed it directly into your website.
    This iframe element must include the miro-embedded-board CSS class.

For more information about the response to a call with action: "access-link", see
Response for action: 'access-link'.

success

(required)

success takes a callback function that executes upon a successful BoardsPicker interaction (users can select and share a board.)
When a user selects a board and successfully completes an interaction with the BoardsPicker component, the callback returns the details of the specified board.

Example:

success: function(selectedBoard) {
  console.log(selectedBoard)
},

cancel

(optional)

cancel takes a callback function that executes when users cancel the BoardsPicker interaction.
When a user cancels the operation, they close the BoardsPicker component without selecting a board.

Example:

cancel: function() {
  // Do something
},

error

(optional)

error takes a callback function that executes when the BoardsPicker interaction fails (users cannot select or share a board.)
This scenario can occur when the BoardsPicker component encounters an issue that prevents users from successfully selecting a board.

Example:

error: function(err) {
  console.log(err)
  // Do something...
},

windowRef

(optional)

windowRef sets a URL link to a currently open browser window.
The URL referenced here points to the browser window to embed the selected board in.

Example:

function onClick() {
  miroBoardsPicker.open({
    windowRef: windowRef, //Provide opened window reference
    // Calculate popup window dimensions and position.
    const pos = {left, top}
    const size = {width, height}
  
    const windowRef = window.open(
      '',
      '_blank',
 `width=${size.width},height=${size.height},left=${pos.left},top=${pos.top},menubar=0,toolbar=0,location=0,personalbar=0,status=0`
    )
  })
}

allowCreateAnonymousBoards

(optional)

If allowCreateAnonymousBoards: true, it allows unregistered users to create and interact with a new temporary Miro board.
When it's set to true, you must also pass a valid access token with getToken.

Example:

function onClick() {
  miroBoardsPicker.open({
    clientId: '...', // 1) Put your 'clientId' here.
    action: 'access-link',
    allowCreateAnonymousBoards: true, //2) Enable this option 
    getToken: () => getTokenFromServer(), // Provide token in async way
    success: data => {
      console.log('on success', data)
      document.querySelector('#container').innerHTML = data.embedHtml
    },
    
    error: e => {
      console.log('on error', e)
    },
    
    cancel: () => {
      console.log('on cancel')
    },
    
    windowRef: windowRef, // Link to an open popup window 
  })
}

getToken

(required if allowCreateAnonymousBoards: true. Otherwise, optional)

When using anonymous boards, you must provide a JSON Web Token (JWT) from your application’s backend to the BoardsPicker component.
This token enables new boards for the integration.getToken method.

Example:

// Type: () => Promise<string>
function getTokenFromServer() {
  //Get JWT token from your server. Read more about JWT https://jwt.io/
  return fetchPost('https://example.com/token-for-integration-with-miro')
}

🚧

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>

See also

Updated 4 days ago

Did this page help you?