Understanding custom web widget sharing with other users
Hi Miro team,
I’m currently working on a research project exploring the ways to enhance the functionality of Miro boards for SLT practitioners.
I’ve been trying out some of the sample code for making custom web widgets with some success. I’ve been able to make several widgets that work in the Dev Team environment and have also been able to publish them to other boards. However, the other users of the boards are unable to use them. I’ve read all the documentation online, but am still unclear about the steps to make my widgets work for others.
My code is published via GitHub pages at: https://newcastlerse.github.io/miro
I’ve recreated the 'implicit-flow-example' from the miroapp/app-examples repo. This given as an example on the page: https://developers.miro.com/docs/how-to-start#section-3-install-your-web-plugin-to-any-miro-user. On the Dev Team board, I get a pop-up that I click to authorise the widget and it clears the board of all content. My understanding of the implicit-flow-example is that a token is exchanged between GitHub pages and the board.
In the section titled 'Make your web-plugin available to any Miro user' it states 'To share your app with other Miro users, you must build a URL in the following format:'
client_id – Your application's Client ID, which is given in the settings for your app. redirect_uri – The URL to which the Miro will redirect the user's browser after authorisation has been granted by the user.
The documentation suggests that 'You can then distribute this link to your users, which they can use to install your app.' It doesn't describe how this is actually done, I'm sure I'm missing something probably obvious to others!
I can provide the details of my client ID, but I'm unclear what the redirect_uri should be. In my own 'implicit-flow-example' code I use a link to the hosted auth-success.html file.
I've assumed that this might be able to be used in the authorize link and I’ve tried setting the redirect part of the url to: redirect_uri=https://newcastlerse.github.io/miro/auth-success.html and setting this as the Redirect URL at the build app page: https://miro.com/app/settings/user-profile/apps. I’ve tried to republish the app to Dev Team, but my board users are getting an error with the GitHub pages site.
Are the two redirect_uris unrelated, so I need to reference a different URL? If so, what should it be? Does the Redirect URL at the build app page need to be set in this way first, so that others can install it themselves and are they able to do that, given that I’ve already installed it to Dev team myself?
I’m a newbie to Miro and am excited as to the potential of custom widgets, but I need a little more instruction on how to set things up.
Many thanks
Rebecca
Page 1 / 1
Just for language clarity sake:
I think by ‘web widget’ you mean to say ‘web plugin’. The ‘plugin’ is the app that you make that gets iFramed into a UI endpoint of Miro UI. Miro uses a different term of ‘widget’ to refer to any item that gets created on to the board (shapes, stickies, cards, images, etc).
A plugin can create, destroy or modify widgets.
Thanks Max, for clarfiying the terminology!
@Becky I hope this might be helpful.
Here’s my understanding of the user auth logic.
A member of a team on a Miro account can authorize aplugin for a team.
But each member of the team has toauthorize that plugin for their individual usage in that team. Took us a while to figure that out...
I think Miro is striking a middle ground of making it easy to authorize an app for a whole enterprise but also leave TOS agreements and data-access authorization to pass down to the end user.
Here’s a peak into one of my plugins that people can install (TagConnector) with working Redirect URI’s -- exposing the parts of it that relate to your question. It might not be super clear from just this… If you have more questions -- feel free to keep the convo going below. Hopefully we can take the mystery out of this for future devs.
index.js
Note: builder.html is the html that gets iframed in my case. Its the main app view/startpoint.
not-authorized.html
truncated up top
Host site start point: is index.html
‘Build App Page’ ‘Redirect URIs’:
I think you’ll need all three(?) - and maybe(?) in this order… this works for us
The install link you send around is the third one -- the one that starts with a query to Miro servers, passing in your plugin’s “client id” … and ends at “auth-success.html”
If a person is not currently logged in to Miro / in a Miro logged-in session… it will ask them to login to Miro or sign up. Then it will ask them to authorize the plugin and send them to ‘auth-success.html’
Alternatively: if you’ve installed the plugin for people on a team your on … the plugin will show up as an icon in their toolbar/respective UI endpoint (based on their ‘team id’) and when they click it, it will send them to “not-authorized.html”(see above) which has a button that runs miro.authorize() passing in the options config object which sets the redirect URI to auth-success.html.
Its all about getting to auth-success.html
Hi @Max Harper,
thanks so much for taking the time to explain this clearly and providing the screen shots!
I’ve replaced my hardcoded url in the not-authorised.html file back to ‘window.location.host’ and have supplied the 3 redirect URLs on the Build App page. It still works correctly for me, I now just have to get my team members to test it.
Thanks as well for explaining the two different scenarios of user authorisation. In my case, the plug-in has a toolbar icon, so I’ll assume that as long as it’s installed to a shared board, it’ll behave the same way for others as it does for me and they’ll just need to authorise it.
It looks like I was pretty close and my miro authorisation url was correct, however, I wouldn’t have guessed that I needed multiple redirect urls to get it to work!
Fingers crossed, all will be well on team testing. If not - I may be back to check out a few details!
cheers
Becky
See what you discover on the ‘shared board’ front. I found that: If the board is shared because users are members of a ‘team’ in Miro it will show up in the “...” of the toolbar UI. But sharing a board (where you see the plugin) with ‘guest editors’ outside of a team - they will not see the plugin on the board UI. Reason-being: Plugins are installed to teams and people not boards. Maybe I did something wrong… but that was my experience.
The plan I have for distribution of the plugin before an event of collaborators who are ‘shared editors’ is to put the plugin install link in the board, share the board to guest editors, and have them click the link in the board.
Hi again @Max Harper
so - something still isn’t right. The user testing for me is a Team Member in the Dev team group. She can see the plugin icon, but gets a 404 error on clicking it. I agree that the plugin is assigned to teams(board groups?) rather than individual boards. Once installed to a team, the icons seem appear on every board as a default.
My user sent me a screen shot of her browser dev tools. Clearly, she’s failing to reach auth-success.html, because she’s not reaching not-authorised.html successfully. I’m not sure if this is her not-authorized request, or her token request shown. My token request looks like this, when I use the plugin myself, except I have the access token returned successfully.
Structurally, i don’t think there’s much difference between your code snippets and mine. All my plugin does is clear the board of any existing widgets, so I’m not sure if anything gets ‘iframed’ in the way your builder.html contents is rendered in a sidebar. (Please correct me if I’ve misunderstood this!)
Just as an aside, neither of those numbers I’ve obscured in the pic above are my client id, now I’ve checked them.
main.js
This is my code in main.js which is referenced in board-cleaner.html, which is the link I published as the web plugin link on the Build App page.
Any thoughts?
cheers
Becky
Not sure if this is the exact issue. but...
It looks like you don’t have a “not-authorized.html” page… Which is the page that users see when someone on their team installed the app, and now they see the app icon on their toolbar and click it. That click initiates a check with Miro to see if that user has authorized that app, if “NO” then it redirects to thenot-authorized.html page.
My not-authorized.html page looks like this.
and the code is
Remember: a Miro user can install an app for a whole team and the app icon will show up in other teammates’ UI. But their click of that icon will redirect to the authorize-this-app-page called “not-authorized.html” with a button for auth-ing. What’s difficult / awkward / non-intuitive as single dev, is testing that user’s experience, because you have to go out and test as a ‘teammate’ of yourself. Plus the flow of you installing and them seeing but having to auth is non-intuitive at first.
Also weird, is that the first to install for a team is ‘authorizing’ on a page made by Miro. That’s the one with the redirect-URL placed into the ‘Make app” page… BUT all the subsequent team-members have to auth on a page that you’ve made. not-authorized.html
Maybe not-authorized and not-authorised is spelling issue somewhere in all this..? (given US v UK spelling of that…?
Maybe also not-authorised.html is not in the right place in directory/path ?
I hope this works for you. Sharing Miro apps is so rewarding. Magic!
I’m heading backpacking for a couple days. So Monday afternoon I’ll check back in. Good luck.
Hi @Max Harper, this is puzzling..
this is my highly unoriginal not-authorized.html file.
not-authorized.html
It’s at the project root level with auth-success.html and board-cleaner.html. I’ve definitely used the US spelling. It is pretty much verbatim from:
If the Miro board has to go to not-authorized before auth-success, then I would have thought it might make sense to register not-authorized.hml as an redirect_uri endpoint as well? However, you’ve said this isn’t the case for you? I’ve tried it regardless, will get it tested again today hopefully.
Ok, I’ve had a an update - it still produces a 404 error. Is it possible to log a ticket for Miro issues or is that only for professional users? I’ve only a few weeks to help these guys….
@Becky
GOOD NEWS:
Found your github page with ‘install link’ installed the app successfully on my board via that link/route and it worked flawlessly. It works both on paid account and not-paid account.
SO… the error must be isolated to the ‘not-authorized’ flow (WHICH… is only for users who have had the app ‘installed’ by another teammate to their ‘Miro team’.
PROBLEM GETTING FURTHER ISOLATED:
I can point you to a Miro platform person… let’s first see if we can get clear on what to tell them is going wrong.
Which page/upon which event are you getting 404 error?
Your user has the app ‘installed’ (by you, a member of their team) so they are seeing your app’s circular Miro UI icon… this means that board-cleaner.html and main.js are loading properly by Miro. In main.js … miro.isAuthorized() is returning false so… the modal window opens and it loads ‘not-authorized.html -->
Is it the request for not-authorized html which is returning the 404 error? This would be the first thing the user sees on the modal…
OR, is the user seeing not-authorized html and then clicking the ‘authorize’ button and then getting a 404 response as it tries to load ‘auth-success.html’ ?
Hi @Max Harper ,
excellent news that you got it working! My apologies for having to ask, but - can you spell out exactly the process you used to install it yourself on your boards? This is another grey area for me.
So far, I’ve only installed the plugin to the Dev Team and in fact, I want to use it with a different team, so it sounds like this might be possible without me having to do much more...
To find out the answer to your last question, (where is the code returning the 404 error) I think I’ll have to get my tester to share her screen so I can watch what happens in the dev tools. I don’t suppose it’s because Dev Team is really just a sandbox?
Thanks again for taking the time to help!
--- I can check on the ‘sandbox of dev team’ question… but I’m pretty sure that’s not the issue… is your tester a ‘member’ of the dev team.
So… It looks like you moved your install/OAuth link from your readme.md in your github page?? Maybe you can share ‘board cleaner’ link again..? This is where I found ‘board cleaner’ the app yesterday.
It looked like these steps but asked to and installed “Board Cleaner” (not “Get all widgets”):
We could video meet and walk through this if that would be helpful.
______________________
@Max Harper
Ah thanks Max, so you went into incognito mode on the browser and then pasted the redirect link! This then asked you to log into Miro and part of that process was that you were asked to authorise the plugin!
A few interesting things here; the link on the github page originally went to a plugin called Get All Widgets, the client id for that app ended in 27215. I updated it a few days ago. This is the link for board cleaner authorisation. Maybe it was cached when you went to it?
I’m happy to do a video chat if you’d like, though i’m busy after 3pm and i’m on leave Fri-Mon. I’ll see if i can get my helper to test this out and let you know how we get on!
@Max Harper
I’ve just found out the web plugin works for my team member, now we know what to do!
Thanks so much for all your time and effort!
I’ve still got about 6 weeks to work on this project, so I might be posting again.
All the best
Becky
@Becky Great news! Can’t wait to see what you create.
Please do share back success or any other challenges or ideas. I hope we can make this forum a place that fuels great creativity.
Who knows … you may be able to help the next person with Oauth/redirectURI issues.
