How to Embed a Widget
Updated 2 months ago
Introduction
The Ideanote Idea Widget is a simplified version of the Ideanote Webapp and allows people to submit ideas in a step-by-step flow as well as browse ideas.
You can embed the Idea Widget in any website to provide your customers with Ideanote functionality such as idea and problem submission and browsing of ideas.
You can embed the widget in your website, webapp or mobile app.
Live example
You can choose to embed your widget in 3 different ways:
- Popover: Using a launcher button
- Tile: Using an iFrame (like the above example)
- Full-Screen: Using URL to directly link to your widget
How to add a widget to your website
- In your Workspace navigate to the mission you would like to embed.
- Click the Share button and click Add Widget.
- Choose Popover, Tile or Full-Screen as the widget type.
- Click Setup and Copy Code to copy the widget code to your clipboard.
- If you want to add the widget to your website, go to the web page where you want to add the widget, then paste the code before the closing HTML
</body>tag. Add the code to every web page where you want the widget to appear.
"Tile" code example
Here is an example of an Idea Widget Tile code snippet. It uses an HTML iframe tag and can be used anywhere on your website, webapp or mobile app.
- You can define the width and height properties in pixels or percentage to fit your needs.
- If you want to dynamically show specific missions to a specific audience you can generate a Tile code snippet for each mission. Unique to each widget code is the widget config id (e.g. f92d9611da in the snippet below).
<iframe
allowfullscreen
name="idea-widget-frame"
title="Idea Collection Widget"
style="border: none; width: 320px; height: 450px; box-shadow: 0px 3px 5px -1px rgba(0, 0, 0, 0.2), 0px 5px 8px 0px rgba(0, 0, 0, 0.14), 0px 1px 14px 0px rgba(0, 0, 0, 0.12); border-radius: 0px;"
frameborder="0"
src="https://idea-widget.ideanote.io?config=f92d9611da"
></iframe>
"Popover" code example
Here is an example of an Idea Widget of type "Popover".
<script>
window.ideanoteSettings = {
config: "cf2ef50be3"
};
(function(src){
var a=document.createElement("script");
a.async=!0,a.src=src,document.getElementsByTagName("head")[0].appendChild(a)
})("https://static.ideanote.io/widget/widget.js");
</script>
Preauthentication
It's possible for you to preauthenticate the widget, so that the user doesn't need to log in manually.
You have option to preauthenticate with all widget types (popover, tile and full-screen).
Preauthentication with Tile and Full-Screen types
Preauthentication with the tile and full-screen types is done by adding URL parameters to the idea widget embed URL. The base URL looks like this: https://idea-widget.ideanote.io?config=f92d9611da and is obtained from either the Tile or Full-Screen embed method (see above guide).
How to pre-authenticate the user using JWT
Right now Ideanote only supports pre-authentication using JWT. The issued token must be added to the idea widget URL adding the URL parameter auth.jwt. The resulting URL will end up looking like this:
https://idea-widget.ideanote.io?config=f92d9611da&auth.jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJlbWFpbCI6InJ1bmVAaWRlYW5vdGUuaW8ifQ.ng_ZBZlGWF2_Xy0VbwbK9WybiCsdpaWP-ToBhrCfkwA
JWT Structure
Ideanote expects the structure of the JWT payload to match the following:
sub: user ID in your system (required)email: email of the user that you want to issue the JWT on behalf (required)subdomain: the subdomain of your Ideanote workspace (required)name: full name of the user (optional)avatarUrl: an URL to the avatar of the user (optional)department: The department the user works in (optional).country: The country the user works in (optional)
Preauthentication with the popover type
In order to preauthenticate a widget using the "popover" type, you will have to manually extend your widget code with additional functionality that generates an auth object. The function can be async, so you can call you own authentication service in this step. The auth object will look different based on which authentication method you prefer:
JWT: If you want to preauthenticate with JWT, you will have to return an object with one key called "jwt": { jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI..." }. Please read Preauthentication with Tile and Full-Screen types above for an example of how the JWT-structure should look.
<script defer="" src="https://static.ideanote.io/widget/widget.js"></script>
<script>
async function getAuth() {
// This code will have to use your backend in order to generate a token.
const token = ...
return {
jwt: token
}
}
async function setupWidget() {
window.ideanoteSettings = {
config: "XXXXXX",
preferences: {
auth: await getAuth()
}
}
}
setupWidget();
</script>
OPEN ID: In order to preauthenticate with OpenID, you will have to implement a function that fetches an OpenID code from your own backend. This code is needed to identify and properly authenticate the user. Please see example below for more information.
<script defer="" src="https://static.ideanote.io/widget/widget.js"></script>
<script>
async function getOpenIDCode() {
// This function should be implemented by you.
// The function should return an OpenID code by either generating it on your backend or by showing the user a log in flow.
// The OpenID code looks like this: "vlVaMFkgS7rURaFHjMYCiCOceURfNTTfquYvcSaOWfI"
throw new Error("TODO: Implement");
}
async function getAuth() {
const tokenResult = await fetch("https://api.ideanote.io/v1/session?fields=kind,user.id,sessionToken", {
method: "POST",
headers: {
"content-type": "application/json"
},
body: JSON.stringify({
kind: "OPEN_ID",
spaceProvider: "<ID OF YOUR AUTH PROVEDR>", // You can copy the auth provider ID from security settings on your Ideanote workspace
state: (Math.random() + 1).toString(36).substring(2), // Random string generated by you. This could be any random string generator.
code: await getOpenIDCode()
})
});
const session = await tokenResult.json();
return {
sessionToken: session.sessionToken
}
}
async function setupWidget() {
window.ideanoteSettings = {
config: "XXXXXX",
preferences: {
auth: await getAuth()
}
}
}
setupWidget();
</script>