The Portal is a great way to engage your accounts by validating ideas and collecting upvotes and feedback. The Portal can be shared with customers, which is great for Customer-facing teams like customer success, sales, and support, who want to point customers in the right direction for leaving feedback and also see what your product team plans. Embed your Portal where your customers already spend time. It'll be even easier for them to upvote ideas you're considering, review your planned features, and see what you've recently launched.
In this article:
- Embedding your Portal in your website
- Embedded Portal configuration options
- Setting up user identity verification
Embedding your Portal in your website
We embed the Portal with iframes, so it will be necessary to generate some kind of URL to point to your Portal.
- On your Portal, select Share to ensure share settings are set to Private link or Public link.
- From the Embed tab, copy & paste the HTML embed snippet into your application.
Note: Sharing a portal publicly will allow search engines to index your portal links and they will be visible via a Google search.
Note: The private link sharing option allows anyone with the link to access it.
Embedded Portal configuration options
When embedding your Portal, you may want to customize its appearance to match your application and branding.
In addition to standard customizations (customize primary color, remove Productboard branding) available in Portal settings, additional options are available for embedded Portals.
Removing the logo from the header
Use URL parameter hide_logo = 1:
<iframe src="https://portal.productboard.com/u99vquqlpsyckypjrmtbf3sj?hide_logo=1" frameborder="0"></iframe>
Removing the entire header
Users can submit a new idea if this option is enabled in Portal settings. The button will be relocated from the header if it's been hidden.
Use URL parameter hide_header=1:
<iframe src="https://portal.productboard.com/u99vquqlpsyckypjrmtbf3sj?hide_header=1" frameborder="0"></iframe>
Adjust the height and width
If your Portal size is not ideal, you may adjust the height and width by using height and width parameters in either pixels (px) or percentage (%):
<iframe src="https://portal.productboard.com/u99vquqlpsyckypjrmtbf3sj" frameborder="0" height=100% width=100%></iframe>
Removing the user avatar
This is only hidden for users authenticated by SSO (see below).
Setting up user identity verification
Productboard requires users submitting feedback to verify their identities via email. That's because feedback tends to be more valuable when you know who it's coming from. Plus, piercing the haze of anonymity tends to improve quality of feedback.
Single Sign-on (optional)
If you've embedded your portal somewhere that requires authorization to access (like an app that people sign into to use), you can save your users the trouble of having to prove their identities a second time via email by enabling Single Sign-On. Of course, this will only work if they're already logged in to your application.
Warning: THIS IS NOT A SECURITY MEASURE LIKE SAML SSO. It's for the convenience of your customers and other regular users who access your portal through a front-end interface. Portal SSO does not restrict portal access in any way. You cannot use it to require Productboard workspace membership for access (that is, you can't use it to make your Portal internal-only).
Note: When users are authenticated via SSO, their avatar will automatically be hidden on the embedded Portal, as it's assumed it may already be visible in your application.
Enable Portal SSO: Steps for your developer
- Obtain the private key: In Productboard, on your Portal, select Share.
- On the Embed tab, copy the private key.
- When a user wants to use the Portal, send a request to your server to generate an SSO token using the snippet below.
- Install a JWT library. (We use JSON Web Tokens to authenticate your users securely, but you can use whatever library best suits you.)
- Generate tokens on your server using code similar to the example below.
var jwt = require('jsonwebtoken');
var PrivateKey = 'YOUR_PRIVATE_KEY';
function createProductboardToken(user) {
var userData = {
email: user.email,
id: user.id,
name: user.name,
company_name: user.company_name,
company_domain: user.company_domain,
};
return jwt.sign(userData, PrivateKey, {algorithm: 'HS256'});
}
Token behavior
Please note that the user's email address is sent with the jwt token when the iframe is loaded, even if they haven't made any specific action (voting or submitting a new idea) on the page, which would require their email address. When the page loads and the user is automatically authenticated, the email address won't be automatically captured in their Productboard workspace. It is sent but not captured unless they vote on a feature or submit a new idea.
What data is extracted through my token?
Productboard only extracts the following data from the token:
- company_name
- company_domain
- name
Anything else will be ignored when consuming the token.
Example token:
You can examine the expected shape of the data in the JWT token through this explorer.
Mandatory iat claim:
Important: Setting up the mandatory iat claim is required to embed your Portal. Missing these details can lead to issues embedding your Portal.
- Payloads must include an iat claim. Some libraries, like the jsonwebtoken, cited above, generate it automatically. For other libraries, you may need to include it manually. (Tokens without the iat claim will be refused, and the user will not be logged in.)
- iat claim is expected to be the timestamp of issuing the token. If set to a future time, the token will not work.
Optional exp claim:
- All tokens expire after 12 hours from issuance (iat claim), but you may optionally include an exp claim in the payload specifying an earlier expiration time. For sessions longer than 12 hours, it will be necessary to refresh the iframe with a new token regularly. Users who interact with the Portal on an expired token (e.g., submit a vote) must confirm their identities by email before their feedback is logged.
4. Pass the token back to your app and into our iframe, where Productboard will use the token to authenticate your user:
<iframe src="https://portal.productboard.com/u99vquqlpsyckypjrmtbf3sj?token=TOKEN_YOU_GENERATED" frameborder="0"></iframe>
Will a company be created in Productboard when feedback is submitted?
Yes, if you include company_domain in the token, Productboard will create the company if it's not present.
Workaround
If you would like users’ consent for the data that is being sent, we suggest inserting an additional consent step before the iframe loads.
For example, You could have a button like ‘take me to the portal/roadmap,’ which came with a checkbox ‘I acknowledge that my email address will be shared, and that button takes them to the portal page.
Comments
Article is closed for comments.