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.
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
clientId
(required)
The unique Client ID of the app that requests user authorization.
To obtain an app client ID:
- In Miro, go to your apps.
- 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
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
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
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 themiro-embedded-board
CSS class.
For more information about the response to a call with action: "access-link"
, see
Response for action: 'access-link'
.
success
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
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
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
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
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
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 theaccess-link
action type don’t load.
To solve the issue, you can override thereferrerpolicy
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